A whole package

2018-11-07

This vignette will teach you how to create a unit test shell for all of the examples in an entire package’s documentation.

I’m going to be extra careful and use rprojroot for my paths because I’m in the tricky situation of making a package inside a package vignette. If you’re a package author and you don’t know the rprojroot package, it’s worth getting to know it.

Setup

First, let’s set up a dummy package directory with just the detect.R and match.R files from the source code of the stringr package.

usethis::create_package("tempkg", open = FALSE)
file.copy(
  system.file("extdata", c("detect.R", "match.R"), package = "exampletestr"), 
  rprojroot::find_root_file(
    "tempkg/R/", 
    criterion = rprojroot::has_dir("tempkg")
  )
)

Now let’s move into the tempkg directory.

setwd(
  rprojroot::find_root_file(
    "tempkg/", 
    criterion = rprojroot::has_dir("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 a unit tests shell file for each .R file in the package using make_tests_shells_pkg():

make_tests_shells_pkg()

This outputs test-detect-examples.R and test-match-examples.R files in the tests/testthat folder. As an example of what to do next, the test-detect-examples.R file has contents

context("`str_detect()`")

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

context("`str_detect()`")

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

This process must be repeated for every created test shell file in tests/testthat/.