This vignette will teach you how to create a unit test shell for the examples in a single function's documentation.
First, let's set up a dummy package called tempkg
with just the detect.R
and match.R
files from the source code of the stringr
package.
usethis::create_package("tempkg", open = FALSE) fs::file_copy( system.file("extdata", c("detect.R", "match.R"), package = "exampletestr"), "tempkg/R/" )
Now let's move into the tempkg
directory:
setwd("tempkg/")
and set the active project:
usethis::proj_set(".")
#> ✔ Setting active project to '/private/var/folders/l_/2mwm03p55zg7zjykv084hhvr0000gn/T/RtmpPdOSWX/tempkg'
The detect.R
file looks like this (well, I've abbreviated it slightly):
#' Detect the presence or absence of a pattern in a string. #' #' Vectorised over `string` and `pattern`. #' #' @param string Input vector. Either a character vector, or something #' coercible to one. #' @param pattern Pattern to look for. #' #' @return A logical vector. #' #' @export #' @examples #' fruit <- c("apple", "banana", "pear", "pinapple") #' str_detect(fruit, "a") #' str_detect(fruit, "^a") #' str_detect(fruit, "a$") #' str_detect(fruit, "b") #' str_detect(fruit, "[aeiou]") str_detect <- function(string, pattern) { switch(type(pattern), empty = , bound = str_count(string, pattern) > 0, fixed = stri_detect_fixed(string, pattern, opts_fixed = opts(pattern)), coll = stri_detect_coll(string, pattern, opts_collator = opts(pattern)), regex = stri_detect_regex(string, pattern, opts_regex = opts(pattern)) ) }
We can make the unit tests shell file for the str_match()
function using make_test_shell_fun()
:
make_test_shell_fun("str_detect", open = FALSE)
This outputs a test-str_detect-examples.R
file in the tests/testthat
folder with contents
test_that("`str_detect()` works", { fruit <- c("apple", "banana", "pear", "pinapple") expect_equal(str_detect(fruit, "a"), ) expect_equal(str_detect(fruit, "^a"), ) expect_equal(str_detect(fruit, "a$"), ) expect_equal(str_detect(fruit, "b"), ) expect_equal(str_detect(fruit, "[aeiou]"), ) expect_equal(str_detect("aecfg", letters), ) })
which can be sensibly completed as
test_that("`str_detect()` works", { fruit <- c("apple", "banana", "pear", "pinapple") expect_equal(str_detect(fruit, "a"), rep(TRUE, 4)) expect_equal(str_detect(fruit, "^a"), c(TRUE, rep(FALSE, 3))) expect_equal(str_detect(fruit, "a$"), c(FALSE, TRUE, FALSE, FALSE)) expect_equal(str_detect(fruit, "b"), c(FALSE, TRUE, FALSE, FALSE)) expect_equal(str_detect(fruit, "[aeiou]"), rep(TRUE, 4)) expect_equal( str_detect("aecfg", letters), letters %in% c("a", "c", "e", "f", "g") ) })
Alternatively, we can use the roxytest
(https://github.com/mikldk/roxytest) package's @testexamples
roxygen tag for testing examples.
make_test_shell_fun("str_detect", roxytest = TRUE)
#> ℹ Running `roxygen2::roxygenize` . . .
#> Updating roxygen version in /private/var/folders/l_/2mwm03p55zg7zjykv084hhvr0000gn/T/RtmpPdOSWX/tempkg/DESCRIPTION
#> Loading tempkg
#> ✔ Roxygenized :-) #> @testexamples #> #' expect_equal(str_detect(fruit, "a"), ) #> #' expect_equal(str_detect(fruit, "^a"), ) #> #' expect_equal(str_detect(fruit, "a$"), ) #> #' expect_equal(str_detect(fruit, "b"), ) #> #' expect_equal(str_detect(fruit, "[aeiou]"), ) #> #' expect_equal(str_detect("aecfg", letters), ) #> [Copied to clipboard] #> ● Paste the block into your roxygen documentation. #> ● Complete the tests in the block. #> ● Run `devtools::document()` to generate the tests in 'tests/'.
This can also be done by highlighting the function name and selecting the RStudio addin Copy roxytest @testexamples to clipboard.
knitr::opts_knit$set(root.dir = tempdir(check = TRUE))
if (fs::dir_exists("tempkg")) fs::dir_delete("tempkg") knitr::opts_knit$set(root.dir = init_wd)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.