The event stream

bddkit run --events <path> writes one JSON object per line while the run is in progress. Use it to follow a run live, to feed a dashboard, or as the input to bddkit report. The console output, the JUnit and Cucumber reports, and the exit code do not change.

The path can be a regular file, a named pipe, or anything else that opens for writing by name. $BDDKIT_EVENTS supplies the path when the flag is absent; the flag wins. Standard output is never a target, because it carries the console.

Shape of the stream

Every line has a type, a seq that counts from 0 and only increases, and t, the milliseconds since the run started. A consumer must ignore a type or a field it does not know, so new fields do not break it.

• The first line is run_started. It records the schema version and the artifacts directory.
• The last line is run_finished. It records the exit code and the totals.
• Between them, each feature file produces file_started, then scenario_started, step_started, step_finished or step_skipped, scenario_finished, and file_finished.

Lines from different files interleave. Lines from one file are always in causal order. A step inside a macro or an included scenario is an event of its own, with parent pointing at the step that called it.

Three states of the file

• Empty: the run was refused and exited 2. The reason is on stderr. Nothing is written until the run has started.
• Terminated: the last line is run_finished. If the run was interrupted, that line carries a signal field (SIGINT, SIGTERM, SIGHUP, CTRL_C or CTRL_BREAK). Scenarios still in flight at that point have no scenario_finished.
• Cut short: lines but no run_finished. The process was killed, or it exited on a second signal.

Nothing is written after run_finished.

Evidence

--evidence adds what the steps did: the variables each step resolved, every HTTP exchange, each SQL statement, and each polling attempt. It is off by default, because it puts request and response bodies on disk. Masking applies to all of it. --evidence=<sources> chooses which steps are recorded: marked (the steps the scenario marked), failures (every step of a failed scenario), or all.

Reading a stream

bddkit run --events run.ndjson
bddkit report run.ndjson -o run.html

bddkit report turns a stream into an HTML page or a Markdown file, and also works on a stream from a run that was cut short. Field-by-field detail is in docs/events-design.md in the bddkit repository.