R: Snapshot testing for whole files

expect_snapshot_file {testthat} | R Documentation

## Snapshot testing for whole files

### Description

Whole file snapshot testing is designed for testing objects that don't have a convenient textual representation, with initial support for images (`.png`, `.jpg`, `.svg`), data frames (`.csv`), and text files (`.R`, `.txt`, `.json`, ...).

The first time `expect_snapshot_file()` is run, it will create `_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 `_snaps/{test}/{name}.new.{ext}`. To review failures, call `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.

### Usage

    expect_snapshot_file(path, name = basename(path), binary = TRUE, cran = FALSE)

### Arguments

`path` | Path to file to snapshot.
`name` | Snapshot name, taken from `path` by default.
`binary` | If `FALSE`, files are compared line-by-line, ignoring the difference between Windows and Mac/Linux line endings.
`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. Even on CRAN, the expectations will still fail if `x` errors.

### 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

    ## Not run:
    expect_snapshot_file(save_png(hist(mtcars)), "plot.png")

    ## End(Not run)

    # You'd then also provide a helper that skip 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

      path <- save_png(code)
      expect_snapshot_file(path, paste0(name, ".png"))
    }

[Package testthat version 3.0.0 Index]