% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expect_snapshot_object.R
\name{expect_snapshot_object}
\alias{expect_snapshot_object}
\title{Snapshot testing for R objects}
\usage{
expect_snapshot_object(
  x,
  name,
  writer = save_rds,
  print = FALSE,
  tolerance = NULL,
  ...
)
}
\arguments{
\item{x}{An R object to snapshot. Can be any R object including lists,
models, data.frames, vectors, etc.}

\item{name}{\link{character} snapshot name (file extension added
automatically)}

\item{writer}{\link{function} Function to write the object to a file.
Default is \code{\link[=save_rds]{save_rds()}}.
Other options include \code{\link[=save_json]{save_json()}}, \code{\link[=save_deparse]{save_deparse()}}, \code{\link[=save_csv]{save_csv()}}.
Custom writer functions should accept \code{x} and return a file path.}

\item{print}{\link{logical} whether to print \link[waldo:compare]{waldo::compare} output to R console;
can become very long for complex objects like \link{lm}s}

\item{tolerance}{If non-\code{NULL}, used as threshold for ignoring small
floating point differences when comparing numeric vectors. Only applies
when \code{writer} produces an RDS file (the default); silently ignored for
text-based formats (JSON, CSV, deparse, etc.). See \code{\link[waldo:compare]{waldo::compare()}} for
full details.}

\item{...}{
  Arguments passed on to \code{\link[testthat:expect_snapshot_file]{testthat::expect_snapshot_file}}
  \describe{
    \item{\code{binary}}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use the
\code{compare} argument instead.}
    \item{\code{cran}}{Should these expectations be verified on CRAN? By default,
they are not, because snapshot tests tend to be fragile because they
often rely on minor details of dependencies.}
    \item{\code{transform}}{Optionally, a function to scrub sensitive or stochastic
text from the output. Should take a character vector of lines as input
and return a modified character vector as output.}
    \item{\code{variant}}{If not-\code{NULL}, results will be saved in
\verb{_snaps/{variant}/{test}/{name}}. This allows you to create
different snapshots for different scenarios, like different operating
systems or different R versions.

Note that there's no way to declare all possible variants up front which
means that as soon as you start using variants, you are responsible for
deleting snapshot variants that are no longer used. (testthat will still
delete all variants if you delete the test.)}
    \item{\code{old,new}}{Paths to old and new snapshot files.}
  }}
}
\value{
\link{NULL} (from \code{\link[testthat:expect_snapshot_file]{testthat::expect_snapshot_file()}})
}
\description{
A flexible wrapper around \code{\link[testthat:expect_snapshot_file]{testthat::expect_snapshot_file()}} that allows
snapshotting any R object, not just data.frames. This function provides
a convenient interface for snapshot testing with sensible defaults for
serialization.

When using RDS format (the default), snapshots are compared using
\code{\link[waldo:compare]{waldo::compare()}} which provides rich, visual diffs in
\code{\link[testthat:snapshot_review]{testthat::snapshot_review()}}. This makes it much easier to review
changes to complex R objects.
}
\details{
When using RDS format (the default), snapshots can vary across R versions
and platforms even with fixed serialization versions. Consider using
\code{variant = platform_variant()} for RDS snapshots to handle these
differences, or use text-based formats like JSON or deparse for more
stable snapshots across platforms and versions.

The RDS comparison uses \code{\link[waldo:compare]{waldo::compare()}} internally, which provides
rich visual diffs in \code{\link[testthat:snapshot_review]{testthat::snapshot_review()}}. This is particularly
useful for complex objects like models, nested lists, or data structures
where byte-level comparison would be difficult to interpret.
}
\examples{
\donttest{
# expect_snapshot_object() must be called inside a test_that() block with
# testthat 3rd edition active. Outside a test suite, the snapshot is
# skipped because there is no reference file to compare against.
withr::with_tempdir({
  testthat::test_that("snapshot examples", {
    testthat::local_edition(3)

    # Snapshot a list (RDS format with platform/version variant)
    expect_snapshot_object(
      list(a = 1, b = 2), name = "config", variant = platform_variant()
    )

    # Snapshot a model
    model <- lm(mpg ~ wt, data = mtcars)
    expect_snapshot_object(
      model, name = "model", variant = platform_variant()
    )

    # Snapshot with JSON format (for human-readable diffs)
    # Text formats don't need variants
    expect_snapshot_object(iris[1:5, ], name = "iris", writer = save_json)

    # Snapshot with deparse format
    expect_snapshot_object(
      list(x = 1:5), name = "simple_list", writer = save_deparse
    )
  })
})
}
}
