1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/snapshot-file.R
\name{expect_snapshot_file}
\alias{expect_snapshot_file}
\alias{announce_snapshot_file}
\alias{compare_file_binary}
\alias{compare_file_text}
\title{Snapshot testing for whole files}
\usage{
expect_snapshot_file(
path,
name = basename(path),
binary = lifecycle::deprecated(),
cran = FALSE,
compare = NULL,
transform = NULL,
variant = NULL
)
announce_snapshot_file(path, name = basename(path))
compare_file_binary(old, new)
compare_file_text(old, new)
}
\arguments{
\item{path}{Path to file to snapshot. Optional for
\code{announce_snapshot_file()} if \code{name} is supplied.}
\item{name}{Snapshot name, taken from \code{path} by default.}
\item{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{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{compare}{A function used to compare the snapshot files. It should take
two inputs, the paths to the \code{old} and \code{new} snapshot, and return either
\code{TRUE} or \code{FALSE}. This defaults to \code{compare_file_text} if \code{name} has
extension \code{.r}, \code{.R}, \code{.Rmd}, \code{.md}, or \code{.txt}, and otherwise uses
\code{compare_file_binary}.
\code{compare_file_binary()} compares byte-by-byte and
\code{compare_file_text()} compares lines-by-line, ignoring
the difference between Windows and Mac/Linux line endings.}
\item{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{variant}{If not-\code{NULL}, results will be saved in
\verb{_snaps/\{variant\}/\{test\}/\{name\}.\{ext\}}. This allows you to create
different snapshots for different scenarios, like different operating
systems or different R versions.}
\item{old, new}{Paths to old and new snapshot files.}
}
\description{
Whole file snapshot testing is designed for testing objects that don't have
a convenient textual representation, with initial support for images
(\code{.png}, \code{.jpg}, \code{.svg}), data frames (\code{.csv}), and text files
(\code{.R}, \code{.txt}, \code{.json}, ...).
The first time \code{expect_snapshot_file()} is run, it will create
\verb{_snaps/\{test\}/\{name\}.\{ext\}} containing reference output. Future runs will
be compared to this reference: if different, the test will fail and the new
results will be saved in \verb{_snaps/\{test\}/\{name\}.new.\{ext\}}. To review
failures, call \code{\link[=snapshot_review]{snapshot_review()}}.
We generally expect this function to be used via a wrapper that takes care
of ensuring that output is as reproducible as possible, e.g. automatically
skipping tests where it's known that images can't be reproduced exactly.
}
\section{Announcing snapshots}{
testthat automatically detects dangling snapshots that have been
written to the \verb{_snaps} directory but which no longer have
corresponding R code to generate them. These dangling files are
automatically deleted so they don't clutter the snapshot
directory. However we want to preserve snapshot files when the R
code wasn't executed because of an unexpected error or because of a
\code{\link[=skip]{skip()}}. Let testthat know about these files by calling
\code{announce_snapshot_file()} before \code{expect_snapshot_file()}.
}
\examples{
# To use expect_snapshot_file() you'll typically need to start by writing
# a helper function that creates a file from your code, returning a path
save_png <- function(code, width = 400, height = 400) {
path <- tempfile(fileext = ".png")
png(path, width = width, height = height)
on.exit(dev.off())
code
path
}
path <- save_png(plot(1:5))
path
\dontrun{
expect_snapshot_file(save_png(hist(mtcars$mpg)), "plot.png")
}
# You'd then also provide a helper that skips tests where you can't
# be sure of producing exactly the same output
expect_snapshot_plot <- function(name, code) {
# Other packages might affect results
skip_if_not_installed("ggplot2", "2.0.0")
# Or maybe the output is different on some operation systems
skip_on_os("windows")
# You'll need to carefully think about and experiment with these skips
name <- paste0(name, ".png")
# Announce the file before touching `code`. This way, if `code`
# unexpectedly fails or skips, testthat will not auto-delete the
# corresponding snapshot file.
announce_snapshot_file(name = name)
path <- save_png(code)
expect_snapshot_file(path, name)
}
}
|
