.. Copyright 2021 CMakePP
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
.. http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.
..
###########
CMinx Tests
###########

The ``tests`` directory contains files related to testing CMinx and the code
snippets found in the documentation.

******************************
Building and Running the Tests
******************************

In order to run all of the tests CMinx needs to have been built with CMake.
This is because part of the test suite tests the CMake API, which in turn
requires calling CMinx from CMake. The following commands with configure, build,
and test CMinx (assumed to be run from the root of this repository):

.. code::

   cmake -S . -B <build_dir> -DBUILD_TESTING=on
   cmake --build <build_dir>
   cd <build_dir>
   ctest

See `here <https://cmakepp.github.io/CMinx/installation.html>`__ for full
documentation on how to configure and build CMinx with CMake. The key points
are you need to enable testing (done by enabling ``BUILD_TESTING``) and that
you need to run ``ctest`` in the build directory.

If CMinx was built with Python you can still run all the tests, except the ones
pertaining to the CMake API. To test CMinx built with Python you first need to
install the extra unit test dependencies (run in root directory):

.. code::

   pip install -e .[testing]

After installing the extra packages needed for unit testing, the unit tests can
be run with (still in this directory):

.. code::

   python3 -B test_all.py

Pay attention to the ``-B``, this tells Python not to generate ``__pycache__``.
If you leave off the ``-B`` then CMinx's recursive mode will try to generate
documentation for the ``__pycache__`` directories. The ``index.rst`` files
generated by the unit tests will not match the expected output, and the unit
tests will fail.

****************************
``tests`` Directory Overview
****************************

- ``cmake/`` contains unit tests of CMinx's CMake API.
- ``cmake_input/`` contains actual marked-up CMake source code that is used in
  various CMinx unit tests.
- ``examples/`` contains examples of how to write CMinx documentation, and  how
  to use the Python classes which are part of CMinx. Compared to the content in
  the ``test_samples`` directory, the contents of ``examples`` are meant to be
  more tutorial like whereas the contents of ``test_samples`` are more
  snippet-like.
- ``test_samples/`` contains the code snippets used throughout the documentation
  to demonstrate CMinx features. Also included for each snippet is the reST
  which results from running CMinx on the snippet.
- ``unit_tests/`` contains unit tests for the Python classes and functions
  comprising CMinx.
- ``.coveragerc`` contains settings for generating code coverage with
  Coverage.py
- ``CMakeLists.txt`` tells CMake about the test suite
- ``context.py`` contains paths and other parameters used throughout the test
  suite.
- ``helpers.py`` contains functions used throughout the test suite
- ``README.rst`` the present file, provides helpful (hopefully) notes about the
  ``tests`` directory and how to test CMinx
- ``test_all.py`` top-level script for running all of the unit tests
