Start section in the programmer guide describing how to add unit tests

doc/src/Build_development.rst

@@ -108,13 +108,18 @@ results over a given number of steps and operations within a given
 error margin).  The status of this automated testing can be viewed on
 `https://ci.lammps.org <https://ci.lammps.org>`_.
 
+The scripts and inputs for integration, run, and regression testing
+are maintained in a
+`separate repository <https://github.com/lammps/lammps-testing>`_
+of the LAMMPS project on GitHub.
+
 The unit testing facility is integrated into the CMake build process
 of the LAMMPS source code distribution itself.  It can be enabled by
 setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.
 It requires the `YAML <http://pyyaml.org/>`_ library and development
-headers (if not found locally a recent version will be downloaded
+headers (if those are not found locally a recent version will be
-and compiled transparently) to compile and will download and compile
+downloaded and compiled along with LAMMPS and the test program) to
-a specific recent version of the
+compile and will download and compile a specific recent version of the
 `Googletest <https://github.com/google/googletest/>`_ C++ test framework
 for implementing the tests.
 
@@ -164,22 +169,21 @@ The ``ctest`` command has many options, the most important ones are:
 In its full implementation, the unit test framework will consist of multiple
 kinds of tests implemented in different programming languages (C++, C, Python,
 Fortran) and testing different aspects of the LAMMPS software and its features.
-At the moment only tests for "force styles" are implemented. More on those
+The tests will adapt to the compilation settings of LAMMPS, so that tests
-in the next section.
+will be skipped if prerequisite features are not available in LAMMPS.
 
 .. note::
 
-   The unit test framework is new and still under development.
+   The unit test framework was added in spring 2020 and is under active
-   The coverage is only minimal and will be expanded over time.
+   development.  The coverage is not complete and will be expanded over
-   Tests styles of the same kind of style (e.g. pair styles or
+   time.
-   bond styles) are performed with the same executable using
+
-   different input files in YAML format.  So to add a test for
+Tests for styles of the same kind of style (e.g. pair styles or bond
-   another pair style can be done by copying the YAML file and
+styles) are performed with the same test executable using different
-   editing the style settings and then running the individual test
+input files in YAML format.  So to add a test for another style of the
-   program with a flag to update the computed reference data.
+same kind it may be sufficient to add a suitable YAML file.
-   Detailed documentation about how to add new test program and
+:ref:`Detailed instructions for adding tests <Developer_unittest>` are
-   the contents of the YAML files for existing test programs
+provided in the Programmer Guide part of the manual.
-   will be provided in time as well.
 
 Unit tests for force styles
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/src/Developer.rst

@@ -13,5 +13,6 @@ of time and requests from the LAMMPS user community.
    Developer_org
    Developer_flow
    Developer_write
+   Developer_unittest
    Classes
    Developer_utils

doc/src/Developer_unittest.rst

@@ -0,0 +1,45 @@
+Adding tests for unit testing
+-----------------------------
+
+This section discusses adding or expanding tests for the unit test
+infrastructure included into the LAMMPS source code distribution.
+Unlike example inputs, unit tests focus on testing the "local" behavior
+of individual features, tend to run very fast, and should be set up to
+cover as much of the added code as possible.  When contributing code to
+the distribution, the LAMMPS developers will appreciate if additions
+to the integrated unit test facility are included.
+
+Given the complex nature of MD simulations (i.e. many operations can
+only be performed when suitable "real" simulation environment has been
+set up) not all tests will be unit tests in the strict definition of
+the term, but rather be executed on a more abstract level by issuing
+LAMMPS script commands and then inspecting the changes to the internal
+data.  For some classes of tests, generic test programs have been
+written that can be applied to parts of LAMMPS that use the same
+interface (via polymorphism) and those are driven by input files, so
+tests can be added by simply adding more of those input files.
+
+
+Adding tests for styles computing forces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for individual LAMMPS commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for the C-style library interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for the Python module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for the Fortran interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for the C++-style library interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for utility functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding tests for programs in the tools folder
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^