Test development workflow
In standard R packages, new functionality is added to R/
with usethis::use_r(), followed by a corresponding test
file in tests/testthat/ with
usethis::use_test():
use_r()use_test()
While developing, these files can be accessed using the functions
above, and tested interactively with
devtools::test_active_file() and
devtools::test_coverage_active_file()
test_active_file()test_coverage_active_file()
As the code in R/ grows, the test suite might include
additional features like fixtures, helpers, mocks, or a
setup.R file. When a package has been sufficiently
developed, the tests are run with devtools::test(), test
coverage is reported with devtools::test_coverage(), and
the (I’m assuming the package is checked periodically with
devtools::check(), too):
test()test_coverage()
Additional package can be used to include test coverage reports (covrpage),
traceability matrices (covtracer),
etc., to your package documentation.
Test documentation
Throughout development, the functional requirements for your package
are documented in R/ (with roxygen2), and
long-form documentation is placed in vignettes.1 Vignettes can (and
should) be used to show users how your package works, especially if your
package is going to be shared with the world (i.e., via a pkgdown site).
However, it’s not often developers use vignettes to store the
information that’s essential to the development process (i.e.,
proposed features, specifications, user stories, etc.)
Rmd + BDD = pickler
Including relevant context in describe() and
it() is nice for developers, but I’ve found stakeholders
and potential users rarely look the the tests/ folder for
information on a package’s features (or how it’s functions are supposed
to behave).
pickler was written to make the information in the
tests/ folder more accessible to a broader audience. The Gherkin-style
functions available in pickler are designed to work in R
Markdown (i.e. as a vignette) and run in a test file. It’s been
pointed out elsewhere2 that vignettes have a few characteristics
that make them a great place for development:
“an R package implies writing documentation: one of the main goals of the Vignettes, in an R package, is to document how to use the package. And the good news is that when checking a package, i.e. when running
check()fromdevtools(Wickham, Hester, and Chang 2020) orR CMD check, the Vignettes are going to be built, and the process will fail if at least one of the Vignettes fails to render. That way, you can use the documentation of the back-end as an extra tool for doing unit testing!”