Finite Element Discretization Library
                                   __
                       _ __ ___   / _|  ___  _ __ ___
                      | '_ ` _ \ | |_  / _ \| '_ ` _ \
                      | | | | | ||  _||  __/| | | | | |
                      |_| |_| |_||_|   \___||_| |_| |_|

                               https://mfem.org

This directory contains several shell scripts that perform simple checks on the
MFEM sources and Git commits including: code styling, documentation formatting,
proper use of .gitignore, and preventing the accidental commit of large files.

Use by developers
=================
It is recommended that developers run these tests scripts and verify that they
complete successfully before pushing to GitHub. For example:

   cd tests/scripts
   ./runtest ../.. code-style documentation gitignore branch-history

See the sections below for details on runtest and the available test scripts.

The runtest script
==================
The tests in the tests/scripts directory can be run directly, e.g.

   cd tests/scripts
   ./documentation

However, it is easier to detect issues when they are run through the runtest
script:

   ./runtest ../.. documentation

The above command will create separate files, "documentation.out" and
"documentation.err" with the standard output and error generated by the script.
A test is considered to pass if its corresponding *.err file is empty.

Several tests can be run together:

   ./runtest code-style documentation

Each test provides a short help message, e.g.

   ./documentation [-h|-help] {mfem_dir}

   where: {mfem_dir}  is the MFEM source directory [default value: ../..]
          -h|-help    prints this usage information and exits

   This script runs documentation-related tests in mfem_dir. It checks in
   particular the Doxygen formatting used in code comments.

   Example usage: ./documentation ../..

including the runtest script itself

   ./runtest [-h|-help] {mfem_dir} {test1} {test2} ...

   where: {mfem_dir}  is the MFEM source directory [default value: ../..]
          {test1}...  are the sequence of tests to run
          -h|-help    prints this usage information and exits

   This script runs a sequence of tests using the code in mfem_dir (note that
   specifying the directory is optional). For each test, the standard output and
   standard error are saved in files test.out and test.err respectively in the
   current directory [1]. The output file interleaves stdout and stderr, while
   the error file is filtered by removing test-specific patterns specified in an
   optional test.filters file in the test directory [2]. After filtering, empty
   error files are erased, signifying that the corresponding test has passed.

   [1] run directory  = ~/mfem/tests/scripts
   [2] test directory = ~/mfem/tests/scripts

   Example usage: ./runtest ../..

Available test scripts
======================
A test script is just a simple shell (bash) scripts that produces output on the
standard error to indicate a problem.

The currently available test scripts are:

- code-style: Checks if the code conforms to the MFEM C++ style. The script also
  verifies that std::cout and std::cerr are not used in the library.

- documentation: Checks the Doxygen documentation formatting.

- gitignore: Checks for compliance with MFEM's .gitignore rules

- branch-history: Checks if the current branch history (the commits that will be
  merged in master) contains unusually large files, unusually large number of
  changes in a commit, unusually large number of commits, etc.

Adding new test scripts is easy and we welcome contributions from users and
developers.