This is an old revision of the document!
Table of Contents
CP2K Regression Testing
CP2K comes with over 2500 test input files (located in cp2k/tests) which serve as both examples on how to use the many features in CP2K and also as a method for developers to test modifications and extensions to CP2K. In order to reduce the chance of bugs being introduced into the code, and ensure that all parts of the code are working, we recommend that :
- all developers complete a successful run of the full regression test suite before committing changes to SVN.
- all users complete a test before using a self-compiled binary for their projects
Dashboard
A number of regtests are run automatically by various members of our community. The results of these tests are collected centrally at the Dashboard . If errors are detected, the developer responsible for the change should fix it immediately.
Code Coverage
We aim that the regression test suite covers all the functionality of CP2K. For this purpose we regularly create Coverage Reports of the test-suite. If you see parts of the code which are not well tested, please contribute to improving coverage by writing new tests!
How does it work?
The regression test suite is run using the do_regtest script. It performs the following tasks:
- update to the current SVN version (including new tests)
- performs a realclean build of the source
- executes a list of tests
- compares the results (outputs) with those of the last known result (reference)
- produces a summary
Running the regtests
Step 1: Preparation
- You must be able to build and run cp2k on the given machine, the rest should be 'easy'
- Decide on a directory for doing the regtest, there will be plenty of files in this dir (after a while) so make it something like
$HOME/rt - Checkout a version of cp2k into
$HOME/rt. If you set up your svn account so that you don't need to provide a password for doing svn update, things will be more convenient later on. - Set up the arch files so that you can cleanly build cp2k (test this)
Step 2: Running
$ cp2k/tools/regtesting/do_regtest --help
Usage: do_regtest [OPTION]
Run the CP2K regression test suite
Example: do_regtest -c my_regtest.conf
General:
-h, -help, --help print this help screen.
-c, -config FILE read any of the following configuration switches from FILE.
-cp2kdir PATH location of cp2k source tree relative to current working directory.
Svn:
-svndate DATE checkout svn revision of given DATE. Default: use trunk.
-nosvn do not run svn update. Default: off.
-noemptycheck run tests even when no changes in svn were made. Default: on.
Build:
-version VERSION VERSION passed to make. Default: sopt.
-arch ARCH ARCH passed to make. Default: Linux-x86-64-gfortran.
-quick rebuild if needed, but without realclean. Default: off.
-nobuild do not build cp2k, rely on user's build. Default: off.
Runtime:
-mpiranks NRANKS number of mpi-ranks. Default: 2 for parallel versions, 1 for serial.
-ompthreads NTHREADS number of OpenMP threads. Default: 2 for smp versions otherwise 1.
-maxtasks NPROCS total number of processor to use. Default: `nproc --all`.
-jobmaxtime SECONDS maximum execution time of a single test. Default 600.
Testing:
-noreset do not reset the reference outputs. Default: off.
-skiptest do not run test, only svn update and build. Default: off.
-skipdir TESTDIR do not run tests in TESTDIR. This switch can repeated.
-restrictdir TESTDIR run only tests in TESTDIR. This switch can repeated.
-retest run only tests in directories, which had failing tests in previous run.
Exit codes:
0 clean exit with testing
1 problem with svn update
3 problem with realclean
4 build errors
5 problem with retest option - no TEST directory with latest test results found
6 problem with retest option - no error summary exists in the last TEST directory
7 reference directory is locked
8 ctrl-C (SIGINT) and various other signals trapped
100 no svn changes since last run - clean exit without testing
For more information visit: <http://cp2k.org/dev:regtesting>
Step 3: Interpretation
A test results can be any of the following:
| Test Result | Meaning |
|---|---|
OK | if the results match those of a previous run precisely. The execution time is also given. |
NEW | if they have not been executed previously. The reference result is generated automatically in this run. Tests can also be NEW if they have been reset, i.e. been newly added to the TEST_FILES_RESET files. |
RUNTIME FAILURE | if they stopped unexpectedly (e.g. core dump, or stop) |
WRONG RESULT | if they produce a result that deviates (even a tiny bit) from an old reference |
The last two outcomes generally mean that a bug has been introduced, which requires investigation. Since regtesting only yields information relative to a previously known result, it is most useful to do a regtest before and after you make changes. To allow per-test numerical difference higher than that set as a default, add third column in appropriate TEST_FILES file with a relative value of the difference.
Adding and Resetting Tests
The test-suite is fully controlled by the following files in the cp2k/tests directories
| File Name | Content |
|---|---|
TEST_DIRS | is just a list of directories that contain tests. You can add your directory here. |
TEST_FILES | the list of input files that need to be executed. You can add your file name here. Adding a comment about what it tests might help later debugging problems if a regtest fails |
TEST_FILES_RESET | you can add files for which the reference output became invalid (e.g. bug fix) to this list of files. However be absolutely sure that the change is due to a bug fix, do not reset these that fail because of unclear reasons. Try to add a comment to the svn message and/or the file itself |
TEST_TYPES | this file allows you to create a new test type. I.e. to specify for which words should be grepped and what field should be used in the numerical comparison. |