Architecture

SpecTracer is a lean Python CLI with no heavy infrastructure. Four modules orchestrate a simple pipeline: collect → parse → link → aggregate → render.

Pipeline Overview

  .feature                JUnit XML             Cucumber JSON
     |                        |                       |
     v                        v                       v
  FeatureParser          JunitParser           CucumberParser
     |                        |                       |
     +-----------─────+─────────+
                 |                       |
              Scenario[]           TestResult[]
                 |                       |
                 +--------> Linker <--------+
                               |
                     LinkedScenarioView[]
                               |
                          Aggregator
                               |
                     AggregatedData{views, stats, health}
                               |
                          HtmlRenderer
                               |
                          report.html

Modules

Parsers

Linker

The linker is the simplest but most important module. It performs OR-based tag matching:

• For each scenario, find all test results where any tag appears in the scenario's linking tags
• @require-* tags are stripped before linking — they never participate
• Tag matching is exact string equality only — no wildcards, no expressions
• One test result can link to multiple scenarios (tag collision)

def link(scenarios, results):
    for scenario in scenarios:
        linked = [
            r for r in results
            if any(tag in r.tags for tag in scenario.linking_tags)
        ]
        yield ScenarioView(scenario, linked)

Aggregator

The ReportAggregator transforms linked data into report views. All methods are static:

Renderer

The HtmlRenderer uses Jinja2 to produce a single self-contained HTML file. Everything is inlined:

• CSS: Full stylesheet with dark mode support via prefers-color-scheme: dark
• JavaScript: Client-side hash routing (#/, #/pyramid, etc.), sortable tables, search/filter
• Logo: Optional base64-encoded PNG
• Data: All report data is embedded as JSON in a <script> tag

The report file has zero external dependencies — it works offline, on any OS, in any modern browser.

Data Flow

Here's exactly what happens when you run uv run python build_pyramid.py:

1. Config loading — cli.py discovers and reads the JSON config file. Validates required keys (features, output).
2. File collection — FileCollector resolves glob patterns and directory recursion for feature files, JUnit XML, and Cucumber JSON paths.
3. Parsing — Each file type is parsed by its dedicated parser. Scenarios and test results are extracted into typed data classes.
4. Linking — ResultLinker cross-references scenario tags against test result tags. OR logic: any shared tag creates a link.
5. Aggregation — ReportAggregator computes all stats, views, breakdowns, and health checks from the linked data.
6. Rendering — HtmlRenderer feeds the aggregated data into a Jinja2 template and writes the output file.

Tag Resolution Order

When parsing a .feature file, tags are resolved as follows:

1. All tags on lines immediately above a Scenario: line are collected
2. Tags matching the pattern @require-(unit|integration|e2e)(:\w+)? are classified as layer requirements
3. All remaining tags become linking tags
4. If zero requirement tags were found, the scenario defaults to @require-e2e

Testing Strategy (Dogfooding)

SpecTracer tests itself using its own input formats — an approach called outside-in dogfooding.

The CI pipeline runs all three layers, collects the outputs, and feeds them into SpecTracer to generate a self-report — a coverage report for SpecTracer itself. Every feature starts as a .feature file, validated by a behave E2E scenario before implementation.

uv run behave features/ --format json -o reports/e2e.json
uv run pytest tests/unit --junitxml=reports/unit.xml
uv run pytest tests/integration --junitxml=reports/int.xml

uv run python build_pyramid.py
# Output: reports/spectracer-report.html — a self-report