Commit 1c547152 authored by Brad King's avatar Brad King 💬
Browse files

Tests: Document test directory layout in a README.rst

Cross-reference the CMake Source Code Guide document.
Also drop the outdated `Tests/README` file.
parent 4e3483c0
......@@ -93,7 +93,7 @@ The CMake source tree is organized as follows.
packagers, etc.
* ``Tests/``:
The test suite.
The test suite. See `Tests/README.rst`_.
* ``Utilities/``:
Scripts, third-party source code.
......@@ -103,3 +103,5 @@ The CMake source tree is organized as follows.
* ``Utilities/Release/``:
Scripts used to package CMake itself for distribution on ``cmake.org``.
.. _`Tests/README.rst`: ../../Tests/README.rst
If you think about adding a new testcase then here is a small checklist you
can run through to find a proper place for it. Go through the list from the
beginning and stop once you find something that matches your tests needs,
i.e. if you will test a module and only need the configure mode use the
instructions from section 2, not 3.
1. Your testcase can run in CMake script mode, i.e. "cmake -P something"
Put your test in Tests/CMakeTests/ directory as a .cmake.in file. It will be
put into the test binary directory by configure_file(... @ONLY) and run from
there. Use the AddCMakeTest() macro in Tests/CMakeTests/CMakeLists.txt to add
your test to the test runs.
2. Your test needs CMake to run in configure mode, but will not build anything
This includes tests that will build something using try_compile() and friends,
but nothing that expects add_executable(), add_library(), or add_test() to run.
If the test configures the project only once and it must succeed then put it
into the Tests/CMakeOnly/ directory. Create a subdirectory named like your
test and write the CMakeLists.txt you need into that subdirectory. Use the
add_CMakeOnly_test() macro from Tests/CMakeOnly/CMakeLists.txt to add your
test to the test runs.
If the test configures the project with multiple variations and verifies
success or failure each time then put it into the Tests/RunCMake/ directory.
Read the instructions in Tests/RunCMake/CMakeLists.txt to add a test.
3. If you are testing something from the Modules directory
Put your test in the Tests/Modules/ directory. Create a subdirectory there
named after your test. Use the ADD_TEST_MACRO macro from Tests/CMakeLists.txt
to add your test to the test run. If you have put your stuff in
Tests/Modules/Foo then you call it using ADD_TEST_MACRO(Module.Foo Foo).
4. You are doing other stuff.
Find a good place ;) In doubt mail to cmake-developers@cmake.org and ask for
advise.
CMake Tests Directory
*********************
This directory contains the CMake test suite.
See also the `CMake Source Code Guide`_.
.. _`CMake Source Code Guide`: ../Help/dev/source.rst
Many tests exist as immediate subdirectories, but some tests
are organized as follows.
* ``CMakeLib/``:
Source code, used for tests, that links to the ``CMakeLib`` library
defined over in ``Source/``.
* ``CMakeOnly/``:
Deprecated. Tests that run CMake to generate a project but not build it.
Superseded by ``Tests/RunCMake/``.
* ``Find*/``:
Tests for specific find modules that can only be run on machines with
the corresponding packages installed. They are enabled in
``CMakeLists.txt`` by undocumented options used on CI builds.
* ``Module/``:
Tests for specific CMake modules.
* ``RunCMake/``:
Tests that run CMake and/or other tools while precisely checking
their return code and stdout/stderr content. Useful for testing
error cases and diagnostic output.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment