widget-golden-and-a11y-testing

Widget, golden and accessibility testing

One harness pins the surface; layout and accessibility are asserted by computed geometry on the real widget tree, not by blessed pixels. Goldens are a narrow, honest safety net for glyph shaping and mirroring — never the layout gate. This skill covers the widget tier; for the pure-core / Drift / Notifier tiers see testing-strategy.

Read the reference for the task at hand:

• references/harness-and-mediaquery.md — pumpApp, Device presets, the four load-bearing lines, driving MediaQuery flags, finder policy.
• references/overflow-and-textscale.md — the two overflow classes, the three traps, the matrix, the fit assertion, and the four wrong fixes.
• references/a11y-guidelines-and-limits.md — the four built-in guidelines and their defects, the semantics/traversal gate, pure-Dart contrast, and what automation genuinely cannot cover.
• references/golden-two-lanes.md — the golden-refusal argument, the Ahem-vs-real-font lanes, RTL goldens, and blocking accidental blessing.

Run scripts/check-test-hygiene.sh before a PR.

Non-negotiable rules

1. Pin the device on every layout/geometry test. The default widget surface is 800x600 logical — wider than any phone. Unpinned, content is ~2x too wide, everything fits, the suite is green, and the shipped phone is broken. useDevice(...) first, pumpApp(...) second.
2. physicalSize is in PHYSICAL pixels — always multiply by DPR. view.physicalSize = Size(320, 640) at the default DPR 3.0 is a 107x213 logical surface, not a phone. Set devicePixelRatio and physicalSize = logical * dpr, then addTearDown(view.reset) — a leaked size poisons every later test in the file.
3. Layer MediaQuery ABOVE MaterialApp, built from .copyWith. MaterialApp inserts no MediaQuery of its own; the one from pumpWidget's View is nearest. A bare MediaQueryData() zeroes the view-derived size the device just pinned — the test then measures a 0x0 screen and passes.
4. pump(), never pumpAndSettle() as an animation wait. pumpAndSettle carries a 10-minute timeout and truncates its stack trace, and hangs forever on an infinite splash/shimmer/spinner. Use pump() for state changes and pump(duration) / fakeAsync for timer-driven async — pump() does not advance the fake clock.
5. Never suppress overflow. A RenderFlex overflow already fails a widget test (it routes through FlutterError.reportError and the binding rethrows at test end). Never call takeException() to swallow it, never assign FlutterError.onError, never copy ignoreOverflowErrors, and never takeException() in a global tearDown — each disarms the whole net.
6. One testWidgets per (device, scale, bold) tuple — never a loop inside a test. Overflow is reported once per RenderObject (the flag resets only on reassemble()), so looping scales inside one test silently under-reports every scale after the first. Loop around the testWidgets call.
7. Assert the fit, not just absence of overflow. A clipped Text reports nothing — RenderParagraph has no overflow indicator. takeException(), isNull is necessary but not sufficient; add a getSize/getRect assertion that the label fits inside its computed cell.
8. Prefer computed geometry over goldens for layout. Assert cells in a row share a top and cells in a column share a left (moreOrLessEquals, epsilon: 0.5); assert tap targets with a getSize loop. These fail with a sentence a human can act on. Goldens cannot assert anything — a blessed screen of clipped, unreadable text passes forever.
9. Assert contrast on colour VALUES in pure Dart, never on pixels. meetsGuideline(textContrastGuideline) screenshots and histograms the layer — white text on #FAFAFA passes (an open Flutter defect). A pure-Dart WCAG + APCA test on the theme's colours cannot false-pass. For a state pair distinguished only by chroma (selected vs surface at equal luminance), assert wcag(theme.selected, theme.surface) directly — a grayscale-mode user perceives exactly that luminance gap, so no separate grayscale channel is needed.
10. await expectLater(...) for meetsGuideline — it returns an AsyncMatcher. A plain expect() looks right and asserts nothing. Keep the four built-in guidelines only as advisory tripwires; the geometry and pure-Dart contrast tests are the gate.
11. Two golden lanes, both loadAppFonts(); block accidental --update-goldens. Ahem squares are byte-stable cross-OS and prove geometry/mirroring but not glyph shaping; one narrow real-font lane on a pinned OS proves script joining and numeral glyphs. Tag every golden @Tags(['golden']) and generate blessed files in one pinned environment only.
12. Never clamp TextScaler. withClampedTextScaling, textScaleFactor, and FittedBox defeat the matrix while contrast and tap-target stay green, and override the user's own OS setting. Fix the layout, not the text.