A brief overview of tinytest

Package setup

A quick way to set things up is as follows.

tinytest::setup_tinytest("pkgdir")

where pkgdir is a package source directory with a valid DESCRIPTION file

The setup is as follows.

  1. Files having names starting with test are in pkg/inst/tinytest, e.g. test_haha.R. Test files are R scripts interspersed with test commands, such as expect_equal(myfunc(1), 0).
  2. tinytest is added to Suggests: in the DESCRIPTION file.
  3. A file named tinytest.R is set up in pkg/tests to make sure that tests will be run by R CMD check.

A nice way to set up a completely new package that passes R CMD check is as follows

pkgKitten::kitten("hihi")
tinytest::setup_tinytest("hihi")

where hihi is the name of the new package.

Interactive package testing

Function description
test_all("pkgdir") run all test files (pkg must be loaded).
build_install_test("pkgdir") build, install, and test in temp dir.
run_test_dir("pkgdir") run all test files in a directory (pkg must be loaded).
run_test_file("testfile") run a single test file (pkg must be loaded).

All functions return an object of class tinytests. Results can be printed to screen, summarized with summary or converted to data frame with as.data.frame for analyses. The option verbose (default: 2) controls showing test progress in the terminal.

Test functions

The syntax of test functions resembles that of testthat. For expectations comparing two results, the first argument represents the observed value while the second argument represents the desired value.

Function description
expect_true Argument must evaluate to TRUE
expect_false Argument must evaluate to FALSE
expect_equal Data and attributes of arguments must be equal
expect_equivalent Data of arguments must be equal
expect_identical Target and current must be identical
expect_inherits Current object must inherit from the desired class
expect_null Expression must evaluate to NULL
expect_equal_to_reference Object must be equal to an object stored on file
expect_equivalent_to_reference Object must be equivalent to an object stored on file
expect_stdout Expect a printed message (via print or cat)
expect_message Expression must yield a message
expect_warning Expression must yield a warning
expect_error Expression must yield an error
expect_silent Expect no errors, no warnings

For tests in a script there is an alternative syntax in the style of RUnit. For each function of the form expect_lol there is a function of the form checkLol.

Monitor side-effects

Side-effects, such as changing environment variables, locale settings, or changing the working directory can cause hard-to-trace bugs. Add the statement

report_side_effects()

to a test file and certain types of side-effects, if any, are reported.

Alternatively, use the side_effects argument to any of the test runners, for example

test_all("/path/to/package", side_effects=TRUE)

Run test with custom environment variables set

Temporarily set environment variables for the run of the test. For example:

test_all("/path/to/package", setenv=list("wa_babalooba" = "ba_la_bamboo"))

Test results (objects of class tinytests) have two printing modes: a long format and a short, one-line format. Information that is always shown includes:

In long format, the test call and difference between desired and realized input are shown in full. Global printing options can be set with options(option=value).

Option default description
tt.pr.passes FALSE print passing tests?
tt.pr.limit 10 how many results to print?
tt.pr.nlong 3 how many tests in long format?
tt.pr.color TRUE print colored output?

It is also possible to influence these options using print.tinytest. Colored output is suppressed on systems with a "dumb" terminal.

Run tests for an installed package

For a package called haha that is tested with tinytest, any user that has haha and tinytest installed can run tests as follows.

tinytest::test_package("haha")

Run tests in parallel

Run tests in parallel over files.

tinytest::test_package("haha", ncpu=3)

Or, for more control:

cl <- parallel::makeCluster(4)
parallel::clusterCall(cl, source, "R/functions.R")
test_all(cluster=cl)
stopCluster(cl)

Use extension packages

Add the following to a test file to use assertions exported by ttdo.

using(ttdo)

this will give you excellent diff output of the diffobj package in tinytest test results. The high-performance checkmate package also extends tinytest.

Skipping or ignoring tests

Use exit_file() to stop executing a test file, with an optional message.

exit_file("I'm too tired to test today")

Use ignore(testfunction) to run a test but not include the result in the output.

# both tests run, but only second is recorded.
if ( ignore(expect_equal)(1 + 1, 2) ){
  expect_true( 1 > 0 )
}

Note the placement of brackets.

Use at_home() to detect whether a test is running interactively, or via test_package() (i.e. the way R CMD check will run it).

if ( at_home() ){
  # run tests requiring lots of time.
}

The package vignette has some tips on how to use this feature, and how you can set up your package so R CMD check also runs tests protected by at_home() in your environment.

Comparing with data stored on file

Data can be loaded from pkg/inst/tinytest (or subdirectories). A simple test file might look like this.

desired <- read.csv("mycsvoutput.csv", stringsAsFactors=FALSE)
obtained <- compute_my_result()
expect_equal(obtained, desired)

If you wish to publish the package on CRAN, make sure that the files are small enough for the package to be acceptable. See the CRAN repository policy for explicit bounds on package size. Alternatively you can avoid installing the data and associated test files by adding them to .Rinstignore.

More information

See the vignette.

vignette("using_tinytest", package="tinytest")