Requirements traceability for Python test suites – Ensure every requirement is tested and every test is traceable.
A pytest plugin and CLI tool that validates requirement coverage, prevents specification drift, and auto-generates traceability documentation for compliance-critical projects.
In regulated industries (medical devices, aerospace, automotive) and quality-critical software, you need to prove that every requirement has corresponding tests. Manual traceability matrices become outdated instantly. pytreqt automates this:
- Prevents broken references: Catches typos in requirement IDs before they reach production
- Enforces bidirectional traceability: Links requirements ↔ tests in both directions
- Detects coverage gaps: Shows which requirements lack test coverage
- Identifies change impact: When a requirement changes, immediately see affected tests
- Generates compliance artifacts: Auto-creates TEST_COVERAGE.md for audits and reviews
| Feature | Description |
|---|---|
| ✅ Real-time validation | Validates requirement IDs in test docstrings against specification files during test runs |
| 🎨 Rich terminal output | Colorful reporting with ✓ (passed), ✗ (failed), ⊝ (skipped) status indicators |
| 📊 Coverage analysis | Reports showing which requirements are tested and which are missing |
| 🚫 Typo prevention | Catches invalid requirement references before they cause compliance issues |
| 📈 Auto-generated docs | Creates TEST_COVERAGE.md with complete traceability matrix |
| 🔍 Change detection | Identifies tests affected by requirement updates |
| 🔌 Seamless integration | Works as both a pytest plugin and standalone CLI tool |
| ⚙️ Flexible configuration | Supports custom requirement patterns (FR-, US-, REQ-*, etc.) |
pip install pytreqtOr with uv (recommended):
uv add pytreqtpytreqt initThis creates a pytreqt.toml configuration file with sensible defaults.
def test_user_login():
"""
Verify user authentication functionality.
Tests: FR-1.1, FR-1.2
"""
assert authenticate_user("user", "password") == Truepytreqt coveragepytreqt showCreate a pytreqt.toml file or add to your pyproject.toml:
[tool.pytreqt]
requirements_file = "docs/requirements.md"
requirement_patterns = ["FR-\\d+\\.?\\d*", "BR-\\d+\\.?\\d*"]| Option | Description | Example |
|---|---|---|
requirements_file |
Path to requirements specification | "docs/requirements.md" |
requirement_patterns |
Regex patterns for requirement IDs | ["FR-\\d+", "US-\\d+"] |
pytreqt works seamlessly as a pytest plugin. Enable it in your pyproject.toml:
[tool.pytest.ini_options]
addopts = "-p pytreqt"Now pytreqt will automatically validate requirement references during test runs:
pytest # pytreqt validation runs automaticallyEnsure every safety requirement has corresponding test coverage and maintain traceability matrices for regulatory submissions.
Track safety requirements through the entire test suite, automatically detect untested requirements.
Generate traceability documentation required for certification, validate requirement-test linkage.
Maintain compliance audit trails, prove that security requirements are properly tested.
Keep living documentation synchronized with tests, prevent requirement drift during rapid iterations.
- Python 3.10 or newer
- uv (recommended) or pip
# Clone the repository
git clone https://github.com/pytreqt/pytreqt.git
cd pytreqt
# Install in development mode with all dependencies
uv sync --all-extras --devWe use Nox for automated testing across multiple Python and pytest versions:
# Test all Python/pytest combinations
uv run nox
# Test specific Python version
uv run nox -s tests-3.13
# Test specific combination
uv run nox -s "tests-3.13(pytest_version='8.3')"
# Run quality checks
uv run nox -s lint mypy
# Generate coverage report
uv run nox -s coverage
# List all available sessions
uv run nox --listSupported test matrix:
- Python: 3.10, 3.11, 3.12, 3.13
- pytest: 8.0, 8.3
- Automatically skips incompatible combinations
# Run tests
uv run pytest tests/
# Linting and formatting
uv run ruff check src/
uv run ruff format src/
# Type checking
uv run mypy src/
# Check file endings
uv run ./src/pytreqt/tools/check_newlines.pyContributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run quality checks:
uv run nox - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure:
- All tests pass across supported Python/pytest versions
- Code follows ruff formatting standards
- Type hints are present and mypy checks pass
- Documentation is updated for new features
🚧 Alpha – This package is in active development. Core features are functional, but the API may change. Production use is possible but expect updates.
Roadmap:
- Support for additional requirement formats (YAML, JSON, DOORS exports)
- Integration with CI/CD systems (GitHub Actions, GitLab CI)
- HTML report generation
- VSCode extension for real-time validation
- Requirements change impact visualization
MIT License - Copyright (c) 2025 Jörn Preuß
See LICENSE file for full details.
Jörn Preuß 📧 joern.preuss@gmail.com 🔗 GitHub
Built with: