More documentation on snapshot cleanup (#2194)

Fixes #1615

Author: hadley

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:

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.

man/expect_snapshot.Rd

@@ -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.