cerebro library
cerebro: headless screenshot capture and navigation map for Flutter apps.
Classes
- CaptureDiff
-
Compares two
map.jsonfiles (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.jsonandresults/*.jsonintomap.jsonand rendersMAP.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 writesmap.pngandmap.svgwith 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.
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. ForStatefulShellRouteonlybranches[].routesis visited: itsroutesgetter 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 testexports 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
routenodes 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/(andtest/for test-only rules) underroot. -
loadRealFonts(
{Map< String, List< extraFonts = const {}}) → Future<String> >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 testshow 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 toforegroundthan 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.jsonfrom a file path or from a directory containing one. -
relativeLuminance(
int rgb) → double - Relative luminance of an 0xRRGGBB colour.
-
renderEdgesMermaid(
List< Map< edges) → StringString, Object?> > - 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.yamlto a file path. Relative paths are joined toroot; a package asset key (packages/<pkg>/fonts/x.ttf, the formTextStyle(package:)andpubspec.yamlfonts use) is mapped to<pkg root>/lib/fonts/x.ttfthrough.dart_tool/package_config.json(packageConfigoverrides 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
textToleranceofforeground(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/paymentsbecomes a child of/accountwhen that exists, else of the root. Used for Navigator 1.0 apps, whoseroutesmap 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.