More details needed about writing tests

[MichaelChirico]

As someone who has (1) written / contributed to dozens of R packages and (2) written 10s of patches to R itself, I am still pretty unclear the "right" way to write tests for R patches.

It would be useful to have this spelled out in more detail in the guide, for example:

• The tests/ folder uses the .R/.Rout system of snapshot tests that will be unfamiliar to many accustomed to other testing frameworks (e.g. testthat, which only recently embraced the usage of snapshot tests & anyway uses a different system for them)
• Spell out when tests should be added to the top-level tests/ folder as opposed to the default package-level /tests/ folders (e.g. src/library/utils/tests)
• The organization of the tests/ directory
• How to decide in which file to write new tests for a given patch

[llrs]

I just remembered this issue after reading a comment on R-bugzilla about adding regression test. The referenced revision 80841 has the following addition to it.

## PR#15628 ebd0() for dpois() [for now] \\  dpois(x, *) for  2\pi x >= DMAX
stopifnot(exprs = {
 print(abs(dpois(  40, 7.5)/ 6.81705586862060455e-17 -1)) < 6e-16 # 2.66e-15 in R <= 4.1.1
 print(abs(dpois(1400,1000)/ 1.46677334419656833e-33 -1)) < 8e-16 # 1.71e-14 in R <= 4.1.1
})
## very large x:
x <- trunc(2^(1000+ head(seq(1,24, by=1/64), -1)))
L <- tail(x,1)
dpxx <-  dpois(x,x) ## had ended in many 0's
ldpxx <- dpois(x,x, log=TRUE) # ... -Inf
(d <- mean(dlp <- diff(ldpxx)))# -0.005415
stopifnot(exprs = {
    dpxx > 0
    is.finite(ldpxx)
    print(abs(print(dpois(L,L))/ (1/sqrt(2*pi)/sqrt(L)) -1)) < 1e-15 # see 1.11e-16
    abs(range(dlp) - d) < 1e-12 # seen 4.4e-14, was NaN in R <= 4.1.1
    all.equal(ldpxx, log(dpxx), tol = 1e-15)
})
## dpois(x,x) underflowed to zero in R <= 4.1.1 for such large x.

Just adding this here, because I think a section about how to write R test for the source could have some examples (not just explanations about where, when). I'm not sure it is a good example, but it is simple enough to not have a snapshot approach .Rout.save (so at least it is as counterexample to all tests being snapshot test).