*************
Test Examples
*************

A test suite is provided for validating your ChemShell installation in :file:`YOUR_CHEMSH_DIR/tests`.

To run the test suite, use the test script::

  ./test

The test driver will then execute each of the ChemShell tests in turn, followed by a summary of 
the results. The summary is also saved to the file ``validate.log``.

As well as pass or fail, tests may return as unsupported (e.g. if an external code is not 
available on your machine), or unknown if no result could be found. 
Failures and unknown results are not expected and should be investigated before proceeding to
use ChemShell for production calculations.

By default the test suite will be run using the ``chemsh`` script, but execution directly via Python
can also be tested with, e.g.::

  ./test --exe python3

The test set can also be used as a reference set of example inputs to base your own calculations on.
However please note the calculations are designed primarily to test the code and so may be deliberately
unrealistic in some cases.

Test driver options
===================

All of the optional arguments that can be supplied to the ``chemsh`` script can also be given to 
the test driver. For example, to run the test suite with a parallel build of ChemShell using 
4 MPI processes::

  ./test --exe chemsh -np 4

On HPC platforms, the tests can be submitted to the queueing system in the usual way::

  ./test --exe chemsh --submit [job options]

Note in this case the test results will be given in the output file of the submitted job.

Subsets of the test suite can also be run by giving a list of directory names. 
For example, to run the NWChem tests in ``tests/nwchem/`` and ``tests/qmmm/nwchem-gulp`` run::

  ./test --sets nwchem nwchem-gulp

Any tests in subdirectories will also be run. So, for example::

  ./test --sets qmmm

will run all the tests in ``tests/qmmm/`` including all subdirectories.