Skip to contents

Start a doctest

Source: R/docs.R
doctest-tag.Rd

@doctest starts a doctest: a code example that also contains one or more testthat expectations.

Details

Use @doctest where you would usually use @examples. Then add @expect and @expectRaw tags beneath it to create expectations.

By default, a test labelled "Example: <object name>" is created. You can put a different label after @doctest:

#' @doctest Positive numbers
#'
#' x <- 1
#' @expect equal(x)
#' abs(x)
#'
#' @doctest Negative numbers
#' x <- -1
#' @expect equal(-x)
#' abs(x)

You can have more than one @doctest tag in a roxygen block. Each doctest will create a new test, but they will all be merged into a single Rd example. Each doctest must contain an independent unit of code. For example, this won't work:

#' @doctest Test x
#' @expect equal(2)
#' x <- 1 + 1
#'
#' @doctest Keep testing x
#' @expect equal(4)
#' x^2
#' # Test will error, because `x` has not been defined here

A test will only be written if the @doctest section has at least one @expect or @expectRaw in it. This lets you change @examples to @doctest in your code, without generating unexpected tests.