What is the widget golden and a11y testing skill?
The widget golden and a11y testing skill is a SKILL.md in zakariaf/Flutter-Skills. It makes an AI coding agent pin the device in Flutter widget tests, assert layout and accessibility by computed geometry, check contrast on color values in pure Dart, and use goldens only for glyph shaping and mirroring.
The widget golden and a11y testing skill is a SKILL.md in zakariaf/Flutter-Skills. It has an AI coding agent assert layout and accessibility in Flutter widget tests by computed geometry, with goldens as a narrow safety net for glyph shaping and mirroring.
One pumpApp harness pins the device size and layers MediaQuery above MaterialApp, so each test runs at a chosen phone size with a chosen text scale, bold text and accessible navigation setting.
The overflow and fit matrix
The matrix runs one testWidgets per device, text scale and bold tuple, because overflow is reported once per RenderObject. Scales are 1.0, 1.3, 1.5, 2.0 and 3.0, and a getSize or getRect assertion checks that each label fits inside its computed cell.
Accessibility and goldens
Contrast is asserted in pure Dart on color values with WCAG and APCA, and tap targets are measured with an explicit getSize loop. The skill states that Flutter ships four machine checkable guidelines and that Switch Access cannot be tested automatically.
Goldens run in two lanes, an Ahem lane for geometry and mirroring and one pinned OS real font lane for glyph shaping, and both call loadAppFonts. RTL goldens pump under Directionality, and CI blocks --update-goldens.
Who the widget golden and a11y testing skill is for
Best for
- Writing test/support/harness.dart and a pumpApp helper for Flutter widget tests.
- Chasing an overflowed by N pixels failure across device sizes and text scales.
- Writing a11y_test.dart with isSemantics, simulatedAccessibilityTraversal or meetsGuideline.
Not for
- It asserts layout by computed geometry in widget tests rather than writing layout code, so for building Flutter layouts that adapt to window size the flutter-build-responsive-layout skill fits.
- Its answer to an overflow is a test net that never suppresses and a rule to fix the layout, so for mapping Flutter layout errors such as overflow and unbounded constraints to their fixes the flutter-fix-layout-issues skill fits.
- It asserts on the Flutter widget tree inside widget tests, so for scanning a live URL with axe-core, pa11y and Lighthouse the a11y-ally skill fits.
- SKILL.md says Flutter's four built-in guidelines cover a small minority of real accessibility, so for a WCAG 2.2 quick reference with POUR checks and a screen reader checklist the accessibility-testing skill fits.
How to install Widget Golden and A11y Testing Skill for Flutter
npx skills add zakariaf/Flutter-Skills/plugin marketplace add zakariaf/Flutter-Skills and then /plugin install flutter@flutter-skills.Browse first
Run
npx skills add zakariaf/Flutter-Skills --listto see the available skills before installing.Run the install command
Run the command above. It installs all the skills in the repository, and the open skills CLI places them where your agent expects them.
Open a Flutter project
Work in the Flutter project whose tests you want to harden. The skill loads when a task matches its description.
Run the hygiene script
Before a PR, run
scripts/check-test-hygiene.sh, which the skill asks for.
Check that it loaded
Ask your agent to write a pumpApp harness and an overflow matrix for a screen. It should pin the device with physicalSize times devicePixelRatio and create one testWidgets per device, scale and bold tuple.
Key features
- Device pinning
useDevicesetsdevicePixelRatioand setsphysicalSizeto the logical size times the DPR, then registersaddTearDown(view.reset). - pumpApp harnessOne harness layers MediaQuery with
textScaler,boldTextandaccessibleNavigationabove MaterialApp, built fromcopyWith. - Overflow matrixOne
testWidgetsper device, scale and bold tuple, with no suppression of overflow errors anywhere intest/. - Fit assertionA
getSizeorgetRectcheck confirms a label fits its computed cell, since a clippedTextreports no overflow. - Computed geometryCells in a row share a
topand cells in a column share aleft, checked withmoreOrLessEqualsandepsilon: 0.5. - Semantics gate
isSemanticsasserts a node's label and role, such as a button with an enabled state and a tap action. - Pure Dart contrastWCAG and APCA contrast is asserted on theme color values, so a pixel histogram cannot false pass.
- Two golden lanesAn Ahem lane proves geometry and mirroring, and one pinned OS real font lane proves script joining and numeral glyphs.
- RTL goldensGoldens pump under
DirectionalitywithTextDirection.rtlto check that a card mirrors correctly. - Hygiene scriptRun
scripts/check-test-hygiene.shbefore a PR.
Frequently asked questions
What is the widget golden and a11y testing skill?
It is a SKILL.md in the zakariaf/Flutter-Skills repository for the widget tier of Flutter testing. It has your AI coding agent pin the device, assert layout and accessibility by computed geometry, test contrast in pure Dart, and use goldens only as a narrow safety net.
How do I install the widget golden and a11y testing skill?
Run npx skills add zakariaf/Flutter-Skills, which installs all the skills in the repository through the open skills CLI. Add --list to browse first, or add --skill with a skill name to pick one. Claude Code users can instead run /plugin marketplace add zakariaf/Flutter-Skills and then /plugin install flutter@flutter-skills.
Why prefer computed geometry over goldens for layout?
Computed assertions fail with a sentence a human can act on, such as cells in a row sharing a top. Goldens cannot assert anything, so a blessed screen of clipped, unreadable text passes forever. The skill keeps goldens for glyph shaping and mirroring that geometry cannot see.
Why one testWidgets per device, scale and bold tuple?
Overflow is reported once per RenderObject, and the flag resets only on reassemble. Looping scales inside one test therefore under reports every scale after the first. The skill loops around the testWidgets call instead, so each tuple gets its own test and its own overflow check.
Can meetsGuideline check contrast and tap targets?
Only as an advisory tripwire. The skill says white text on #FAFAFA passes the contrast guideline because of an open Flutter defect, and that the tap target guideline skips nodes flush with the view edge. It asserts contrast on color values in pure Dart and measures tap targets with a getSize loop.
Why pin the device size in every layout test?
The default widget surface is 800x600 logical, which is wider than any phone, so content fits and the suite stays green while the shipped phone is broken. Because physicalSize is in physical pixels, the skill multiplies the logical size by the device pixel ratio.
Can I clamp the text scale to make a failing matrix pass?
No. The skill says never clamp TextScaler. withClampedTextScaling, textScaleFactor and FittedBox defeat the matrix while contrast and tap target checks stay green, and they override the user's own OS setting. The fix is to change the layout, not the text, so the overflow matrix keeps catching the most complex label.