diff --git a/R/snapshot-file.R b/R/snapshot-file.R index 4da38f96b..03aa281c6 100644 --- a/R/snapshot-file.R +++ b/R/snapshot-file.R @@ -31,9 +31,14 @@ #' `compare_file_text()` compares lines-by-line, ignoring #' the difference between Windows and Mac/Linux line endings. #' @param variant If not-`NULL`, results will be saved in -#' `_snaps/{variant}/{test}/{name}.{ext}`. This allows you to create +#' `_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.) #' @inheritParams expect_snapshot #' #' @section Announcing snapshots: diff --git a/R/snapshot.R b/R/snapshot.R index 952673bcf..93647d79c 100644 --- a/R/snapshot.R +++ b/R/snapshot.R @@ -53,6 +53,11 @@ #' carefully think about your testing strategy to ensure that all important #' variants are covered by automated tests, and ensure that you have a way #' to get snapshot changes out of your CI system and back into the repo. +#' +#' 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.) #' @param 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. diff --git a/man/expect_snapshot.Rd b/man/expect_snapshot.Rd index f6578e415..1235a0a98 100644 --- a/man/expect_snapshot.Rd +++ b/man/expect_snapshot.Rd @@ -38,7 +38,12 @@ variations for operating system, R version, or version of key dependency. Variants are an advanced feature. When you use them, you'll need to carefully think about your testing strategy to ensure that all important variants are covered by automated tests, and ensure that you have a way -to get snapshot changes out of your CI system and back into the repo.} +to get snapshot changes out of your CI system and back into the repo. + +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{cnd_class}{Whether to include the class of messages, warnings, and errors in the snapshot. Only the most specific diff --git a/man/expect_snapshot_file.Rd b/man/expect_snapshot_file.Rd index 5a2a8cda6..2e31b8ba8 100644 --- a/man/expect_snapshot_file.Rd +++ b/man/expect_snapshot_file.Rd @@ -51,9 +51,14 @@ 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 +\verb{_snaps/\{variant\}/\{test\}/\{name\}}. This allows you to create different snapshots for different scenarios, like different operating -systems or different R versions.} +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{old, new}{Paths to old and new snapshot files.} } diff --git a/man/expect_snapshot_output.Rd b/man/expect_snapshot_output.Rd index 57f638759..64b4ffd4a 100644 --- a/man/expect_snapshot_output.Rd +++ b/man/expect_snapshot_output.Rd @@ -29,7 +29,12 @@ variations for operating system, R version, or version of key dependency. Variants are an advanced feature. When you use them, you'll need to carefully think about your testing strategy to ensure that all important variants are covered by automated tests, and ensure that you have a way -to get snapshot changes out of your CI system and back into the repo.} +to get snapshot changes out of your CI system and back into the repo. + +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{class}{Class of expected error or warning. The expectation will always fail (even on CRAN) if an error of this class isn't seen diff --git a/man/expect_snapshot_value.Rd b/man/expect_snapshot_value.Rd index 785f7459e..f85832d0c 100644 --- a/man/expect_snapshot_value.Rd +++ b/man/expect_snapshot_value.Rd @@ -53,7 +53,12 @@ variations for operating system, R version, or version of key dependency. Variants are an advanced feature. When you use them, you'll need to carefully think about your testing strategy to ensure that all important variants are covered by automated tests, and ensure that you have a way -to get snapshot changes out of your CI system and back into the repo.} +to get snapshot changes out of your CI system and back into the repo. + +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.)} } \description{ Captures the result of function, flexibly serializing it into a text diff --git a/vignettes/snapshotting.Rmd b/vignettes/snapshotting.Rmd index 8548d971a..d0f3019ba 100644 --- a/vignettes/snapshotting.Rmd +++ b/vignettes/snapshotting.Rmd @@ -128,6 +128,8 @@ test_that("bullets", { If this is a deliberate change, you can follow the advice in the message and update the snapshots for that file by running `snapshot_accept("pizza")`; otherwise you can fix the bug and your tests will pass once more. (You can also accept snapshot for all files with `snapshot_accept()`). +If you delete the test, the corresponding snapshot will be removed the next time you run the tests. If you delete all snapshots in the file, the entire snapshot file will be deleted the next time you run all the tests. + ### Snapshot format Snapshots are recorded using a subset of markdown.