A Simple Package for Testing R Packages

Provides two convenience functions assert() and test_pkg() to facilitate testing R packages.


Build Status Coverage Status Downloads from the RStudio CRAN mirror

This package provides two simple functions (30 lines of code in total):

  • assert(fact, ...): think of it as message(fact) + stopifnot(...)

  • test_pkg(package): runs tests with all objects (exported or non-exported) in the package namespace directly available, so no need to use the triple-colon package:::name for non-exported objects

Why?

Because it is tedious to type these commands repeatedly in tests:

message('checking if these numbers are equal...')
stopifnot(all.equal(1, 1+1e-10), 10*.1 == 1)
 
message('checking if a non-exported function works...')
stopifnot(is.character(package:::utility_foo(x = 'abcd', y = 1:100)))

With the two simple functions above, we type six letters (assert) instead of sixteen (message + stopifnot), and assert is also a more intuitive function name for testing purposes (you assert a fact followed by evidence):

assert('These numbers are equal', {
 
  (all.equal(1, 1 + 1e-10))
 
  (10 * .1 == 1)
 
})
 
assert('A non-exported function works', {
  res = utility_foo(x = 'abcd', y = 1:100)
  (is.character(res))
})
 
assert('T is TRUE and F is FALSE by default, but can be changed', {
  (T == TRUE )
  (F == FALSE)
 
  T = FALSE
  (T == FALSE)
})

R CMD check

Put the tests under the directory pkg_name/tests/testit/ (where pkg_name is the root directory of your package), and write a test-all.R under pkg_name/tests/:

library(testit)
test_pkg('pkg_name')

That is all for R CMD check. For package development, it is recommended to use devtools. In particular, Ctrl/Cmd + Shift + L in RStudio makes all objects in a package visible to you, and you can run tests interactively.

Installation

Stable version on CRAN:

install.packages('testit')

Development version:

devtools::install_github('yihui/testit')

More

How about testthat? Well, this package is far less sophisticated than testthat. There is nothing fancy in this package. Please do consider testthat if your tests require more granularity. I myself do not use testthat because I'm too lazy to learn the new vocabulary (testthat::expect_xxx). For testit, I do not need to think if I should use expect_equal, expect_equivalent, or expect_identical; I just write test conditions in parentheses that are expected to return TRUE. That is the only single rule to remember.

There is no plan to add new features or reinvent anything in this package. It is an intentionally tiny package.

Xunzi

Although he did not really mean it, Xunzi said something that happens to apply well to unit testing:

This package is free and open source software, licensed under GPL.

News

CHANGES IN testit VERSION 0.9

NEW FEATURES

o Added a new argument silent to has_error() (thanks, @StevenMMortimer, #6).

CHANGES IN testit VERSION 0.8

NEW FEATURES

o When %==% is used inside assert(), a message will be printed if the value is not TRUE, to show the values of the LHS and RHS, respectively.

CHANGES IN testit VERSION 0.7

NEW FEATURES

o provided an alternative way to write assertions of the form assert('fact', {(condition_2); (condition_2)}); see ?testit::assert for more information

CHANGES IN testit VERSION 0.6

NEW FEATURES

o test_pkg() runs package tests with top-level environment being set to the namespace of the tested package (thanks, @kalibera, #3)

MAJOR CHANGES

o all test scripts (test-*.R) are assumed to be encoded in UTF-8 if they contain multibyte characters

CHANGES IN testit VERSION 0.5

NEW FEATURES

o added an infix operator %==% as an alias of identical() (in RStudio, you can use an add-in to insert the text %==%)

MINOR CHANGES

o test_pkg() will print out the filename of the R script that errored

CHANGES IN testit VERSION 0.4

MAJOR CHANGES

o the fact argument of assert() is optional now: all arguments of assert() can be test conditions

CHANGES IN testit VERSION 0.3

MAJOR CHANGES

o the test files have to be named of the form test-.R (or test-.r), i.e. they have to use the prefix test-

o the test environment is always cleaned (all objects removed) before the next test is run

CHANGES IN testit VERSION 0.2.1

MINOR CHANGES

o fixed a test that failed under R 2.15.x because the argument keep.source did not exist in parse()

CHANGES IN testit VERSION 0.2

MAJOR CHANGES

o assert() does not use base::stopifnot() any more; a tailored version of stopifnot() is used now; see ?assert for the differences between this version and base::stopifnot(); in particular, assert(fact, logical(0)) will fail but stopifnot(logical(0)) will not

CHANGES IN testit VERSION 0.1

NEW FEATURES

o this is the first version of testit; the source code is hosted on Github: https://github.com/yihui/testit

o added functions assert(), test_pkg(), has_error() and has_warning()

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("testit")

0.9 by Yihui Xie, 5 months ago


https://github.com/yihui/testit


Report a bug at https://github.com/yihui/testit/issues


Browse source code at https://github.com/cran/testit


Authors: Yihui Xie [aut, cre] , Steven Mortimer [ctb]


Documentation:   PDF Manual  


GPL license


Suggests rstudioapi


Imported by IalsaSynthesis, SACOBRA, TDMR, Wats, beautier, clinPK, iemisc, nLTT, tracerer.

Suggested by NlsyLinks, animation, blogdown, bookdown, formatR, futile.matrix, highr, junctions, knitr, lambda.r, leaflet, pagedown, rticles, tawny, tawny.types, tinytex, vpc, xaringan, xfun.


See at CRAN