Inline tests with roxygen and testthat.
See demo package using this at roxytest-demo.
There are a number of roclets included:
testthat_roclet
: Writetestthat
tests in theroxygen2
documentationparam_roclet
: Checks for consistency in documentation of parameters (too many/too few)
To 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
. (If you only use param_roclet
you do not need to add
testthat
to Suggests
.)
Suggests:
testthat
However, 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.
Add 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:
roxygen2::roxygenise()
Add the following lines to your package’s DESCRIPTION
file:
Roxygen: list(roclets = c("namespace", "rd", "roxytest::param_roclet"))
(Or make appropriate changes to obtain similar results.)
Then run the following:
roxygen2::roxygenise()
You can of course also add both, e.g.:
Roxygen: list(roclets = c("namespace", "rd",
"roxytest::testthat_roclet", "roxytest::param_roclet"))
(Or make appropriate changes to obtain similar results.)
Then run the following:
roxygen2::roxygenise()
For example, if the file R/functions.R
contains this code (from
roxytest-demo):
#' 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-functions.R
with this
content:
# Generated by roxytest: Do not edit by hand!
context("File R/functions.R")
test_that("Function foo() @ L10", {
expect_equal(foo(2), sqrt(2))
expect_error(foo("a string"))
})
test_that("Function bar() @ L23", {
expect_equal(bar("A", "B"), paste("A", "B", sep = "/"))
})
To demonstrate the param_roclet
roclet assume that this block of
documentation exists:
#' Summing two numbers
#'
#' @param x A number
foobar <- function(x, y) {
x + y
}
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: y
Similarly if there are too many documented arguments.
- Rstudio: CTRL+SHIFT+D option to run
devtools::document()
/roxygen2::roxygenise()
instead ofdevtools::document(roclets=c('rd', 'collate', 'namespace'))
- Project options -> Build tools -> If all check marks are
removed, nothing happens with CTRL+SHIFT+D. If instead
devtools::document()
would be ran it would work. - See rstudio/rstudio#5201
- Project options -> Build tools -> If all check marks are
removed, nothing happens with CTRL+SHIFT+D. If instead