pytest-cpp

2.6.0 · active · verified Tue Apr 14

pytest-cpp is a pytest plugin that allows the pytest runner to discover and execute C++ tests. It supports popular frameworks like Google Test, Boost.Test, and Catch2. This integration enables running tests from multi-language projects with a single command, facilitates parallel execution with plugins like pytest-xdist, and provides uniform JUnit XML output. The current version is 2.6.0, with releases typically occurring 1-3 times per year, categorizing its release cadence as 'Slow'.

Warnings

gotcha Do not pass C++ test framework-specific filtering arguments (e.g., `--gtest_filter='*MyTest*'` or `--catch_test_filter '[tag]'`) directly via the `cpp_arguments` configuration option or command line. This can conflict with `pytest-cpp`'s native test filtering and lead to incorrect or unexpected behavior.
Fix: To filter C++ tests, use standard pytest filtering facilities like the `-k` (keyword) option, e.g., `pytest -k 'MyTest.SpecificCase'` or `pytest -k 'tag_name'`. pytest-cpp automatically maps these to the underlying C++ test framework's filtering mechanisms.
gotcha C++ test executables might not be discovered if their filenames do not match the default `pytest-cpp` discovery patterns (`test_*` or `*_test`).
Fix: Ensure your C++ test executables are named following `test_*.exe` or `*_test.exe` conventions. Alternatively, configure the `cpp_files` option in your `pytest.ini` file to specify custom patterns, e.g., `[pytest] cpp_files = my_app_tests*`.
gotcha C++ test executables must be properly compiled and dynamically linked with their respective test frameworks (Google Test, Boost.Test, Catch2) and any other necessary libraries (e.g., `pthread`). If they cannot run standalone, `pytest-cpp` will report execution failures.
Fix: Before running `pytest`, ensure your C++ test executable can be successfully executed directly from the command line, verifying all dependencies are met. Compile with appropriate flags (e.g., `-lgtest`, `-lgtest_main`, `-pthread` for Google Test) and ensure library paths are correctly configured for your environment.

Install

pip install pytest-cpp Install stable version

Imports

No direct imports for core functionality
```
pytest automatically discovers and loads the plugin once installed.
```
pytest-cpp operates as a plugin that pytest discovers and loads automatically. User-facing interactions are primarily through pytest's command-line interface and pytest.ini configuration, rather than direct Python imports from the `pytest_cpp` package for its core test discovery and execution features.

Quickstart

After installing `pytest-cpp`, create a C++ test file (e.g., `my_cpp_tests.cpp`) using a supported framework like Google Test. Compile it into an executable (e.g., `test_app`). By default, `pytest-cpp` discovers executables matching `test_*` or `*_test` patterns. Simply run `pytest` in the directory containing your compiled C++ test executable, and `pytest-cpp` will integrate and execute these tests alongside any Python tests.

/* C++ test file: my_cpp_tests.cpp (using Google Test) */
#include <gtest/gtest.h>

TEST(ExampleTest, Succeeds) {
    ASSERT_EQ(1, 1);
}

TEST(ExampleTest, Fails) {
    ASSERT_EQ(1, 2); // This test will fail
}

int main(int argc, char **argv) {
    ::testing::InitGoogleTest(&argc, argv);
    return RUN_ALL_TESTS();
}

# Compile the C++ test (example for Linux/macOS with g++ and Google Test)
# g++ my_cpp_tests.cpp -o test_app -I/usr/local/include -L/usr/local/lib -lgtest -lgtest_main -pthread
# (Adjust include/lib paths as needed for your system/build setup)

# To run with pytest-cpp:
# 1. Ensure pytest-cpp is installed: pip install pytest-cpp
# 2. Navigate to the directory containing 'test_app' executable.
# 3. Run pytest:
# pytest

# Example pytest.ini configuration to customize C++ file discovery:
# [pytest]
# cpp_files = my_cpp_test_exec*
#   cpp_arguments = -v

# Expected output for the above example (truncated):
# ============================= test session starts =============================
# ...
# collected 2 items
# 
# test_app::ExampleTest.Succeeds PASSED                                  [ 50%]
# test_app::ExampleTest.Fails FAILED                                   [100%]
# 
# =================================== FAILURES ==================================
# ____________________________ ExampleTest.Fails _____________________________
# 
#     ASSERT_EQ(1, 2), failed at my_cpp_tests.cpp:10
#     Expected: 1
#     Actual: 2
# 
# =========================== short test summary info ===========================
# FAILED test_app::ExampleTest.Fails - ASSERT_EQ(1, 2), failed at my_cpp_tests.cpp:10
# ========================= 1 failed, 1 passed in ...s =========================

view raw JSON →