testthis package vignette

Stefan Fleck

2018-08-11

Overview

Testthis contains tools to make unit testing in R more comfortable. It is designed to complement the packages testthat, devtools and usethis.

RStudio addins

Testthis provides RStudio addins for common tasks. These can be called like normal R function, but it is also possible to assigned to hotkeys to them in RStudio (Tools/Modify Keyboard Shortcuts). I recommend assigning ctrl+alt+Insert, ctrl+alt+Pos1 and ctrl+alt+PageUp to the following functions:

The functions above assume that if the current filename is currentfile.R, the associated test file is /tests/testthat/test_currentfile.R. If you want to modify this behaviour you can put the tag #* @testfile anotherfile anywhere in your code, usually the top or bottom of your .R file. Each R script can only have a single associated testfile.

The following example will associate the file /tests/testthat/other_test_file.R instead of /tests/testthat/test_open_testfile.R with R/open_testfile:

# file R/open_testfile.R

#* @testfile other_testfile
open_testfile <- function(){
  fname <- get_testfile_name()

  if(file.exists(fname)){
    rstudioapi::navigateToFile(fname)
  } else {
    test_skeleton(fname, open = TRUE)
  }
}

Managing test data

Sometimes, it might become necessary to have access to complex data sets for tests. The recommended way for dealing with this is to provide an example dataset in your packages data/ directory; however, there are also usecases where you want seperate data files for your tests.

Testthis provides three functions to to make dealing with separate test data files a bit easier:

use_testdata(iris)
## Saving to 
## * r/testthis/tests/testthat/testdata/iris.rds

tdat <- read_testdata("iris.rds")

use_testdata_raw()
## ✔ Creating 'tests/testthat/testdata-raw/'

Managing test subdirectories

Sometimes it is useful to create tests for a package that go beyond simple best-practice unit tests. For example you might have some tests that require external ressources (web, databases) or take long to execute. If you put such tests in subdirectories of test/testthat they will neither be automaticaly executed by devtools::test() nor run on CRAN.

testthis provides helpers do deal with files in subdirectories of tests/testthat.

use_test_subdir("foobar_tests")
## ✔ Creating 'tests/testthat/foobar_tests/'
## creating tester function test_foobar_tests() in r/testthis/R/testthis-testers.R

test_subdir("foobar_tests")
## No tests: no files in r/testthis/tests/testthat/foobar_tests match '^test.*\.[rR]$'

Test coverage checklist

This is an experimental feature, comments and feature request are welcome. Testthis provides a checklist like test coverage analyser. This is non-automatic and requires you to manually mark functions as tested in your code via special comments. If you look for automatic test coverage analysis, you might want to check out the covr package instead.

For testthis to recognize wheter a unit test exists for a function, the function name must either be mention in a testthat() desc argument, or marked via special comment tag: #* @testing functionname. If you want to mark a function as not requiring testing, you can add the function name to the file /tests/testthat/_testignore manually, or with use_testignore().

The following example will mark the functions parse_testthis_comments and detect_testthis_comments as tested:

# file /tests/testhis/parse_testthis_comments.R

test_that("parse_testthis_comments works as expected", {
  #* @testing detect_testthis_comments
  ...
}

To display the test coverage use:

get_test_coverage()

Testthis Tags

Test_this tags are special comments that modify the behavious of the functions supplied by this package. They are of the Form #* @tag <value>. Please not that only some test_this tags really require a <value>. The tag system should be considered to be in a beta-state.

Valid tags for script files in the /R/ dir (pkg/R/*.R)

Valid tags or test files (pkg/tests/testthat/test_*.R)

also look at /test/testthat/test_Taglist.R for examples.