This is an old revision of the document!
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.
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.
We aim that the regression test suite covers all the functionality of CP2K. For this purpose we regularly create Coverage Reports of the testsuit. If you see parts of the code which are not well tested, please contribute to improving coverage by writing new tests!
The regression test suite is run using the do_regtest script. It performs the following tasks:
$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.
The do_regtest script is controlled via a config file. It should contain the following variables:
| ||the base directory for testing (e.g. $HOME/rt)|
| ||compiler selection (e.g. intel)|
| ||the result of tools/get_arch_name, where the executable can be found|
| ||cp2k||normally cp2k|
| ||Maximum number of CP2K threads to execute concurrently (== total number of CPU cores to be used for regtesting)|
| ||NO||useful for automatic testers, no testing if nothing changed in SVN (YES/NO)|
| ||NO||if using gfortran with the LeakSanitizer, set this variable to “YES” in order to get memory leak checking|
Normally, you just have to call the do_regtest script with your config-file like this:
$ ./cp2k/tools/regtesting/do_regtest -config <path_to_your_config>
However, the do_regtest script supports a number of addional command line switches. Most of them can also be included into the config file.
|Command Line Switch||Meaning|
| ||do not access the SVN for any updating, makes regtesting fully local|
| ||rebuild the code if needed, but do not perform a realclean before (noquick is not needed anymore)|
| ||do not reset the reference outputs automatically|
| ||specify any string to svn update (most likely used as “2005-02-17”)|
| ||this switch can repeat, exclude certain dirs from regtesting, useful to speed-up regtesting after very localised changes (e.g. -skipdir QS/regtest)|
| ||this switch can repeat, restrict regtesting to certain dirs, useful to speed-up regtesting after very localised changes (e.g. -restrictdir QS/regtest)|
| ||loads a site/compiler/environment specific configuration|
| ||regtesting will be restricted only to those directories that contained failed tests in the previous run|
| ||use this to force regression testing even if no changes exist in SVN|
| ||do not build cp2k, but use one built by the user (turns on quick option automatically)|
The do_regtest script has the following possible exists statuses:
|0||clean exit with testing|
|1||problem with svn update|
|3||problem with realclean|
|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|
A test results can be any of the following:
| ||if the results match those of a previous run precisely. The execution time is also given.|
| ||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.|
| ||if they stopped unexpectedly (e.g. core dump, or stop)|
| ||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.
The test-suite is fully controlled by the following files in the cp2k/tests directories
| ||is just a list of directories that contain tests. You can add your directory here.|
| ||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|
| ||you can add files for which the reference output became invalid (e.g. bug fix) to this list fo 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|
| ||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.|