Need help with vdiffr?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

157 Stars 24 Forks Other 356 Commits 8 Opened issues


Visual regression testing and graphical diffing with testthat

Services available


Need anything else?

Contributors list


R-CMD-check Codecov test coverage CRAN status <!-- badges: end -->

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

in your test files.

1) Run


1) If

detected new snapshots or changes to existing snapshots, run
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

expectation. It takes as arguments:
  • A title. This title is used in two ways. First, the title is standardised (it is converted to lowercase and any character that is not alphanumeric or a space is turned into a dash) and used as filename for storing the figure. Secondly, with ggplot2 figures the title is automatically added to the plot with

    (only if no ggtitle has been set).
  • A figure. This can be a ggplot object, a recordedplot, a function to be called, or more generally any object with a


The snapshots are recorded in subfolders of the


Note that in addition to automatic ggtitles, ggplot2 figures are assigned the minimalistic theme

(unless they already have been assigned a theme).


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:

  • Some of the plot components depend on random variation. Try setting a seed.

  • The plot depends on some system library. For instance sf plots depend on libraries like GEOS and GDAL. It might not be possible to test these plots with vdiffr (which can still be used for manual inspection, add a [testthat::skip()] before the

    call in that case).

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

and should be displayed on Travis.

You can also set the

environment variable with
to unconditionally (also interactively) log failures in the file pointed by the variable.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.