There are a number of roclets included:
testthat_roclet: Write testthat tests in the roxygen2 documentation
@tests: Generate test skeletons@testexamples: Generate test skeletons with @examples included first such that e.g. variables can be reusedtinytest_roclet: Write tinytest tests in the roxygen2 documentation
@tests: Generate test skeletons@testexamples: Generate test skeletons with @examples included first such that e.g. variables can be reusedparam_roclet: Checks for consistency in documentation of parameters (too many/too few)return_roclet: Checks if @exported functions has @return documentation (possibly just @return None)examples_roclet: Checks if @exported functions has @examples documentationTo use the package in your own package you do not need to add any additional dependencies in your package’s DESCRIPTION file apart from the usual Suggests: testthat that is required for testing with testthat or the Suggests: tinytest that is required for testing with tinytest. (If you only use param_roclet, return_roclet or examples_roclet you do not need to add anything to Suggests.)
Suggests:
testthat # or tinytestHowever, any developer working on your package needs to have roxytest installed to be able to successfully run roxygen2::roxygenise() (or devtools::document()). For this reason you may consider adding roxytest to Suggests, but this is not required.
testthat rocletAdd the following lines to your package’s DESCRIPTION file (along with Suggests: testthat):
Roxygen: list(roclets = c("namespace", "rd", "roxytest::testthat_roclet"))(Or make appropriate changes to obtain similar results.)
Then run the following:
Similarly for the other roclets.
You can of course also add multiple, e.g.:
Roxygen: list(roclets = c("namespace", "rd",
"roxytest::testthat_roclet",
"roxytest::param_roclet",
"roxytest::return_roclet"))(Or make appropriate changes to obtain similar results.)
Then run the following:
Below we show based on testthat, but it is the same for tinytest except the output which then happens at inst/tinytest without contest() and testthat() boilerplate.
testthat rocletAs mentioned above, there are two tags available:
@tests: Generate test skeletons@testexamples: Generate test skeletons with @examples included first such that e.g. variables can be reusedNote that both can be used at the same time.
We first demonstrate @tests and afterwards @testexamples.
@tests tagFor example, if the file R/functions.R contains this code (from roxytestdemo):
#' A function to do x
#'
#' @param x A number
#'
#' @tests
#' expect_equal(foo(2), sqrt(2))
#' expect_error(foo("a string"))
#'
#' @return something
foo <- function(x) {
return(sqrt(x))
}
#' A function to do y
#'
#' @param x Character vector
#' @param y Character vector
#'
#' @tests
#' expect_equal(bar("A", "B"), paste("A", "B", sep = "/"))
#'
#' @export
bar <- function(x, y) {
paste0(x, "/", y)
}Then roxygen2::roxygenise() will generate (with the testthat_roclet roclet) the file tests/testthat/test-roxytest-tests-functions.R with this content:
@testexamples tagFor example, if the file R/functions.R contains this code (from roxytestdemo):
#' A function to do w
#'
#' @param x A number
#'
#' @examples
#' x <- 2
#' foo(x)
#'
#' @testexamples
#' expect_equal(foo(x), foo(2))
#'
#' @return something
foo2 <- function(x) {
return(sqrt(x))
}Then roxygen2::roxygenise() will generate (with the testthat_roclet roclet) the file tests/testthat/test-roxytest-testexamples-functions.R with this content:
# Generated by roxytest: Do not edit by hand!
context("File R/functions.R: @testexamples")
test_that("Function foo2() @ L13", {
x <- 2
foo(x)
expect_equal(foo(x), foo(2))
})Note that:
\dontrun: Everything including content is removed\donttest: Only the tag itself is removed\dontshow: Only the tag itself is removedparam rocletTo demonstrate the param_roclet roclet assume that this block of documentation exists:
When the package is documented, the following output will be displayed:
Functions with @param inconsistency:
* Function 'foobar' with title 'Summing two numbers':
- Missing @param's: ySimilarly if there are too many documented arguments.
return rocletTo demonstrate the return_roclet roclet assume that this block of documentation exists:
When the package is documented, the following output will be displayed:
Functions with @export but no @return:
* Function 'foobar2()' with title 'Summing two numbers'examples rocletTo demonstrate the examples_roclet roclet assume that this block of documentation exists:
When the package is documented, the following output will be displayed:
Functions with @export but no @example(s):
* Function 'foobar2()' with title 'Summing two numbers'