Runner

Run scenarios through a device pool and write the run's report artifacts.

bajutsu.runner.pipeline

Run every scenario through a device pool and write the run's report artifacts.

run_all(eff, scenarios, lease, clock=None, on_blocked=None, on_blocked_for=None, run_dir=None, workers=1, bindings=None, secret_values=None, progress=None, baselines_dir=None, schemas_dir=None, actuator=None, resolve_actuator=None, golden_context=None, lease_udid_spec='booted')

Run every scenario, each on a freshly leased device, and return one result per scenario.

lease(eff, scenario) blocks until a device is free, launches the app, and returns a Lease bundling the live driver with that device's evidence sink / relaunch / control / network collector; lease.release() afterwards terminates the app and returns the device to the pool. A lease's collector, when present, has its exchanges cleared per scenario, exposed to request assertions, and written to <sid>/network.json (redacted with secret_values).

Parameters:

Name	Type	Description	Default
eff	Effective	The resolved target config (drives redaction, backend, launch).	required
scenarios	list[Scenario]	The scenarios to run; results come back in this declaration order.	required
lease	LeaseFn	Leases a device and launches the app for one scenario (a single-device run is a pool of one).	required
clock	Clock | None	Injectable time source for condition waits, so tests need no real sleeps. None uses the real clock.	None
on_blocked	BlockedHandler | None	A single alert-guard handler, used by tests.	None
on_blocked_for	OnBlockedFor | None	Picks each scenario's alert-guard handler (honoring its dismissAlerts); takes precedence over on_blocked.	None
run_dir	Path | None	Where per-scenario artifacts (network.json, visual diffs) are written. None skips writing them.	None
workers	int	Concurrent scenarios; >1 hands each worker its own device + per-device resources, so the loop keeps no shared mutable state.	1
bindings	Mapping[str, str] | None	secrets.<name> → value substitutions applied to step inputs.	None
secret_values	list[str] | None	The raw secret values to redact from evidence.	None
progress	ProgressFn | None	Receives one-line progress messages (the web UI streams these). None is silent.	None
baselines_dir	Path | None	Baseline images for visual assertions. None disables visual comparison.	None
schemas_dir	Path | None	Directory the responseSchema assertions' schema files resolve against. None disables them.	None
actuator	str | None	The single selected actuator (e.g. idb / playwright); when given, each scenario is preflighted against its static capability set and failed up front if it needs a capability the actuator lacks (BE-0082). None skips the fixed preflight (a lease driven directly in tests, or when resolve_actuator chooses per scenario instead).	None
resolve_actuator	Callable[[Scenario], str] | None	Per-scenario actuator resolver (BE-0240); when given, each scenario's actuator — and thus the capability set it is preflighted against — is resolved from the scenario's own steps (cheapest sufficient), instead of the one fixed actuator. Mutually exclusive with actuator (passing both raises): the CLI's single-engine path and audit pass this, the cross-browser matrix passes actuator.	None
golden_context	GoldenContext | None	Goldens directory for golden assertions (BE-0006). None disables them.	None
lease_udid_spec	str	The run's resolved udid spec (the provider's udid_spec). A WebDriver URL routes the run to the live XCUITest environment, so the preflight narrows to that transport's set (BE-0238) — the same is_webdriver_endpoint signal environment_for routes on. "booted" (the default) is never a URL, so the local path is unchanged.	'booted'

Returns:

Type	Description
list[RunResult]	One result per scenario, in the same order as scenarios.

run_and_report(eff, scenarios, lease, runs_dir, run_id, clock=None, on_blocked=None, on_blocked_for=None, workers=1, bindings=None, secret_values=None, source_name=None, description=None, progress=None, baselines_dir=None, schemas_dir=None, actuator=None, resolve_actuator=None, config_source=None, exec_provenance=None, golden_context=None, lease_udid_spec='booted')

Run the scenarios, then write the run's artifacts under runs_dir/run_id.

Wraps run_all and persists the report: manifest.json, JUnit XML, and the executed scenario.yaml (so a run is re-runnable / reviewable). idb toolchain versions are recorded as provenance only when idb actually drove the run — never a pass/fail input (BE-0005).

Beyond run_all's arguments, runs_dir + run_id locate this run's artifact directory (runs_dir/run_id), source_name / description are recorded in the report, and config_source — the Git source the config came from (BE-0063), or None for a local config — is stamped into the manifest's provenance so a branch-based run states the exact commit it executed.

Returns:

Type	Description
tuple[list[RunResult], Path]	The per-scenario results and the path to the written manifest.json.

run_matrix_and_report(eff, scenarios, engines, run_pass, runs_dir, run_id, *, source_name=None, description=None, secret_values=None, config_source=None, exec_provenance=None)

Run the scenarios once per engine, then assemble ONE report at runs_dir/run_id (BE-0076).

The cross-browser fan-out: a loop over engines, each a full pass. run_pass(engine, run_dir) runs the selected scenarios for one engine against its own pool, writing that engine's evidence under run_dir (the caller hands it runs_dir/run_id/<engine>, prefixing the existing NN-slug layout so two engines never collide); its results are tagged with engine here. The passes' tagged results are concatenated into one flat list and written as a single manifest / JUnit / report — the manifest's matrix block aggregates the per-engine verdicts, and ok is all-must-pass across every engine x scenario (pure aggregation, no LLM).

Returns:

Type	Description
tuple[list[RunResult], Path]	The concatenated per-engine results and the path to the written manifest.json.