module_testing: The BioCro module testing system

In ebimodeling/biocro: Modular Crop Growth Simulations

The BioCro module testing system

Description

BioCro provides several functions for defining, modifying, and running module test cases. These functions together allow module developers to easily create regression tests that ensure the modules continue to function correctly.

Details

Together, test_module_library, test_module, case, cases_from_csv, initialize_csv, add_csv_row, and update_csv_cases form a simple and convenient system for defining and running module test cases. Such tests form a critical component of BioCro's regression testing system, and test cases should be defined for all BioCro modules in all BioCro module libraries. These functions are not required in order to use the BioCro package, but they are critical to understand when creating or modifying modules.

A module test case consists of a set of module inputs, a set of module outputs, and a short description of the case. To run the test, the inputs are passed to the module, and then the calculated outputs are compared to the expected ones. If the outputs match, the test is passed; otherwise, it fails. This operation is handled by the test_module function.

For simple on-the-fly testing, it is possible to define a test case using the case function and run it using test_module. However, a more robust method is available to facilitate regression testing, where module test cases are stored in suitably-formatted csv files, allowing multiple test cases to be defined for each module and easily checked afterwards. If test case files for each module in a module library are stored in a single directory, all the test cases can be checked with one call to test_module_library.

In this system, test cases for a module with fully-qualified name module_name must be stored in module_name.csv, where the colon in the module name has been replaced by an underscore; for example, the module named BioCro:total_biomass would be associated with BioCro_total_biomass.csv. The first row of a test case file must be the quantity types (input or output), the second row must be the quantity names, and the remaining rows must each specify input quantity values along with the expected output values they should produce. There must also be a description column (with description in the first row) containing short descriptions of the test cases. These formatting requirements will automatically be satisfied for any test case file produced by initialize_csv or modified by add_csv_row or update_csv_cases. Such files can be read from R using cases_from_csv, and the resulting case objects can be passed to test_module.

Although it is possible, directly editing the case files is not recommended since initialize_csv, add_csv_row, and update_csv_cases are easier to use. There are several exceptions to this suggestion: (1) when a case must be deleted, (2) when a module input must be added or removed, and (3) during the initialization of a test file, where a user may wish to batch-initialize using update_csv_cases (see its documentation for an explanation of batch-initialization).

Case files can easily be viewed using Excel or other spreadsheet viewers, and are also nicely formatted when viewed on the GitHub website for the repository.

Examples of module test case files can be found in the tests/module_test_cases directory, while code that uses the testthat package to automatically run all the defined test cases for the standard BioCro module library via test_module_library can be found in the tests/testthat/test.Modules.R file.

See Also

• modules

• module_case_files

• test_module_library

• test_module

ebimodeling/biocro documentation built on April 23, 2024, 7:06 p.m.