Technical documentation
Infrastructure
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!
Component | Description |
|---|---|
R Packages |
|
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 . |
Setup | Initialise the test_that testing environment, including the ds.test_env environment. It is the setup.R file. |
Teardown | 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. |
Tests | 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:
https://github.com/patRyserWelch8/dsTestingFramework
Remainder of this section
DataSHIELD Wiki by DataSHIELD is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. Based on a work at http://www.datashield.ac.uk/wiki