unitizeR - Interactive R Unit Tests

R build status Dependencies direct/recursive Project Status: Active – The project has reached a stable, usable state and is being actively developed.

TL;DR

unitizer simplifies creation, review, and debugging of tests in R. It automatically stores R expressions and the values they produce, so explicit expectations are unnecessary. Every test is easy to write with unitizer because testing and using a function are the same. This encourages non-trivial tests that better represent actual usage.

Tests fail when the value associated with an expression changes. In interactive mode you are dropped directly into the failing test environment so you may debug it.

unitizer is on CRAN:

install.packages('unitizer')

It bakes in a lot of contextual help so you can get started without reading all the documentation. Try the demo to get an idea:

library(unitizer)
demo(unitizer)

Or check out the screencast to see unitizer in action.

Why Another Testing Framework?

Automated Test Formalization

Are you tired of the deparse/dput then copy-paste R objects into test file dance, or do you use testthat::expect_equal_to_reference or other snapshot testing a lot?

With unitizer you interactively review your code as you would when typing it at the R prompt. Then, with a single keystroke, you tell unitizer to store the code, and any values, warnings, or errors it produced, thereby creating a formal regression test.

Streamlined Debugging

Do you wish the nature of a test failure was more immediately obvious?

When tests fail, you are shown a proper diff so you can clearly identify how the test failed:

diff example

Do you wish that you could start debugging your failed tests without additional set-up work?

unitizer drops you in the test environment so you can debug why the test failed without further ado:

review example

Fast Test Updates

Do you avoid improvements to your functions because that would require painstakingly updating many tests?

The diffs for the failed tests let you immediately confirm only what you intended changed. Then you can update each test with a single keystroke.

Usage

unitizer stores R expressions and the result of evaluating them so that it can detect code regressions. This is akin to saving test output to a .Rout.save file as documented in Writing R Extensions, except that we’re storing the actual R objects and it is much easier to review them.

To use unitizer:

unitizer can run in a non-interactive mode for use with R CMD check.

Documentation

Acknowledgments

Thank you to:

About the Author

Brodie Gaslam is a hobbyist programmer based in the US East Coast.