vdiffr

R-CMD-check Codecov test coverage CRAN status

vdiffr is a testthat extension for monitoring the appearance of R plots. It generates reproducible SVG files and registers them as the testthat snapshots.

How to use vdiffr

  1. Add graphical expectations by including expect_doppelganger() in your test files.

  2. Run devtools::test().

  3. If test() detected new snapshots or changes to existing snapshots, run testthat::snapshot_review() to review them.

There may be many reasons for a snapshot to fail. Upstream changes (e.g. to the R graphics engine or to ggplot2) may cause subtle differences in your plots that are not actual failures. For this reason, snapshots do not cause failures on CRAN by default. You will only see failures locally or on CI platforms such as Github Actions.

Adding expectations

vdiffr integrates with testthat through the expect_doppelganger() expectation. It takes as arguments:

The snapshots are recorded in subfolders of the _snaps/ directory.

disp_hist_base <- function() hist(mtcars$disp)
disp_hist_ggplot <- ggplot(mtcars, aes(disp)) + geom_histogram()

vdiffr::expect_doppelganger("Base graphics histogram", disp_hist_base)
vdiffr::expect_doppelganger("ggplot2 histogram", disp_hist_ggplot)

Note that in addition to automatic ggtitles, ggplot2 figures are assigned the minimalistic theme theme_test() (unless they already have been assigned a theme).

Debugging

It is sometimes difficult to understand the cause of a doppelganger failure. A frequent cause of failure is undeterministic generation of plots. Potential culprits are:

To help you understand the causes of a failure, vdiffr automatically logs the SVG diff of all failures when run under R CMD check. The log is located in tests/vdiffr.Rout.fail and should be displayed on Travis.

You can also set the VDIFFR_LOG_PATH environment variable with Sys.setenv() to unconditionally (also interactively) log failures in the file pointed by the variable.