This vignette describes the various special files that testthatunderstands: test, helper, setup/teardown, snapshot, and everythingelse.
These are the bread and butter of testthat. Test files live intests/testthat/, start with eithertest- ortest_, and end with.r or.R. Werecommend organising your test files so that there’s a one-to-onecorrespondence between the files inR/ and the files intests/testthat/ so that (e.g.)R/myfile.R hasa matchingtests/testthat/test-myfile.R. Thiscorrespondence is maintained by functions likeusethis::use_r() andusethis::use_test() andis taken advantage of by functions likedevtools::test_active_file() anddevtools::test_coverage_active_file().
Test files are executed in alphabetical order, but you should striveto avoid dependencies between test files. In principle, you should beable to be run your test files in any order or even at the sametime.
Helper files live intests/testthat/, start withhelper, and end with.r or.R.They are sourced bydevtools::load_all() (so they’reavailable interactively when developing your packages) and bytest_check() and friends (so that they’re available nomatter how your tests are executed).
Helper files are a useful place for functions that you’ve extractedfrom repeated code in your tests, whether that be test fixtures(vignette("test-fixtures")), custom expectations(vignette("custom-expectation")), or skip helpers(vignette("skipping")).
Setup files live intests/testthat/, start withsetup, and end with.r or.R.Typically there is only one setup file which, by convention, istests/testthat/setup.R. Setup files are sourced bytest_check() and friends (so that they’re available nomatter how your tests are executed), but they arenot sourcedbydevtools::load_all().
Setup files are good place to put truly global test setup that wouldbe impractical to build into every single test and that might betailored for test execution in non-interactive or remote environments.Examples:
If any of your setup should be reversed after test execution (i.e. itneeds to be torn down), we recommend maintaining that teardown codealongside the setup code, insetup.R, because this makes iteasier to ensure they stay in sync. The artificial environmentteardown_env() exists as a magical handle to use inwithr::defer() andwithr::local_*(). A legacyapproach (which still works, but is no longer recommended) is to putteardown code intests/testthat/teardown.R.
Here’s asetup.R example from the reprex package, wherewe turn off clipboard and HTML preview functionality during testing:
op<-options(reprex.clipboard =FALSE,reprex.html_preview =FALSE)withr::defer(options(op),teardown_env())Since we are just modifying options here, we can be even more conciseand use the pre-built functionwithr::local_options() andpassteardown_env() as the.local_envir:
withr::local_options(list(reprex.clipboard =FALSE,reprex.html_preview =FALSE),.local_envir =teardown_env())Teardown files live intests/testhat/, start withteardown and end with.r or.R.They are executed after the tests are run, but we no longer recommendusing them as it’s easier to check that you clean up every mess that youmake if you interleave setup and tear down code as described above.
Snapshot files live intests/testthat/_snaps/. Snapshotfile are named automatically based on the name of the test file so thattests/testthat/test-one.R will generatedtests/testthat/_snaps/one.md. Learn more about snapshottests invignette("snapshotting").
Other files and folders intests/testthat/ are ignoredby testthat, making them a good place to store persistent test data.Since the precise location of thetest/testthat/ directoryvaries slightly depending on how you’re running the test, we recommendcreating paths to these files and directories usingtest_path().