The tagging model

Tags are the entire interface between your specification and your test suites. There are exactly three kinds, they do three different jobs, and they never interfere with each other. Understanding this page means understanding SpecTracer.

The three tag roles

The split matters. Identity and reference tags decide what links to what. Requirement tags decide what counts as done. Because they use different prefixes, adding a requirement can never accidentally create or break a link.

Feature: User Login

  @id:FC-42 @regression @require-unit:auth @require-integration:auth @require-e2e:auth
  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When they enter valid credentials
    Then they should be redirected to the dashboard

  @id:FC-43
  Scenario: Login with invalid password shows error
    Given the user is on the login page
    When they enter an invalid password
    Then an error message should be displayed

FC-43 declares no requirements, so it falls back to a bare @require-e2e — see defaults.

How linking works

The linker is deliberately the dumbest part of the tool. For each scenario it collects the set of values after @id:, then keeps every test result carrying an @scenario: tag whose value is in that set. E2E results get one extra rule: an @id: tag on an E2E result counts the same as a matching @scenario: tag. This is not a new tagging convention — it's recognizing that an E2E result comes from running the same feature file the scenario is declared in, so its Cucumber JSON already carries the scenario's own @id: tag verbatim. You don't have to add a redundant @scenario: tag next to it just to make linking happen. Unit and integration results aren't run from the feature file, so they still need an explicit @scenario: tag.

def link(scenarios, results):
    links = {}
    for scenario in scenarios:
        ids = {t[4:] for t in scenario.tags if t.startswith("@id:")}
        linked = [
            r for r in results
            if any(t.startswith("@scenario:") and t[10:] in ids for t in r.tags)
            or (r.layer == "e2e" and any(t.startswith("@id:") and t[4:] in ids for t in r.tags))
        ]
        links[id(scenario)] = linked
    return links

The rules that follow from that

Where tags are read from

Different frameworks put metadata in different places, so SpecTracer checks all the plausible ones rather than mandating a single convention.

For JUnit, the <property> route is the cleanest — it keeps tags out of your test names. But embedding the tag in the test name works fine and needs no plugin, which is why SpecTracer's own suite does it:

test_render_dashboard_sections_present[@scenario:FC-006]

Layer requirements

A link tells you a test exists. A requirement tells you whether that's enough. Three requirement tags exist, matching the three layers:

• @require-unit — satisfied by a linked result collected under unit
• @require-integration — satisfied by a linked result collected under integration
• @require-e2e — satisfied by a linked result collected under e2e

Each declared requirement that has no linked result is flagged as missing on the scenario row in the report, and drags down both headline numbers. The set of all declared requirements across all scenarios is the denominator of the declared tests matched percentage.

Module scope

On a large codebase "there is a unit test for this" is often too weak. You want "there is a unit test in the billing module for this". All three requirement tags accept an optional :modulename suffix for exactly that.

The module names come from the keys of the layer objects in your config:

{
  "unit": {
    "":        ["./reports/unit.xml"],          // unscoped
    "auth":    ["./reports/auth-unit.xml"],     // module "auth"
    "billing": ["./reports/billing-unit.xml"]
  },
  "e2e": {
    "":         ["./reports/e2e.json"],
    "checkout": ["./reports/checkout-e2e.json"]
  }
}

Every result parsed out of a file is stamped with the module key it was registered under. Then:

Module scope works identically for all three layers, which makes it a good fit for microservice-per-team repos: tag scenarios @require-unit:my-service and only that team's results count.

Defaults & edge cases

Naming conventions that hold up

None of this is enforced by the tool — it's what tends to survive contact with a real team.

• Make ids opaque and stable. FC-42 or a ticket key beats login-happy-path, because a renamed scenario shouldn't break every test that references it.
• Never reuse an id. Collisions link one result to several scenarios and quietly inflate coverage.
• Agree the module vocabulary once. Module keys live in two places — the config and the @require-*: suffixes — and they must match exactly.
• Review tags like code. A missing @scenario: tag looks identical to a missing test in the report, which is the point.