Pytest CMake

https://python-cmake.github.io/pytest-cmake
Admin
Pytest CMake is a tool that integrates Pytest with CMake, allowing users to easily discover and run...
Tokens:6,846
Snippets:121
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Build example project

Source: https://python-cmake.github.io/pytest-cmake/integration.html

Commands to configure and build an example project requiring nanobind.

```bash
cmake -S ./example -B ./build -D "nanobind_ROOT=$(python -m nanobind --cmake-dir)"
cmake --build ./build
```

--------------------------------

### Install Documentation Dependencies

Source: https://python-cmake.github.io/pytest-cmake/_sources/installing.rst.txt

Installs the necessary requirements to build the project documentation.

```bash
pip install -r ./doc/requirements.txt
```

--------------------------------

### Build and test example project

Source: https://python-cmake.github.io/pytest-cmake/_sources/integration.rst.txt

Commands to build the example project and execute tests using ctest.

```bash
cmake -S ./example -B ./build -D "nanobind_ROOT=$(python -m nanobind --cmake-dir)"
cmake --build ./build
ctest --test-dir ./build -VV
```

--------------------------------

### Install from Source

Source: https://python-cmake.github.io/pytest-cmake/_sources/installing.rst.txt

Builds and installs the package from the local directory into the current Python environment. Note that editable mode is not supported.

```bash
pip install .
```

--------------------------------

### Locate configuration files

Source: https://python-cmake.github.io/pytest-cmake/installing.html

The path where configuration files are placed after installation.

```text
<python_prefix>/share/Pytest/cmake
```

--------------------------------

### Clone Source Repository

Source: https://python-cmake.github.io/pytest-cmake/_sources/installing.rst.txt

Retrieves the source code from the public repository for manual installation.

```bash
git clone git@github.com:python-cmake/pytest-cmake.git
```

--------------------------------

### Install via Pip

Source: https://python-cmake.github.io/pytest-cmake/_sources/installing.rst.txt

Installs the Pytest CMake configuration package using Pip, which automatically handles Pytest dependencies.

```bash
pip install pytest-cmake
```

--------------------------------

### View CTest output for bundled tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Example output showing a single consolidated test result when BUNDLE_TESTS is enabled.

```console
    Start 1: PythonTest
1/1 Test #1: PythonTest .......................   Passed    0.51 sec
```

--------------------------------

### Example test execution output

Source: https://python-cmake.github.io/pytest-cmake/_sources/introduction.rst.txt

Displays the console output format when running discovered Python tests via CTest.

```console
    Start 1: PythonTest.greet_world
1/4 Test #1: PythonTest.greet_world ...........   Passed    0.47 sec
    Start 2: PythonTest.greet_john
2/4 Test #2: PythonTest.greet_john ............   Passed    0.47 sec
    Start 3: PythonTest.greet_julia
3/4 Test #3: PythonTest.greet_julia ...........   Passed    0.47 sec
    Start 4: PythonTest.greet_michael
4/4 Test #4: PythonTest.greet_michael .........   Passed    0.54 sec
```

--------------------------------

### Configure Python test discovery with pytest_discover_tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Basic setup for discovering Python tests, including library path configuration and test name trimming.

```cmake
pytest_discover_tests(
    PythonTest
    LIBRARY_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
    PYTHON_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
    TRIM_FROM_NAME "^(Test|test_)"
    INCLUDE_FILE_PATH
    DEPENDS MyLibrary
)
```

--------------------------------

### CTest discovery output

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Example console output showing multiple tests discovered and executed by CTest.

```console
    Start 1: PythonTest.test_greet_world
1/4 Test #1: PythonTest.test_greet_world ...........   Passed    0.47 sec
    Start 2: PythonTest.test_greet_john
2/4 Test #2: PythonTest.test_greet_john ............   Passed    0.47 sec
    Start 3: PythonTest.test_greet_julia
3/4 Test #3: PythonTest.test_greet_julia ...........   Passed    0.47 sec
    Start 4: PythonTest.test_greet_michael
4/4 Test #4: PythonTest.test_greet_michael .........   Passed    0.54 sec
```

--------------------------------

### View CTest output for discovered tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Example output showing individual test execution results after running CTest.

```console
    Start 1: PythonTest.greet_world
1/4 Test #1: PythonTest.greet_world ...............   Passed    0.47 sec
    Start 2: PythonTest.greet_john
2/4 Test #2: PythonTest.greet_john ................   Passed    0.47 sec
    Start 3: PythonTest.greet_julia
3/4 Test #3: PythonTest.greet_julia ...............   Passed    0.47 sec
    Start 4: PythonTest.subfolder.greet_michael
4/4 Test #4: PythonTest.subfolder.greet_michael ...   Passed    0.54 sec
```

--------------------------------

### CTest execution output

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Example console output from CTest showing test success and failure states.

```console
    Start 1: PythonTest
1/1 Test #1: PythonTest .......................   Passed    0.55 sec
```

```console
    Start 1: PythonTest
1/1 Test #1: PythonTest .......................***Failed    0.47 sec
```

--------------------------------

### Build Documentation

Source: https://python-cmake.github.io/pytest-cmake/_sources/installing.rst.txt

Generates the documentation using Sphinx.

```bash
sphinx-build ./doc ./build/doc/html
```

--------------------------------

### View documentation path

Source: https://python-cmake.github.io/pytest-cmake/installing.html

The local file path to access the generated documentation.

```text
file:///path/to/sphinx-build/build/doc/html/index.html
```

--------------------------------

### Configure LIBRARY_PATH_PREPEND

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Prepend library paths to the system library environment variable.

```cmake
pytest_discover_tests(
    ...
    LIBRARY_PATH_PREPEND
        $<TARGET_FILE_DIR:lib1>
        $<TARGET_FILE_DIR:lib2>
        /path/to/libs/
)
```

--------------------------------

### Configure TEST_PATHS

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Specify directories or files to search for tests.

```cmake
pytest_discover_tests(
    ...
    TEST_PATHS
        path1
        path2/test.py
)
```

--------------------------------

### Configure ENVIRONMENT

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Set custom environment variables for test execution.

```cmake
pytest_discover_tests(
    ...
    ENVIRONMENT
        "ENV_VAR1=VALUE1"
        "ENV_VAR2=VALUE2"
        "ENV_VAR3=VALUE3"
)
```

--------------------------------

### Run tests with ctest

Source: https://python-cmake.github.io/pytest-cmake/integration.html

Command to execute tests using ctest with verbose output.

```bash
ctest --test-dir ./build -VV
```

--------------------------------

### Configure PYTHON_PATH_PREPEND

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Prepend paths to the PYTHONPATH environment variable.

```cmake
pytest_discover_tests(
    ...
    PYTHON_PATH_PREPEND
        $<TARGET_FILE_DIR:lib1>
        $<TARGET_FILE_DIR:lib2>
        /path/to/python/
)
```

--------------------------------

### Configure PROPERTIES

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Apply CTest properties to all generated tests.

```cmake
pytest_discover_tests(
    ...
    PROPERTIES
        LABELS "python;unit"
        TIMEOUT 120
)
```

--------------------------------

### Dynamically gather test files with GLOB_RECURSE

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Uses CMake's file command to dynamically collect Python test files for dependency tracking.

```cmake
file(GLOB_RECURSE test_files "/path/to/tests/*.py")

pytest_discover_tests(
    ...
    DEPENDS ${test_files}
)
```

--------------------------------

### Configure environment variables for tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Set PYTHONPATH and library paths using generator expressions to ensure the test can locate the built library.

```cmake
set_tests_properties(
    TEST PythonTest
    PROPERTY ENVIRONMENT
        PYTHONPATH=$<TARGET_FILE_DIR:MyLibrary>:$ENV{PYTHONPATH}
)
```

```cmake
set_tests_properties(
    TEST PythonTest
    APPEND PROPERTY ENVIRONMENT
        LD_LIBRARY_PATH=$<TARGET_FILE_DIR:MyLibrary>:$ENV{LD_LIBRARY_PATH}
)
```

--------------------------------

### Configure LD_LIBRARY_PATH for tests

Source: https://python-cmake.github.io/pytest-cmake/tutorial.html

Appends the library directory to the environment variable required for runtime shared library resolution.

```cmake
set_tests_properties(
    TEST PythonTest
    APPEND PROPERTY ENVIRONMENT
        LD_LIBRARY_PATH=$<TARGET_FILE_DIR:MyLibrary>:$ENV{LD_LIBRARY_PATH}
)
```

--------------------------------

### Enable INCLUDE_FILE_PATH

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Include the source file path in the generated test name to distinguish tests with identical names.

```cmake
pytest_discover_tests(
    ...
    INCLUDE_FILE_PATH
)
```

--------------------------------

### Configure Pytest root path

Source: https://python-cmake.github.io/pytest-cmake/_sources/integration.rst.txt

Specify the Pytest_ROOT path via CLI when using virtual environments or non-standard locations.

```bash
cmake -S . -B ./build -D "Pytest_ROOT=$(python -m pytest_cmake --cmake-dir)"
```

--------------------------------

### Configure DEPENDS

Source: https://python-cmake.github.io/pytest-cmake/api_reference.html

Specifies dependencies for the test target, including targets or specific Python files.

```cmake
pytest_discover_tests(
    ...
    DEPENDS lib1 lib2
)
```

```cmake
pytest_discover_tests(
    ...
    DEPENDS
        /path/to/test_foo.py
        /path/to/test_bar.py
)
```

```cmake
file(GLOB_RECURSE test_files "/path/to/tests/*.py")

pytest_discover_tests(
    ...
    DEPENDS ${test_files}
)
```

--------------------------------

### Discover Python tests with pytest_discover_tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/introduction.rst.txt

Configure automatic CTest generation for Python tests, including library path and dependency management.

```cmake
pytest_discover_tests(
    PythonTest
    LIBRARY_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
    PYTHON_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
    TRIM_FROM_NAME "^test_"
    DEPENDS MyLibrary
)
```

--------------------------------

### pytest_discover_tests function signature

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

The base signature for the pytest_discover_tests function.

```cmake
pytest_discover_tests(NAME
    [TEST_PATHS path1 path2...]
    [WORKING_DIRECTORY dir]
    [TRIM_FROM_NAME pattern]
    [TRIM_FROM_FULL_NAME pattern]
    [LIBRARY_PATH_PREPEND path1 path2...]
    [PYTHON_PATH_PREPEND path1 path2...]
    [ENVIRONMENT env1 env2...]
    [PROPERTIES prop1 prop2...]
    [DEPENDS target1 target2...]
    [INCLUDE_FILE_PATH]
    [STRIP_PARAM_BRACKETS]
    [BUNDLE_TESTS]
    [EXTRA_ARGS arg1 arg2...]
    [DISCOVERY_EXTRA_ARGS arg1 arg2...]
)
```

--------------------------------

### Pass extra arguments to Pytest discovery

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Provides additional command-line arguments specifically for the test discovery phase.

```cmake
pytest_discover_tests(
    ...
    DISCOVERY_EXTRA_ARGS "-k=expression"
)
```

--------------------------------

### Configure TRIM_FROM_FULL_NAME

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Use a regular expression to trim parts of the generated full test name.

```cmake
pytest_discover_tests(
    ...
    TRIM_FROM_FULL_NAME "(Test|test_)"
)
```

--------------------------------

### Enable STRIP_PARAM_BRACKETS

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Remove square brackets from parametrized test identifiers.

```cmake
pytest_discover_tests(
    ...
    STRIP_PARAM_BRACKETS
)
```

--------------------------------

### Configure TRIM_FROM_NAME

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Use a regular expression to remove prefixes from discovered test names.

```cmake
pytest_discover_tests(
    ...
    TRIM_FROM_NAME "^(Test|test_)"
)
```

--------------------------------

### Define a Pytest test in CMake

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Use the add_test function to register a Python test command.

```cmake
add_test(
    NAME PythonTest
    COMMAND Pytest::Pytest ${CMAKE_CURRENT_SOURCE_DIR}
)
```

--------------------------------

### Pass extra arguments to Pytest execution

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Provides additional command-line arguments to the Pytest process for each test case.

```cmake
pytest_discover_tests(
    ...
    EXTRA_ARGS "--capture=no" "--cmdopt=demo"
)
```

--------------------------------

### Locate Pytest with CMake

Source: https://python-cmake.github.io/pytest-cmake/_sources/integration.rst.txt

Use find_package to integrate the package into a CMake project.

```cmake
find_package(Pytest)
```

--------------------------------

### Bundle tests into a single CTest target

Source: https://python-cmake.github.io/pytest-cmake/tutorial.html

Configuration using BUNDLE_TESTS to group all tests under one CTest execution.

```cmake
 pytest_discover_tests(
     PythonTest
     LIBRARY_PATH_PREPEND
         $<TARGET_FILE_DIR:MyLibrary>
     PYTHON_PATH_PREPEND
         $<TARGET_FILE_DIR:MyLibrary>
     DEPENDS MyLibrary
     BUNDLE_TESTS True
 )
```

--------------------------------

### Bundle tests into a single CTest execution

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Configure pytest_discover_tests to group all tests under one CTest entry by setting BUNDLE_TESTS to True.

```cmake
pytest_discover_tests(
    PythonTest
    LIBRARY_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
    PYTHON_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
    DEPENDS MyLibrary
    BUNDLE_TESTS True
)
```

--------------------------------

### pytest_discover_tests(NAME ARGV)

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

The pytest_discover_tests function is used to discover Python tests and register them as CTest tests within a CMake build system.

```APIDOC
## pytest_discover_tests(NAME ARGV)

### Description
Automatically create CTest tests for Python tests collected with Pytest within a controlled environment.

### Parameters
- **NAME** (string) - Required - The name of the target to be created.
- **TEST_PATHS** (list) - Optional - List of files or directories to search for tests.
- **WORKING_DIRECTORY** (string) - Optional - Directory in which to run the Pytest command.
- **TRIM_FROM_NAME** (regex) - Optional - Regular expression to trim parts of discovered test names.
- **TRIM_FROM_FULL_NAME** (regex) - Optional - Regular expression to trim parts of the full generated test name.
- **LIBRARY_PATH_PREPEND** (list) - Optional - Library paths to prepend to system library environment variables.
- **PYTHON_PATH_PREPEND** (list) - Optional - Python paths to prepend to PYTHONPATH.
- **ENVIRONMENT** (list) - Optional - Custom environment variables to set during test execution.
- **PROPERTIES** (list) - Optional - CMake test properties to apply to generated tests.
- **DEPENDS** (list) - Optional - List of targets the tests depend on.
- **INCLUDE_FILE_PATH** (flag) - Optional - Include file path in generated test names.
- **STRIP_PARAM_BRACKETS** (flag) - Optional - Remove square brackets from parametrized test identifiers.
```

--------------------------------

### Configure PYTHONPATH for tests

Source: https://python-cmake.github.io/pytest-cmake/tutorial.html

Updates the PYTHONPATH environment variable to include the directory of the dependent library.

```cmake
set_tests_properties(
    TEST PythonTest
    PROPERTY ENVIRONMENT
        PYTHONPATH=$<TARGET_FILE_DIR:MyLibrary>:$ENV{PYTHONPATH}
)
```

--------------------------------

### Define Python test file dependencies

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Ensures the test target rebuilds when specific Python test files are modified.

```cmake
pytest_discover_tests(
    ...
    DEPENDS
        /path/to/test_foo.py
        /path/to/test_bar.py
)
```

--------------------------------

### pytest_discover_tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

A CMake function that discovers Pytest tests and creates CTest entries for them.

```APIDOC
## pytest_discover_tests

### Description
This function discovers Pytest tests and registers them as CTest tests. It supports specifying dependencies, bundling tests, and passing extra arguments to the Pytest command line.

### Parameters
- **DEPENDS** (list) - Optional - List of dependent targets or Python test files that trigger a rebuild when modified.
- **BUNDLE_TESTS** (boolean) - Optional - If set, bundles Python tests under a single CTest test for improved performance via Pytest caching and fixtures.
- **EXTRA_ARGS** (list) - Optional - Extra arguments passed to the Pytest command line for each test case.
- **DISCOVERY_EXTRA_ARGS** (list) - Optional - Extra arguments passed to the Pytest command line during the test discovery phase.
```

--------------------------------

### Target specific Pytest versions

Source: https://python-cmake.github.io/pytest-cmake/_sources/integration.rst.txt

Specify version constraints using find_package arguments.

```cmake
# Request Pytest version 7.2.0.
find_package(Pytest 7.2.0 EXACT REQUIRED)

# Request Pytest between version 6.0.0 and 7.2.0 included.
find_package(Pytest 6.0.0...7.2.0 REQUIRED)

# Request any version of Pytest over 4.6.11.
find_package(Pytest 4.6.11 REQUIRED)
```

--------------------------------

### pytest_discover_tests

Source: https://python-cmake.github.io/pytest-cmake/api_reference.html

The primary function used to discover and register Pytest tests as CTest tests. It supports various configuration options to control test execution and discovery.

```APIDOC
## pytest_discover_tests

### Description
Creates CTest tests for each Pytest test discovered. This function works similarly to the gtest_discover_tests function.

### Parameters
- **BUNDLE_TESTS** (option) - Optional - Indicate whether Python tests should be bundled under a single CTest test. Can also be set via the BUNDLE_PYTHON_TESTS environment variable.
- **EXTRA_ARGS** (list) - Optional - List of extra arguments to pass on the Pytest command line for each test case.
- **DISCOVERY_EXTRA_ARGS** (list) - Optional - List of extra arguments to pass on the Pytest command line for the test discovery process.

### Usage Example
```cmake
pytest_discover_tests(
    EXTRA_ARGS "--capture=no" "--cmdopt=demo"
    DISCOVERY_EXTRA_ARGS "-k=expression"
)
```
```

--------------------------------

### Define dependent targets for pytest_discover_tests

Source: https://python-cmake.github.io/pytest-cmake/_sources/api_reference.rst.txt

Specifies targets that must be built before running the tests.

```cmake
pytest_discover_tests(
    ...
    DEPENDS lib1 lib2
)
```

--------------------------------

### Pytest test identifier

Source: https://python-cmake.github.io/pytest-cmake/_sources/tutorial.rst.txt

Format of a fully identified test collected by Pytest.

```console
tests/test_module.py::TestMyClass::test_example
```
Tokens:
Raw