rubak / roxytest

Inline testthat tests with roxygen2

roxytest

Inline tests with roxygen and testthat.

See demo package using this at roxytest-demo.

Usage

There are a number of roclets included:

• testthat_roclet: Write testthat tests in the roxygen2 documentation
• param_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.

testthat roclet

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()

param roclet

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()

Multiple roclets

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()

Examples

testthat roclet

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 = "/"))
})

param roclet

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.

Wish-list

• Rstudio: CTRL+SHIFT+D option to run devtools::document()/roxygen2::roxygenise() instead of devtools::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