Technical documentation



The testing framework relies on test_that; a R package providing some unit testing for the programming language R. This package offers some additional functionalities compared with R studio. For that reason, it has been largely adopted by the R community to develop packages. CRAN also expects any packages to have some unit tests written using this package.

Folders structure

A DataSHIELD package has a set of well-defined folders; those folders includes man, R, and tests. The R folder contains R files some R functions. The tests folder contains all the additional code required to run the tests. An additional folder referred as “testthat” is created to hold all the tests written with the test_that package. When the test_that package is invoked, by default all the tests available in this folder are automatically executed sequentially. Then, a report is provided.


Conceptual model

DataSHIELD testing framework includes the following components. This architecture does not only promote code re-use, but also empowers the developers with some useful tools. The conceptual model illustrates how the various components bring together all the necessary tools to tests DataSHIELD functions.

This pyramid illustrates how the DataShield Testing Framework relies on many components to write and execute a test successfully. The most advanced testers could adapt the framework to their own needs. However, we would discourage the editing any of the code provided. Otherwise, the integration to the main DataSHIELD repository could become a lot more challenging!








R Packages

  • test_that package provides the unit testing framework required to write unit tests for DataSHIELD functions.

  • Devtools package is a convenient mechanism to running some testthat test with R Studio and R command prompt.

  • RCurl package is used to connect through the IP stack to the Opal servers (i.e. virtual machines).

  • bitops package is to provide functions for bitwise operations on integer vectors.

  • rjson package provides the functions to convert data to rjson and convert data in JSON data into R.

  • mime package provides the functions to offer additional functionality in R related to the multi-purpose internet mail extension.

  • dsBaseClient package provides the client side functions. Other DataSHIELD packages being developed would become part of this conceptual model.

R programming language

R programming language is used to develop DataSHIELD libraries.

Virtual machine

Emulates remote connection to a DataSHIELD server using the full IP-stack communication protocols and an Opal server.

Environment: ds.test_env

This R environment provides all the programming variables required to develop some tests and connect to the datasets.

Testing dataset

Some local and remote data is provided to complete some tests for accuracy and expected values returned by some DataSHIELD functions.

Connection Tools

Some functions to safely connect locally and remotely to the testing dataset .


Initialise the test_that testing environment, including the ds.test_env environment. It is the setup.R file.


Once of all the tests have been executed, the ds.test_env environment is cleared from the memory and all connections to the virtual machine are closed. It is the teardown.R file.

Definition of tests

Some definitions of tests are written, so that a test can be used again for different columns of the local and remote data. This element is written by the developers and promote code re-use. It also reduce the code for unit tests size and it becomes more available.


All the files starting with test are executed by test that. All the tests follow the naming convention stated in Classes of tests.

Downloading the Testing framework

An empty R Packages with the testing framework can be obtained from the following repository:

Remainder of this section