use_catch: Use Catch for C++ Unit Testing

Description

Add the necessary infrastructure to enable C++ unit testing in Rpackages with https://github.com/philsquared/Catch{Catch} and testthat.

Usage

use_catch(dir = getwd())

Arguments

dir

The directory containing an Rpackage.

Functions

All of the functions provides by Catch are available with the CATCH_ prefix -- see https://github.com/philsquared/Catch/blob/master/docs/assertions.md{here} for a full list. testthat provides the following wrappers, to conform with testthat's Rinterface:

lll{ Function Catch Description context CATCH_TEST_CASE The context of a set of tests. test_that CATCH_SECTION A test section. expect_true CATCH_CHECK Test that an expression evaluates to true. expect_false CATCH_CHECK_FALSE Test that an expression evalutes to false. expect_error CATCH_CHECK_THROWS Test that evaluation of an expression throws an error. expect_error_as CATCH_CHECK_THROWS_AS Test that evaluation of an expression throws an error of a specific class. }

Advanced Usage

If you'd like to write your own Catch test runner, you can instead use the testthat::catchSession() object in a file with the form:

#define TESTTHAT_TEST_RUNNER #include

void run() { Catch::Session& session = testthat::catchSession(); // interact with the session object as desired }

This can be useful if you'd like to run your unit tests with custom arguments passed to the Catch session.

Details

Calling use_catch() will:

Create a filesrc/test-runner.cpp, which ensures that thetestthatpackage will understand how to run your package's unit tests,
Create an example test filesrc/test-example.cpp, which showcases how you might use Catch to write a unit test, and
Add a test filetests/testthat/test-cpp.R, which ensures thattestthatwill run your compiled tests.

C++ unit tests can be added to C++ source files within the src/ directory of your package, with a format similar to Rcode tested with testthat -- for example,

context("C++ Unit Test") { test_that("two plus two is four") { int result = 2 + 2; expect_true(result == 4); } }