testthat 3.0.0


  Hadley Wickham

We’re tickled pink to announce the release of testthat 3.0.0. testthat makes it easy to turn your existing informal tests into formal, automated tests that you can rerun quickly and easily. testthat is the most popular unit-testing package for R, and is used by over 5,000 CRAN and Bioconductor packages. You can learn more about unit testing at https://r-pkgs.org/tests.html.

You can install it from CRAN with:


In this blog post, I want to discuss the two biggest changes: the introduction of the “edition”, which allows us to make breaking changes that you have to specifically opt-in to, and a new family of “snapshot” tests. I’ll also give a quick round up of the other major changes, but you might want to look at the release notes for the full details.

3rd edition

testthat 3.0.0 introduces the idea of an edition. An edition is a bundle of behaviours that you have to explicitly choose to use, allowing us to make backward incompatible changes. This is particularly important for testthat since it’s used by a very large number of packages, and the old edition includes a few design infelicities that we wanted want to fix. Choosing to use the 3rd edition allows you to use our latest recommendations for ongoing and new work, while historical packages continue to use the old behaviour. To use it, and this line to your DESCRIPTION:

Config/testthat/edition: 3

The second edition will never go away, but new features will only appear in the 3rd edition. We don’t anticipate creating new editions very often (maybe once every 5 years at most), and they’ll always be paired with a new major version of testthat, i.e. if there’s another edition, it’ll be the 4th edition and will come with testthat 4.0.0.

The full details of the 3rd edition are described in vignette("third-edition", package = "testthat"). If you’re a heavy testthat user, I strongly recommend reading the vignette. Here are the most important changes:

Snapshot testing

The goal of a unit test is to record the expected output of a function using code. This is a powerful technique because because not only does it ensure that code doesn’t change unexpectedly, it also expresses the desired behaviour in a way that a human can understand. However, it’s not always convenient to record the expected behaviour with code. Some challenges include:

  • Text output that includes many characters like quotes and newlines that require special handling in a string.

  • Output that is large, making it painful to define the reference output, and bloating the size of the test file and making it hard to navigate.

  • Cases where you want to record a mix of printed output, messages, warnings, or errors.

  • Binary formats, like plots or images, which are very difficult to describe in code: i.e. the plot looks right, the error message is useful to a human, the print method uses colour effectively.

For these situations, testthat provides an alternative mechanism: snapshot tests. Instead of using code to describe expected output, snapshot tests (also known as golden tests) record results in a separate human-readable file. Snapshot tests in testthat are inspired primarily by Jest, thanks to a number of very useful discussions with Joe Cheng.

If snapshot tests sound intriguing to you, please read the details in vignette("snapshotting", package = "testthat").

Other improvements


A big thanks to all 64 contributors who helped with this release by discussing problems, proposing features and contributing code: @aalucaci, @andrewmarx, @Anirban166, @benxiahu, @Bisaloo, @boerjames, @brodieG, @c0k3b0y, @Christoph999, @daattali, @damianooldoni, @DanChaltiel, @davidchall, @DavisVaughan, @EdwardJGillian, @emiliesecherre, @gaborcsardi, @gavinsimpson, @gergness, @hadley, @hbaniecki, @hongooi73, @HughParsonage, @jarauh, @jcheng5, @jennybc, @jimhester, @jonkeane, @kevinushey, @khaeru, @kjytay, @kos59125, @krlmlr, @ksvanhorn, @lionel-, @maelle, @manumart, @mardam, @md0u80c9, @melvidoni, @mgirlich, @MichaelChirico, @msberends, @mtkerbeR, @MyKo101, @nbenn, @Nelson-Gon, @njtierney, @noeliarico, @omsai, @pat-s, @psteinb, @salim-b, @SKalt, @stefanoborini, @stufield, @sumedh10, @tanho63, @tbrown122387, @torfason, @torockel, @xiaodaigh, @yitao-li, and @yutannihilation.