Installation
Get SpecTracer running in your project in minutes. No databases, no servers — just Python and your test outputs.
Prerequisites
- Python 3.12+ — SpecTracer uses modern Python features and requires 3.12 or newer.
uv(recommended) — The fast Python package manager written in Rust. Install uv if you haven't already.- Your test outputs — JUnit XML from unit/integration tests and/or Cucumber JSON from E2E tests. Any framework that produces these formats works.
ℹ Python only, stack agnostic
The tool itself is Python, but it processes results from any language or framework. Your app can be Java, JavaScript, Go, Rust, or anything else — as long as your test runner outputs JUnit XML or Cucumber JSON, SpecTracer can consume it.
Install SpecTracer
Clone the repository and install dependencies:
Clone & install
git clone https://github.com/ampyard/spec-tracer.git
cd spec-tracer
uv syncThat's it. uv sync reads pyproject.toml and installs the only runtime dependency — Jinja2 for HTML templating — plus dev dependencies for running the tool's own test suite.
Alternative: Install via pip
If you prefer pip over uv:
pip install
pip install jinja2Verify Installation
Run the tool against the included sample data to verify everything works:
Verify
# Generate sample test results (the tool's own test suite)
uv run pytest tests/unit --junitxml=reports/unit.xml -q
uv run pytest tests/integration --junitxml=reports/int.xml -q
uv run behave features/ --format json -o reports/e2e.json 2> nul
# Generate a report
uv run python build_pyramid.py
# Open reports/spectracer-report.html in your browserIf you see a beautiful HTML report with coverage metrics, a test pyramid, and health checks — you're all set.
✓ Dogfooding
SpecTracer processes its own test outputs. The report you just generated is a self-report showing the tool's own test health.
Project Structure
A typical SpecTracer project looks like this:
your-project/
features/ # Gherkin .feature files (your truth)
login.feature
billing.feature
reports/ # Test outputs (generated by CI)
unit.xml
integration.xml
e2e.json
spectracer.config.json # Tool configuration (required)
build_pyramid.py # Entry point (from cloned repo)
report.html # Generated output (gitignore this)| Path | Purpose | VCS |
|---|---|---|
features/ | Gherkin .feature files defining all scenarios | Commit |
reports/ | JUnit XML / Cucumber JSON from test runs | Ignore |
spectracer.config.json | Configuration file (auto-discovered) | Commit |
report.html | Generated self-contained HTML report | Ignore |
First Configuration
Create a spectracer.config.json at your project root:
spectracer.config.json
{
"features": ["./features"],
"unit": {
"": ["./reports/unit.xml"]
},
"integration": {
"": ["./reports/integration.xml"]
},
"e2e": ["./reports/e2e.json"],
"output": "./report.html"
}Only features and output are required. Add test result paths as your pipeline generates them.