Reports

A run can write its results in several forms. Each one is optional, and none of them changes the console output or the exit code.

Reports for CI

bddkit run --junit reports/junit.xml --cucumber-json reports/cucumber.json

• JUnit XML: one <testsuite> per feature file and one <testcase> per scenario, with each step’s status and timing in <system-out>. Jenkins, GitLab and GitHub test summaries read it.
• Cucumber JSON: the shape that cucumber-html-reporter and Allure accept.

Every report path is created before the config is read. A run that dies on its config therefore leaves an empty file, which a CI parser rejects loudly, rather than yesterday’s green one.

Failure classes

A failed scenario carries a class, so “a test caught a bug” and “staging was down” can be told apart by a CI rule or a report filter:

Class	When
assertion	a check did not hold, including after polling ran out
transport	connection refused, DNS, TLS, an HTTP timeout
db_connection	a database connection was lost mid-run
db_statement	the database refused a statement
input	the scenario itself is wrong
plugin	a plugin answered with a fatal error, or did not answer
reset	a plugin’s per-scenario reset failed
panic	a bug in bddkit
unclassified	a host fault no other class fits

The console summary shows them as well: failed: 5 (4 assertion, 1 transport). The exit code is 1 for any failed scenario, whatever its class.

HTML report

bddkit report run.ndjson -o run.html

Requires a run that wrote its event stream with --events run.ndjson. The result is one self-contained page that opens from disk, with filters for status, text, tag and failure class. Failed scenarios open first. Add --evidence to the run to see each HTTP exchange, SQL statement and screenshot under the step that produced it. Add --embed-artifacts to the report command to carry those files inside the page, so a single file can be mailed.

Markdown report for agents

bddkit report run.ndjson -o report.md

A Markdown file that a coding agent can read with grep, sed and awk without loading all of it. Each part is delimited by marker lines that grep '^<!-- bddkit:' finds, and the index gives each scenario’s line range. By default only failed scenarios are included in full. The format is documented in docs/report-markdown.md in the bddkit repository.

Running reports in CI

The report is most useful after a failure, so it has to run even when run exits 1:

• GitLab: put bddkit report run.ndjson in after_script.
• GitHub Actions: add a step with if: always().
• Shell: bddkit run --events run.ndjson || status=$?; bddkit report run.ndjson; exit ${status:-0}.