README

Part of BarnSuite.

Runs the Given/When/Then Scenarios you captured in Barnspec as executable tests. It reads a captured Scenario, converts it into Scenario Runner's execution shape, and runs it against the Port classes Port Generator generated (and you filled in).

It ships as a library plus the scenario-bridge command.

Requirements

PHP 8.5+
rmb32/barnspec, rmb32/scenario-runner, rmb32/port-generator
Captured Scenarios (.barnspec/) and filled-in Port classes from Port Generator

Installation

composer require --dev rmb32/scenario-bridge

Usage

# one Scenario, by slug or id
vendor/bin/scenario-bridge run commerce basket-quantity-updates

# every Scenario in an area, narrowed and exported
vendor/bin/scenario-bridge run-all commerce --role=customer --only-failures --xml-report=build/report.xml
vendor/bin/scenario-bridge run-all commerce --summary --ndjson-report=build/failures.ndjson

# just one Phase
vendor/bin/scenario-bridge run-all commerce --phase="launch"

# every released Phase — what CI keeps proving while the next is built
vendor/bin/scenario-bridge run-all commerce --released

Exit code is non-zero if anything failed.
Every Scenario starts from nothing: its own storage, its role authenticated first. A Port that throws, or one not generated yet, fails only the Scenarios that need it; the rest still run and are recorded.
--phase= runs and records only that Phase's Scenarios (by slug or title); --released runs and records every released Phase's. An area with nothing released yet runs nothing and exits successfully.
A released Story changed through an elaboration (see Barnspec) is run by standing: --released skips a Scenario still being amended or retired in the active Phase and prints why, --phase=<active> runs the elaboration's new and amended Scenarios, and with neither flag a run proves what will hold once the active Phase is released. A Scenario an elaboration has replaced never runs.
Ports come from barnspec.json's portStubs.factory when it names one (see Port Generator); otherwise they are built with new. A factory usually boots your test environment, so it also inherits whatever that environment stands in for (a permission check that lets everything through, say). Scenarios then prove nothing about it: undo the stand-in in the container the factory builds.
--role=, --story=, --scenario= narrow what is shown and exported; --only-failures and --summary change the console view only.
--xml-report=path writes a JUnit-style XML report most CI systems can display; --ndjson-report=path writes one JSON object per failing action/assertion.
In a real terminal with no export flags, you're offered an interactive export wizard (all / fails / passes × format × destination).
Every run is recorded against Barnspec's Work context, pass or fail, so a Scenario's fulfilment colour is derived from what actually ran rather than vouched for by a person. A Scenario whose tickets are all done goes green when a run passes and back to red when one fails; nothing else can make it green. Pass --no-record to run without writing that result — useful for trying something out without moving a colour on the story map.
--ndjson-report is an export format for people and CI, not the recording mechanism: it emits one line per failing action/assertion, keyed by name, so a passing Scenario produces no lines at all and nothing in it identifies a Scenario by id. The recording happens here in the CLI instead, where both the real id and the result are already in hand.

A Scenario only genuinely passes once the generated Port stubs (which throw a TODO until filled in) contain real logic — so a Scenario with no Ports written for it can never be green, however finished the work behind it feels.

Related packages

Scenario Runner CLI — unit-test scaffolding.
Barnspec CLI — capture the Scenarios.
Port Generator — creates the Port stubs.
Scenario Runner — the execution engine and result reporting.
Barnspec — where Scenarios are captured.

More docs

Internals · History · Known issues

rmb32 / scenario-bridge

Package info

Security

Statistics