cerebro library

cerebro: headless screenshot capture and navigation map for Flutter apps.

Classes

CaptureDiff
Compares two map.json files (or a baseline directory and the current capture) and reports added, removed and changed screens.
Cerebro
Entry point called by the generated test/cerebro/cerebro_capture_test.dart.
CerebroConfig
ContrastReport
ContrastSample
DeviceSpec
A logical screen size the app is rendered at.
FontLoadReport
Result of loadRealFonts, recorded in map.json so the agent knows whether glyphs in the screenshots are real or the FlutterTest block font.
GoRouterDriver
LintFinding
A deterministic, regex-based scan of Dart UI code for the defects the audit most often finds. Not a replacement for the analyzer: it targets design rules the analyzer does not know about.
LintOptions
LintRule
LowContrast
MapWriter
Merges routes.json, fonts.json and results/*.json into map.json and renders MAP.md (Mermaid route tree + thumbnail table).
Classification of what a tap did, derived from the router state before and after the tap plus any overlay that appeared.
Renders the explored navigation graph as a picture: one node per route (its light, 1.0× screenshot as the thumbnail), one arrow per distinct tap result between two routes. Always writes map.dot; when Graphviz (dot) is on the PATH also writes map.png and map.svg with a transparent background, so the picture sits on light and dark pages.
RouteNode
One route in the app's route tree, with its full path.
RouteOptions
Per-route options from cerebro.yaml.
ScreenChange
ScreenDriver
How the harness opens a screen and reads the navigation state. Two implementations: go_router (declarative, location = URI) and Navigator 1.0 (MaterialApp.routes, location = route name).
ScreenTarget
A concrete location to render.
Tappable
A tappable semantics node with its rect in logical pixels.

Constants

lintRules → const Map<String, LintRule>

Functions

classifyEdge({required String from, required String to, required int depthBefore, required int depthAfter, String? overlay, String? error, bool contentChanged = false}) → String
Pure classification so it can be unit-tested without a router.
collectTappables(SemanticsNode root, {required double dpr, double minTapSize = 48, Rect? visible}) → List<Tappable>
Walks the semantics tree accumulating transforms; rects come out in physical pixels (the root is the RenderView), so divide by dpr.
compositeOver(int argb, int background) → int
Composites an ARGB colour with alpha over an opaque 0xRRGGBB background.
contrastRatio(int a, int b) → double
WCAG contrast ratio between two 0xRRGGBB colours (1..21).
enumerateRoutes(GoRouter router) → List<RouteNode>
Walks router.configuration.routes. For StatefulShellRoute only branches[].routes is visited: its routes getter is already the flattened union of all branches.
estimateContrast(Uint8List rgba, int imageWidth, int imageHeight, {required int left, required int top, required int width, required int height, double minDistance = 60}) → ContrastSample?
Estimates text/background contrast inside a rectangle of an RGBA image.
expandTargets(List<RouteNode> tree, CerebroConfig config) → List<ScreenTarget>
Expands routes into locations using config params / variants / exclusions.
findFlutterRoot() → String?
Locates the Flutter SDK root. flutter test exports FLUTTER_ROOT; as a fallback walk up from the flutter_tester binary (<root>/bin/cache/artifacts/engine/<platform>/flutter_tester).
findingIds(Map<String, Object?> screen) → Map<String, String>
Stable identities of a screen's deterministic findings, mapped to a short human label. Positions are left out so a layout shift does not fake a new finding; sizes, colours and ratios are in, so a worse contrast on the same text is a new finding.
flattenRoutes(List<RouteNode> tree) → List<RouteNode>
Flat list of route nodes in tree order.
lintFile(String relPath, String source, {LintOptions options = const LintOptions(), bool? projectHasPageTransitionsTheme}) → List<LintFinding>
lintProject(String root, {LintOptions options = const LintOptions()}) → List<LintFinding>
Scans lib/ (and test/ for test-only rules) under root.
loadRealFonts({Map<String, List<String>> extraFonts = const {}}) → Future<FontLoadReport>
Loads Roboto and MaterialIcons from the SDK cache, plus any extra font files declared by the caller (family -> asset or file paths), so that screenshots taken under flutter test show real glyphs instead of the FlutterTest block font.
measureTextContrast(WidgetTester tester, Uint8List rgba, int imageW, int imageH, {required double scale}) → ContrastReport
Measures WCAG contrast for every rendered paragraph: the text colour is known from the RenderParagraph, the background is sampled from the screenshot pixels under it. Text with an alpha colour is composited.
paintedFraction(Uint8List rgba, int imageWidth, int imageHeight, {required int left, required int top, required int width, required int height, required int foreground, required int background}) → double
Fraction of the rect's pixels that carry paint other than background: pixels nearer to foreground than to the background, or moved at least 30% of the way from the background towards anything else (faded text under an Opacity still counts). A text whose rect is painted in one flat colour (fraction ~0) is not visible in the screenshot: an opaque surface covers it, or it is clipped away.
readMap(String pathOrDir) → Map<String, Object?>
Reads a map.json from a file path or from a directory containing one.
relativeLuminance(int rgb) → double
Relative luminance of an 0xRRGGBB colour.
renderEdgesMermaid(List<Map<String, Object?>> edges) → String
Mermaid graph of explored edges: nodes are locations, overlays hang off their screen as dashed edges, dead taps are listed separately.
renderLintMarkdown(List<LintFinding> findings) → String
requiredContrast({required double fontSize, required bool bold}) → double
WCAG AA minimum: 3.0 for large text (>= 18 pt, or >= 14 pt bold), 4.5 otherwise.
resolveFontPath(String path, String root, {Map<String, Object?>? packageConfig}) → String
Resolves a font path from cerebro.yaml to a file path. Relative paths are joined to root; a package asset key (packages/<pkg>/fonts/x.ttf, the form TextStyle(package:) and pubspec.yaml fonts use) is mapped to <pkg root>/lib/fonts/x.ttf through .dart_tool/package_config.json (packageConfig overrides the file, for tests). Unknown packages fall back to the literal path so the caller reports it as missing.
sampleBackground(Uint8List rgba, int imageWidth, int imageHeight, {required int left, required int top, required int width, required int height, required int foreground, double textTolerance = 12}) → int?
Most frequent colour inside the rect once the text's own pixels are removed: pixels within textTolerance of foreground (the known text colour). Anti-aliased blends stay in, but they are always a minority next to the background, so the mode is the background even when text and background are close (e.g. #F0F0F0 on white). Returns null only when nothing but text pixels is left.
slugForLocation(String location) → String
File-system safe id for a location: /notes?state=empty -> notes__state-empty, / -> root, /notes/1 -> notes_1.
slugForScenario(String name) → String
Id-safe form of a scenario name.
splitOccluded(List<LowContrast> low, List<Tappable> tappables, {required double screenArea}) → (List<LowContrast>, List<Map<String, Object?>>)
Splits low-contrast findings into real ones and texts whose sampled background was another surface painted over them (a FAB or a sticky button crossing the text rect, or a ratio no designer would ship). Returns the kept findings and the not-measurable entries.
treeFromPaths(Iterable<String> paths) → List<RouteNode>
Builds a tree from flat route names by path prefix: /account/payments becomes a child of /account when that exists, else of the root. Used for Navigator 1.0 apps, whose routes map is flat.

Typedefs

AppBuilder = Widget Function(GoRouter router, {required ThemeMode themeMode})
AppWrap = Widget Function(Widget app)
ArgumentsFor = Object? Function(String location)
Navigator 1.0 apps: arguments to pass when opening location (Navigator.pushNamed(..., arguments:)). Return null for none.
RootBuilder = Widget Function({required ThemeMode themeMode})
Navigator 1.0 apps: build the root widget (which contains the MaterialApp) for a theme mode.
RouterBuilder = GoRouter Function({required String initialLocation})
ScenarioReset = Future<void> Function()
ScenarioSetup = Future<void> Function()
A named test fixture: seeds fakes, overrides dependencies, logs a user in, puts a repository in its error state. Runs (with real async allowed) right before the screen is built. Pair it with ScenarioReset so scenarios do not leak into the next screen.