sdods report, show-report, heal, insights
Open reports, ingest results, export requirement traceability and inspect self-healing events.
report
sdods report [--last | --run <id>] [--open] [--html] [--dashboard]
sdods report ingest [files...] --run-id <id> [-p <slug>] [-e <env>] [--manifest <file>] [--format auto|cucumber|runner-json] [--artifacts-dir <dir>] [--replace]
sdods report merge <dirs...> [--run <id>] [--reporter <list>] [--process <name>] [-p <slug>]
sdods report traceability -p <slug> [-e <env>] [--run <id> | --last] [--format json|csv|md|html] [-o <file>]
sdods show-report [--run <id>]report prints the summary of a run (totals, failed and flaky scenarios, report paths); --open opens the HTML report and the SDODS dashboard, --html / --dashboard open one of them. report ingest loads cucumber messages NDJSON and runner JSON results into the database (sdods run does this automatically when a database is configured); --replace deletes previously ingested rows of the run first. When the run directory holds a process gate verdict (gates.json), ingest records it on the run under totals_json.gates and marks a run that did not meet its gates failed, as the server does for the runs it starts. A run whose run.json names a process with gates but that has no gates.json (and is not one shard of several) is judged during ingest. show-report opens the HTML report of the latest or a given run.
report merge
sdods report merge <dirs...> [--run <id>] [--reporter <list>] [--process <name>] [-p <slug>]Merges the blob reports that sdods run --reporter blob --shard i/n wrote (each <run>/shard-reports directory) into one HTML report, plus the other --reporter outputs, under the run given by --run.
With --process <name>, it also judges that process's gates on the whole run. The pass rate and flaky count come from the merged results. The @a11y and @perf evidence comes from the shards' run directories and from the reports attached in the blobs. It prints the same gate table as sdods run --process, writes gates.json into the --run directory (and adds the verdict to its run.json and summary.json when they exist), and exits 1 with GATE_FAILED when a gate is not met. Without --process, it judges the process a shard's run.json names, when that process declares gates.
| Flag | Default | Meaning |
|---|---|---|
--run <id> | latest run | run directory the merged report and the verdict are written to |
--reporter <list> | html,junit | reporters for the merged output |
--process <name> | the gated process in run.json | process whose gates are judged over the merged shards |
-p, --project <slug> | the project in run.json | project that defines --process |
sdods report merge --run gh-123 --process release-gate .sdods/runs/gh-123/shard-reportsOne invocation judges one project's process. Merge each project's shards separately when a matrix runs several projects.
report traceability
sdods report traceability -p <slug> [-e <env>] [--run <id> | --last] [--format json|csv|md|html] [-o <file>]Exports, for one run, every requirement named by an @req:<id> tag (or listed in traceability.requirements), the scenarios that cover it (feature file, line, name, effective tags) and each scenario's final attempt in every runner project it ran in (status, browser, attempts, flaky, duration, timestamps). The header carries the run id, environment, commit and branch, SDODS version and CI link from run.json. It reads the run directory only; no database or server is needed.
| Flag | Default | Meaning |
|---|---|---|
-p, --project <slug> | required | project whose features and runs are read |
-e, --env <name> | only runs against this environment | |
--run <id> | latest run of the project | run directory under .sdods/runs (exit 2 if it belongs to another project or environment) |
--last | the latest run, and exit 2 when there is none | |
--format <fmt> | from the -o extension, else json with --json, else md | json, csv (one row per requirement × scenario × result), md, html |
-o, --output <file> | stdout | write the export to a file |
With no run at all the export is still written, as a static requirement → scenario matrix with every scenario not-run.
| Requirement status | Meaning |
|---|---|
passed | every scenario that covers it passed in the run (a pass on retry counts, and is marked flaky) |
failed | at least one covering scenario failed |
not-run | covered, but at least one covering scenario has no result or was only skipped |
not-covered | listed in the requirements file, and no scenario carries its tag |
Ids tagged on scenarios but missing from the requirements file are kept, with declared: false. Without a requirements file notCovered is null: requirements nobody tagged cannot be known.
Results come from the run's cucumber messages (messages.ndjson and its shard files), which record every attempt in every browser. Runs without them fall back to the per-scenario meta.json files, which keep one browser per scenario; the export says which source it used.
Sign-off
Every export ends with a sign-off block (signed by, role, date, decision, notes) that is always empty. SDODS never fills it in: sign-off authority is human and not delegable. In JSON the fields are null; a person completes the Markdown, HTML or CSV copy they sign.
bun run sdods report traceability -p demo-shop -e staging -o traceability.html
bun run sdods report traceability -p demo-shop --run <run-id> --format csv -o release-1.4.csv
bun run sdods --json report traceability -p demo-shop --lastheal report
sdods heal report [--last | --run <id> | --all] [--write-history]Summarises heal events (original selector, chosen strategy, score, suggested locator) for one run or every run under the artifacts directory. --write-history persists heal-history.json, which biases future heals towards strategies that worked.
insights
sdods insights compute -p <slug> [--window <n>] [--flaky-threshold <r>] [--fragility-threshold <r>] [--min-runs <n>]
sdods insights show -p <slug> [--top <n>]Computes the improvement-loop metrics over the last --window ingested runs of a project (default 30) and stores the result under .sdods/insights/<slug>.json; show prints the last result. Needs a database with ingested runs (sdods run --ingest, or sdods report ingest).
| Flag | Default | Meaning |
|---|---|---|
--window <n> | 30 | most recent runs to consider |
--flaky-threshold <r> | 0.2 | scenarios at or above this flakiness become quarantine candidates |
--fragility-threshold <r> | 0.1 | locators at or above this fragility are marked hot |
--min-runs <n> | 10 | minimum runs before a scenario can be flagged |
--top <n> (show) | 10 | rows per table |
Output: suite health and its trend, scenarios ranked by flakiness (with p95 duration and quarantine candidates), locators ranked by fragility (with the suggested selector from heal history) and environment stability. The same numbers power the web dashboard and GET /api/stats/insights.
sdods insights compute -p demo-shop --window 20
sdods insights show -p demo-shop --top 5 --json