Webtrax docs

Reports

What webtrax check writes, how findings are grouped and identified, and the NDJSON record format for scripts.

Findings and ids

A finding is one problem: one rule on one URL (for example, a broken link to /old-pricing). If ten pages link to that broken URL, it is one finding seen on ten pages. Each finding has a fingerprint, a SHA-256 of the rule id, the normalised URL and a rule-specific key, so the same problem has the same id on every run and every machine. Reports show the first ten characters as the finding id.

Formats

Format Where For
Console summary stdout (default) People at a terminal. Colour only on a TTY; NO_COLOR turns it off.
HTML report.html The full report, single file, works offline.
Markdown report.md, or --stdout md Pull request comments and pasting into an AI chat: stable headings, finding ids, fixes.
JSON report.json, or --stdout json Scripts and dashboards: summary, findings with their fixes, pages.
SARIF 2.1.0 report.sarif (--reports sarif) GitHub code scanning and other security tools: one result per finding, levels by severity, the fingerprint as a partial fingerprint, rule help linking to these docs.
JUnit XML report.junit.xml (--reports junit) CI dashboards: a test suite per check suite, a failing test case per finding.
NDJSON run.ndjson Every record of the run, one per line.

NDJSON records

run.ndjson starts with a run record and ends with a summary; in between are page, finding, metric, snapshot and artifact records. The format is versioned (protocol_version: 1), and JSON Schemas for it (job spec, run line, rule) ship with the @webtrax/protocol package.

Record Main fields
run job_id, started_at, runner, user_agent, spec (the full job spec)
page url, final_url, status or error, redirect_chain, depth, title
finding fingerprint, rule_id, rule_version, severity, url, source_url, title, evidence (at most 2 KB)
summary status (completed, partial, failed), stop_reason, pages, links, findings by severity, suites