Better documentation of helper and setup files

[jennybc]

Working on the testing chapter of R Packages has made me think that the "special files" of testthat are under-documented.

It's not very easy to find out that they exist or to get advice on how best to use them.

I suspect there should probably be a vignette for this.

As it stands, the only docs I find are here in a "Special files" section that appears in the help for test_file() and is inherited into the help for test_package()/test_local()/test_check():

https://testthat.r-lib.org/reference/test_file.html#special-files

Below I'm going to paste some material I originally wrote for the revision of the testing chapter of R Package, but that feels too detailed. Maybe it can be used in testthat.

[jennybc]

Setup and teardown

Sometimes there is truly global test setup that would be impractical to build into every single test and that might be tailored for test execution in non-interactive or remote environments.

Examples:

• Turning off behaviour aimed at an interactive user, such as messaging or
  writing to the clipboard.
• Loading a credential for auth.
• Setting up a cache folder.

Put such code in tests/testthat/setup.R.
In fact, any file in that directory whose name starts with "setup" is treated as a setup file.
Setup files are run by testthat before running whole test files.
Note that setup code is not run by devtools::load_all().

If any of your setup should be reversed after test execution, you should also include the necessary teardown code in setup.R.
We recommend maintaining teardown code alongside the setup code, in setup.R, because this makes it easier to ensure they stay in sync.
The artificial environment teardown_env() exists as a magical handle to use in withr::defer() and withr::local_*() / withr::with_*().
A legacy approach (which still works, but is no longer recommended) is to put teardown code in tests/testthat/teardown.R.

Here's a setup.R example from the reprex package, where we 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 concise and use the pre-built function withr::local_options() and pass teardown_env() as the .local_envir:

withr::local_options(
  list(reprex.clipboard = FALSE, reprex.html_preview = FALSE),
  .local_envir = teardown_env()
)