This documentation is intended to assist contributors to
This example is based on
Some unit tests and all the integration test require
This clone of the
If
Once a test has been selected it can be run by specifying the module and test. The
An entire module can be run by using only the
Build a container to run tests. The vm must be pre-configured but a variety are available. The vm names are all three character abbreviations, e.g.
Options can be added to a command or multiple commands. Options can be configuration file only, command-line only or valid for both. Once an option is added,
To add an option, two files need be to be modified:
These files are discussed in the following sections.
There is a detailed comment at the top of this file on the configuration definitions which one can refer to in determining how to define the rules for the option.
Command-line only options are options where Command-line only options
.
Command-line only options
comment. This section defines and exports the constant for the actual option.Command-line only options
comment. This is where the rules for the option are defined.The steps for how to update these sections are detailed below.
Section 1
Copy the two lines (use constant
/push
) of an existing option and paste them where the option would be in alphabetical order and rename it to the same name as the new option name. For example CFGOPT_DRY_RUN, defined as dry-run
.
Section 2
To better explain this section,
Note that
All options must be documented or the system will error during the build. To add an option, find the command section identified by command id="COMMAND"
section where operation-general title="General Options"
section.
To add an option, add the following to the <option-list>
section; if it does not exist, then wrap the following in <option-list>
</option-list>
. This example uses the boolean option force
of the summary
, text
and example
.
summary
section.For testing, it is recommended that Vagrant and Docker be used; instructions are provided in the
If using a RHEL system, the CPAN XML parser is required for running The following is a sample CentOS/RHEL 7 configuration that can be used for building the documentation
. NOTE that the Install latex (for building PDF)
is not required since testing of the docs need only be run for HTML output.
While some files are automatically generated during make
, others are generated by running the test harness as follows:
Prior to any submission, the html version of the documentation should also be run.
ERROR: [028]
regarding cache is invalid is OK; it just means there have been changes and the documentation will be built from scratch. In this case, be patient as the build could take 20 minutes or more depending on your system.The goal of unit testing is to have 100 percent coverage. Two files will usually be involved in this process:
somefileis the path and name of the test file where the unit tests are located for the code being updated (e.g.
Each module is separated by a line of asterisks (*) and each test within is separated by a line of dashes (-). In the example below, the module is command
and the unit test is check
. The number of calls to testBegin()
in a unit test file will dictate the number following total:
, in this case 2. Under coverage:
, the list of files that will be tested must be listed followed by the coverage level, which should always be full
.
Assuming that a test file already exists, new unit tests will either go in a new testBegin()
section or be added to an existing section.
Unit test files are organized in the test/src/module directory with the same directory structure as the source code being tested. For example, if new code is added to src/command/expire.c then test/src/module/command/expireTest.c will need to be updated.
Setting up the command to be run
If configuration options are required then a string list with the command and options must be defined and passed to the function harnessCfgLoad()
. For example, the following will set up a test to run
Tests are run via macros. All test macros expect the first parameter to be the function to call that is being tested. With the exception of TEST_RESULT_VOID, the second parameter is the expected result, and with the exception of TEST_ERROR, the third parameter is a short description of the test. The most common macros are:
void
. This is then usually followed by tests that ensure other actions occurred (e.g. a file was written to disk).Storing a file
Sometimes it is necessary to store a file to the test directory. The following demonstrates that. It is not necessary to wrap the storagePutNP in TEST_RESULT_VOID, but doing so allows a short description to be displayed when running the tests (in this case store a corrupt backup.info file
).
Testing a log message
If a function being tested logs something with harnessLogResult()
function.
Unit tests are run, and coverage of the code being tested is provided, by running the following. This example would run the test set from the define.yaml section detailed above.
Because no test run is specified and --coverage-only
has been requested, a coverage report will be generated and written to the local file system under the
Sometimes it is useful to look at files that were generated during the test. The default for running any test is that, at the start/end of the test, the test harness will clean up all files and directories created. To override this behavior, a single test run must be specified and the option --no-cleanup
provided. Again, continuing with the check command, we see in define.yaml above that there are two tests. Below, test one will be run and nothing will be cleaned up so that the files and directories in test/test-0 can be inspected.
For more details on running tests, again, please refer to the