Pytest JSON CTRF Reporter
raw JSON → 0.3.6 verified Sun Mar 29 auth: no python
pytest-json-ctrf is a pytest plugin that generates test reports in the Common Test Report Format (CTRF) as a JSON file. This standard format allows for consistent reporting across various testing tools and frameworks, facilitating better analysis and integration with external systems like GitHub Actions for prettifying reports. The current version is 0.3.6, with releases tied to pytest compatibility and feature enhancements.
pip install pytest-json-ctrf Common errors
error pytest: error: unrecognized arguments: --json-ctrf=report.json ↓
cause This error indicates that the `pytest-json-ctrf` plugin is either not installed or not accessible in the current Python environment where pytest is being executed, preventing pytest from recognizing its command-line option.
fix
Ensure the plugin is installed by running
pip install pytest-json-ctrf in the active Python environment. If already installed, verify the environment's PATH or virtual environment activation. error json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0) ↓
cause This error occurs when attempting to parse the generated CTRF report file (e.g., `report.json`), but the file is empty or contains malformed, non-JSON content.
fix
Verify that your pytest tests are actually running and producing reportable outcomes; an empty file often indicates no tests were executed or reported, or a prior error prevented report generation.
error FileNotFoundError: [Errno 2] No such file or directory: 'report.json' ↓
cause This error occurs when a subsequent command or script tries to access the CTRF report file, but it was either not generated, or not created in the expected directory.
fix
Confirm the
pytest --json-ctrf=report.json command was executed successfully without errors, and check the current working directory or specified path to ensure the report.json file exists in the expected location after the test run. error PermissionError: [Errno 13] Permission denied: 'report.json' ↓
cause Pytest-json-ctrf is attempting to create or write the report file in a directory where the running user or process does not have sufficient write permissions.
fix
Change the output directory to a location where the user has write permissions (e.g., the current working directory or a user-specific temporary directory), or adjust the file system permissions for the target directory.
Warnings
gotcha The `--ctrf` command-line option requires a file path argument. If not provided, pytest will not generate the CTRF report, or may raise an error depending on the pytest version. Ensure a valid file path is always specified. ↓
fix Always use `pytest --ctrf <your_report_file_name.json>`.
gotcha As a pytest plugin, `pytest-json-ctrf` is activated via a command-line option (`--ctrf`) rather than direct Python imports within your test code. Attempting to import symbols directly from `pytest_json_ctrf` in your tests is generally unnecessary and will likely result in an `ImportError` or other unexpected behavior. ↓
fix Ensure the plugin is installed (`pip install pytest-json-ctrf`) and activate it using the `--ctrf` command-line flag when running pytest. No explicit Python imports are typically needed in your test files for this plugin.
gotcha To ensure your tests are discovered and reported correctly by pytest (and subsequently by `pytest-json-ctrf`), adhere to pytest's standard test discovery rules: test files should start with `test_` or end with `_test.py`, and test functions/methods should start with `test_`. ↓
fix Rename test files and functions to follow pytest conventions (e.g., `test_my_feature.py`, `def test_functionality()`).
Quickstart last tested: 2026-04-24
import pytest
# tests/test_example.py
def test_passing_example():
assert True
def test_failing_example():
assert False
# To run and generate report:
# pytest --ctrf report.json
# cat report.json