scenarios_report library

What a scenario run wrote to disk, typed — the reader for run.json.

Every fw run scenarios run writes its whole report beside its artifacts: every step of every scenario, each with its screenshot, widget tree, visible texts, semantics and events as paths. This library reads that back so a project's tool/ script — a CI gate, a screenshot uploader, a custom report — is a few lines over typed classes rather than a map walk written once per project:

  • ScenarioRunReport.read takes a run's output directory and hands back the ScenarioRunResult with a way to open what its steps name.
  • compareScenarioRuns takes two of those and says which steps moved — the check that a green suite is also a deterministic one. It compares more than the pictures: the facets a capture cannot show are in ScenarioDriftFacet.
  • readScenarioRunDrift reads the drift.json a run leaves beside its report — the same comparison against whatever ran before it, with every moved step named.
  • readScenarioRunIndex reads the index.json a matrix run leaves at the root of its output tree — the entry point a CI job walks.
  • AppEvent.fromJson (from package:flutterware/app_events.dart) types the .events.json a step points at; ScenarioRunReport.events does the read.

This is published API. A field renamed here breaks somebody's script, which is why scenarioRunReportVersion exists and why the readers refuse a major they do not know rather than handing back a half-decoded object.

Plain Dart on purpose — nothing here may import package:flutter. The script that consumes a run executes under a bare dart run, exactly like tool/flutterware.dart does.

Classes

AppChannel
The channel an event travelled on — what the panel filters and groups by.
AppEvent
One thing that happened on the way from one step to the next.
ScenarioAim
Where a verb's finger went.
ScenarioDriftFacet
The facets two runs compare a step on — what ScenarioStepDrift.what names when one of them moved.
ScenarioRunDrift
What changed between two runs of one suite — nothing, if the suite is deterministic.
ScenarioRunError
ScenarioRunIndex
A matrix run's index.json: one entry per point, each naming the directory whose own run.json holds the rest.
ScenarioRunIndexEntry
One point of the matrix, as the index lists it.
ScenarioRunOutcome
One scenario's verdict, and the steps it captured on the way to it.
ScenarioRunPackage
One package's run: where its artifacts went, and how each scenario fared.
ScenarioRunReport
A written run, read back.
ScenarioRunResult
A whole run — scenarios executed in the runner's flutter_tester, with one artifact triple (PNG, widget tree, texts) per captured step.
ScenarioRunStep
One captured step: what it is a picture of, its sibling legs on disk, and what the app did on the way to it.
ScenarioStepDrift
One step that moved between two runs of the same suite.

Enums

ScenarioStepKind
What a step is a picture of.

Constants

scenarioRunDriftFile → const String
What a run writes beside scenarioRunReportFile when it had a run before it to compare against: ScenarioRunDrift, whole.
scenarioRunIndexFile → const String
What a matrix run writes at the root of its output tree: one line per point, each naming the directory whose run.json holds the rest.
scenarioRunReportFile → const String
What a run writes beside its artifacts: itself, whole, in this shape.
scenarioRunReportVersion → const int
The format run.json (and the matrix's index.json) is written in.

Functions

compareScenarioRuns(ScenarioRunResult before, ScenarioRunResult after, {String? baseline}) → ScenarioRunDrift
Two runs of the same suite, compared by what their steps recorded.
readScenarioRunDrift(String directory) → Future<ScenarioRunDrift?>
Reads the drift.json a run wrote beside its report — what moved between it and the run before it, with every step named rather than the first twenty a call hands back.
readScenarioRunIndex(String directory) → Future<ScenarioRunIndex>
Reads the index.json a matrix run wrote at the root of its output tree.
stillTickingOf(Iterable<ScenarioRunStep> steps) → List<String>
Every step's ScenarioRunStep.stillTicking, once each, in step order — what ScenarioRunOutcome.stillTicking says of a scenario.