From f6d294909a3d289d15ab22200ebecc34058b955e Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 14 Aug 2025 08:42:26 -0500 Subject: [PATCH 1/4] Polishing `announce_snapshot_file()` docs --- R/snapshot-file.R | 21 +++++++++++++++++---- man/expect_snapshot_file.Rd | 20 ++++++++++++++++---- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/R/snapshot-file.R b/R/snapshot-file.R index dea4ce474..101d903f1 100644 --- a/R/snapshot-file.R +++ b/R/snapshot-file.R @@ -41,10 +41,23 @@ #' written to the `_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 -#' [skip()]. Let testthat know about these files by calling -#' `announce_snapshot_file()` before `expect_snapshot_file()`. +#' directory. +#' +#' This can cause problems if youre test is conditionally executed, either +#' because of an `if` statement or a [skip()]. To avoid files being deleted in +#' this case, you can call `announce_snapshot_file()` before the conditional +#' code. +#' +#' ```R +#' test_that("can save a file", { +#' if (!can_save()) { +#' announce_snapshot_file("data.txt") +#' skip("Can't save file") +#' } +#' path <- withr::local_tempfile() +#' expect_snasphot_file(save_file(path, mydata()), "data.txt") +#' }) +#' ``` #' #' @export #' @examples diff --git a/man/expect_snapshot_file.Rd b/man/expect_snapshot_file.Rd index 473634109..0f7ad9950 100644 --- a/man/expect_snapshot_file.Rd +++ b/man/expect_snapshot_file.Rd @@ -79,10 +79,22 @@ 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()}. +directory. + +This can cause problems if youre test is conditionally executed, either +because of an \code{if} statement or a \code{\link[=skip]{skip()}}. To avoid files being deleted in +this case, you can call \code{announce_snapshot_file()} before the conditional +code. + +\if{html}{\out{
}}\preformatted{test_that("can save a file", \{ + if (!can_save()) \{ + announce_snapshot_file("data.txt") + skip("Can't save file") + \} + path <- withr::local_tempfile() + expect_snasphot_file(save_file(path, mydata()), "data.txt") +\}) +}\if{html}{\out{
}} } \examples{ From e2aa4ebfa946bde5ab9916cca41e749aba7f08cf Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 14 Aug 2025 08:52:33 -0500 Subject: [PATCH 2/4] Fix example; make CRAN behaviour consistent; early announce --- R/snapshot-file.R | 24 ++++++++++++------------ man/expect_snapshot_file.Rd | 17 ++++++++--------- 2 files changed, 20 insertions(+), 21 deletions(-) diff --git a/R/snapshot-file.R b/R/snapshot-file.R index 101d903f1..61cdaaa2f 100644 --- a/R/snapshot-file.R +++ b/R/snapshot-file.R @@ -51,7 +51,7 @@ #' ```R #' test_that("can save a file", { #' if (!can_save()) { -#' announce_snapshot_file("data.txt") +#' announce_snapshot_file(name = "data.txt") #' skip("Can't save file") #' } #' path <- withr::local_tempfile() @@ -80,21 +80,20 @@ #' } #' #' # You'd then also provide a helper that skips tests where you can't -#' # be sure of producing exactly the same output +#' # be sure of producing exactly the same output. #' expect_snapshot_plot <- function(name, code) { +#' # Announce the file before touching skips or running `code`. This way, +#' # if the skips are active, testthat will not auto-delete the corresponding +#' # snapshot file. +#' name <- paste0(name, ".png") +#' announce_snapshot_file(name = name) +#' #' # 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) #' } @@ -110,14 +109,15 @@ expect_snapshot_file <- function( check_string(path) check_string(name) check_bool(cran) + check_variant(variant) edition_require(3, "expect_snapshot_file()") + + announce_snapshot_file(name = name) if (!cran && on_cran()) { - skip("On CRAN") + return(invisible()) } - check_variant(variant) - snapshotter <- get_snapshotter() if (is.null(snapshotter)) { snapshot_not_available(path) diff --git a/man/expect_snapshot_file.Rd b/man/expect_snapshot_file.Rd index 0f7ad9950..2005f537f 100644 --- a/man/expect_snapshot_file.Rd +++ b/man/expect_snapshot_file.Rd @@ -88,7 +88,7 @@ code. \if{html}{\out{
}}\preformatted{test_that("can save a file", \{ if (!can_save()) \{ - announce_snapshot_file("data.txt") + announce_snapshot_file(name = "data.txt") skip("Can't save file") \} path <- withr::local_tempfile() @@ -117,21 +117,20 @@ 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 +# be sure of producing exactly the same output. expect_snapshot_plot <- function(name, code) { + # Announce the file before touching skips or running `code`. This way, + # if the skips are active, testthat will not auto-delete the corresponding + # snapshot file. + name <- paste0(name, ".png") + announce_snapshot_file(name = name) + # 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) } From 651f2177e007a1addb46066329cff01af63137b0 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 14 Aug 2025 16:02:14 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Douglas Ezra Morrison --- R/snapshot-file.R | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/R/snapshot-file.R b/R/snapshot-file.R index 61cdaaa2f..f9dbc4163 100644 --- a/R/snapshot-file.R +++ b/R/snapshot-file.R @@ -43,7 +43,7 @@ #' automatically deleted so they don't clutter the snapshot #' directory. #' -#' This can cause problems if youre test is conditionally executed, either +#' This can cause problems if your test is conditionally executed, either #' because of an `if` statement or a [skip()]. To avoid files being deleted in #' this case, you can call `announce_snapshot_file()` before the conditional #' code. @@ -90,7 +90,7 @@ #' #' # Other packages might affect results #' skip_if_not_installed("ggplot2", "2.0.0") -#' # Or maybe the output is different on some operation systems +#' # Or maybe the output is different on some operating systems #' skip_on_os("windows") #' # You'll need to carefully think about and experiment with these skips #' From 617abf62d7f3b8b4ce566136b0c759aa71a7e15d Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Thu, 14 Aug 2025 16:03:11 -0500 Subject: [PATCH 4/4] One more typo; re-document --- R/snapshot-file.R | 2 +- man/expect_snapshot_file.Rd | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/R/snapshot-file.R b/R/snapshot-file.R index f9dbc4163..af70a4570 100644 --- a/R/snapshot-file.R +++ b/R/snapshot-file.R @@ -55,7 +55,7 @@ #' skip("Can't save file") #' } #' path <- withr::local_tempfile() -#' expect_snasphot_file(save_file(path, mydata()), "data.txt") +#' expect_snapshot_file(save_file(path, mydata()), "data.txt") #' }) #' ``` #' diff --git a/man/expect_snapshot_file.Rd b/man/expect_snapshot_file.Rd index 2005f537f..5a2a8cda6 100644 --- a/man/expect_snapshot_file.Rd +++ b/man/expect_snapshot_file.Rd @@ -81,7 +81,7 @@ corresponding R code to generate them. These dangling files are automatically deleted so they don't clutter the snapshot directory. -This can cause problems if youre test is conditionally executed, either +This can cause problems if your test is conditionally executed, either because of an \code{if} statement or a \code{\link[=skip]{skip()}}. To avoid files being deleted in this case, you can call \code{announce_snapshot_file()} before the conditional code. @@ -92,7 +92,7 @@ code. skip("Can't save file") \} path <- withr::local_tempfile() - expect_snasphot_file(save_file(path, mydata()), "data.txt") + expect_snapshot_file(save_file(path, mydata()), "data.txt") \}) }\if{html}{\out{
}} } @@ -127,7 +127,7 @@ 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 + # Or maybe the output is different on some operating systems skip_on_os("windows") # You'll need to carefully think about and experiment with these skips