Accessibility Testing for Flutter with Widgetbook

Flutter's flutter_test package ships four accessibility guidelines. These guidelines cover only three of the 56 success criteria in Web Content Accessibility Guidelines (WCAG) 2.2 at conformance levels A and AA. Getting a Flutter app to WCAG AA is mostly manual work. When prioritizing accessibility and investing sufficient resources, most teams manage to get their app accessible to a satisfying accessible level through hard, manual work. However, keeping the app WCAG compliant is a different problem. During the next audit, developers notice that they accidentally merged unintended accessibility changes that introduced accessibility violations. Their app silently loses the accessibility level. Widgetbook Cloud's accessibility regression testing helps you keep your app accessible.

Book a demo to see Widgetbook Cloud's accessibility regression testing in action.

This guide has three parts.

1. Why accessibility matters, and why it is now a legal requirement for some apps.

2. Why testing it in Flutter is harder than on the web, and what the four guidelines actually catch when you run them on a real component.

3. How Widgetbook and Widgetbook Cloud automate the part that can be automated and run it on every pull request, while being honest about the part that still needs a person.

Why accessibility matters

More people can use your product. The World Health Organization estimates that 1.3 billion people, about 16% of the world, live with a significant disability (study). Disability is also situational rather than only permanent. A broken wrist, a missing finger, or a phone held in one hand on a crowded train all change how someone uses an app.

Accessible design helps everyone, not only the people it was built for. Q42 analysed 1.5 million iOS users and found that a third of them change the text size on their phone, 20% larger and 13% smaller (study). That means roughly one user in five runs your interface at a text scale you don't test on every pull request. On most apps that is a bigger group than any locale you ship to, and they do not file bugs about truncated text. They just stop using the screen or even your app.

In Europe, some apps now have to be accessible by law. The European Accessibility Act has been applicable since 28 June 2025. It does not cover every app, but it does cover specific sectors including e-commerce, consumer banking, e-books, passenger transport, and telecommunications. If you build a banking app for the European market, you are in scope. Conformance is demonstrated against EN 301 549, which incorporates WCAG at Level AA.

Why Flutter makes this hard

Native Android builds a view hierarchy that the operating system understands, with real Button and TextView objects, and TalkBack reads that hierarchy directly. Flutter does not work that way. It renders everything into a single drawing surface, so the operating system sees one opaque view. To make the app accessible, Flutter maintains a separate semantics tree in parallel, and an engine bridge translates that tree into the platform accessibility tree that TalkBack and VoiceOver read.

This has a few consequences that shape how you test:

1. Nothing is accessible by default. A GestureDetector wrapped around a Container produces no semantics node, so it cannot be focused, announced, or activated, whereas an HTML button is a button whether or not you thought about it.

2. There is also no equivalent of the web's axe-core for Flutter. That means no established rule library and no published mapping from WCAG to Flutter APIs.

3. The semantics tree your tests inspect is not the same thing as what the user hears. There are three representations in a row. Your Flutter code builds the semantics tree, which is the tree of SemanticsNodeobjects that flutter_test reads. The engine then translates that into the platform accessibility tree, meaning AccessibilityNodeInfo on Android and UIAccessibilityElement on iOS. Finally TalkBack or VoiceOver reads the platform tree and turns it into speech, adding its own role names, pauses, and grouping along the way.

meetsGuidelines - Flutter's automated accessibility checks

The four guidelines live in flutter_test and run inside an ordinary widget test.

testWidgets('follows a11y guidelines', (tester) async {
  final handle = tester.ensureSemantics();
  await tester.pumpWidget(wrap(row));

  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
  await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
  await expectLater(tester, meetsGuideline(textContrastGuideline));

  handle.dispose();
});

testWidgets('follows a11y guidelines', (tester) async {
  final handle = tester.ensureSemantics();
  await tester.pumpWidget(wrap(row));

  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
  await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
  await expectLater(tester, meetsGuideline(textContrastGuideline));

  handle.dispose();
});

testWidgets('follows a11y guidelines', (tester) async {
  final handle = tester.ensureSemantics();
  await tester.pumpWidget(wrap(row));

  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
  await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
  await expectLater(tester, meetsGuideline(textContrastGuideline));

  handle.dispose();
});

What they catch on a real component

PaymentRequestRow renders one pending request. It has an avatar, the requester's name, a masked card number, a status badge, the amount, and a pair of circular accept and decline buttons. Those buttons ship with a deliberate violation so this article has something to catch: they are 32×32 and they carry no semantic label. Here is the first guideline run against the component.

const _mock = PaymentRequestRow(
  name: 'Alice Bergmann', last4: '4471', amount: '€50.00',
);

await expectLater(tester, meetsGuideline(androidTapTargetGuideline));

const _mock = PaymentRequestRow(
  name: 'Alice Bergmann', last4: '4471', amount: '€50.00',
);

await expectLater(tester, meetsGuideline(androidTapTargetGuideline));

const _mock = PaymentRequestRow(
  name: 'Alice Bergmann', last4: '4471', amount: '€50.00',
);

await expectLater(tester, meetsGuideline(androidTapTargetGuideline));

Expected: Tappable objects should be at least Size(48.0, 48.0)
   Which: SemanticsNode#9(Rect.fromLTRB(711.0, 284.0, 743.0, 316.0),
          actions: [focus, tap], flags: [isButton, isFocusable]

Expected: Tappable objects should be at least Size(48.0, 48.0)
   Which: SemanticsNode#9(Rect.fromLTRB(711.0, 284.0, 743.0, 316.0),
          actions: [focus, tap], flags: [isButton, isFocusable]

Expected: Tappable objects should be at least Size(48.0, 48.0)
   Which: SemanticsNode#9(Rect.fromLTRB(711.0, 284.0, 743.0, 316.0),
          actions: [focus, tap], flags: [isButton, isFocusable]

Running all four across both Figma themes gives a precise verdict, and one result you might not expect.

Contrast passes in both themes. It passes because the masked card line uses colors.textSecondary, a design token that is already AA, instead of a hardcoded grey. The design system stopped the bug before a test could find it. This is the cheapest work you can do and the work most teams skip. If you fix contrast and minimum target size in your tokens and your component APIs, whole categories of violation stop being possible rather than merely becoming detectable later.

The fix, also tested

A correct action button is a 48×48 tap target with a button role and a label that says what the control does. Wrapping the button in MergeSemantics combines the ink response and the Semantics widget into a single node, so the label, the button flag, and the tap action all end up on the same node the guidelines inspect.

MergeSemantics(
  child: Semantics(
    button: true,
    label: 'Accept €50.00 from Alice Bergmann',
    child: Material(
      color: colors.statusSuccessBg,
      shape: const CircleBorder(),
      child: InkWell(
        onTap: onAccept,
        customBorder: const CircleBorder(),
        child: SizedBox(
          width: 48, height: 48, // was 32×32
          child: Icon(Icons.check, size: 14, color: colors.statusSuccessText),
        ),
      ),
    ),
  ),
)

MergeSemantics(
  child: Semantics(
    button: true,
    label: 'Accept €50.00 from Alice Bergmann',
    child: Material(
      color: colors.statusSuccessBg,
      shape: const CircleBorder(),
      child: InkWell(
        onTap: onAccept,
        customBorder: const CircleBorder(),
        child: SizedBox(
          width: 48, height: 48, // was 32×32
          child: Icon(Icons.check, size: 14, color: colors.statusSuccessText),
        ),
      ),
    ),
  ),
)

MergeSemantics(
  child: Semantics(
    button: true,
    label: 'Accept €50.00 from Alice Bergmann',
    child: Material(
      color: colors.statusSuccessBg,
      shape: const CircleBorder(),
      child: InkWell(
        onTap: onAccept,
        customBorder: const CircleBorder(),
        child: SizedBox(
          width: 48, height: 48, // was 32×32
          child: Icon(Icons.check, size: 14, color: colors.statusSuccessText),
        ),
      ),
    ),
  ),
)

All four guidelines now pass, in both themes, and the button announces "Accept €50.00 from Alice Bergmann" instead of an ambiguous "Accept". No rule can make that distinction for you, but once you have decided on the wording, a getSemantics assertion can pin it so it does not quietly regress.

What they do not catch

Print the semantics tree with debugDumpSemanticsTree() and read the labels in order.

None of the four guidelines flag the decorative avatar that gets announced, the context-free "•• 4471", or the fact that one row is seven separate stops for a screen reader user. They miss these because they only inspect elements that are already accessible enough to appear in the tree at all. The clearest example is a whole row wrapped in a plain GestureDetector. It has no semantics node, so labeledTapTargetGuideline has nothing to iterate over, and the test stays green while the row is completely invisible to TalkBack. Reading the dump out loud in code review and asking whether you could dictate each label to a stranger over the phone catches more real bugs than any automated check in this article, and it belongs in the pull request rather than in a pre-release audit.

Accessibility violation detection and regressions with Widgetbook

Two problems tend to get conflated. Reaching a good accessibility level is a detection problem, and in Flutter most of that work is manual because automated detection only reaches three criteria. Keeping that level is a regression problem, where the violations are already fixed, and you only need to know when changes appear again. Widgetbook helps with both, because a story is an isolated, named, parameterised UI state, and that makes it a place to run tests, for a single component or for a whole screen.

Violation detection across the mode matrix

A story already lists every meaningful state, including the awkward ones you would never get from production data. The scenarios pin the data variations, so they stay focused on content and say nothing about themes or device sizes.

scenarios: [
  _Scenario(name: 'default',      args: _Args.fixed(name: 'Alice Bergmann', /*…*/)),
  _Scenario(name: 'long name',    args: _Args.fixed(name: 'Alexandria Featherstonehaugh-Montgomery', /*…*/)),
  _Scenario(name: 'large amount', args: _Args.fixed(amount: '€12,500.00', /*…*/)),
],

scenarios: [
  _Scenario(name: 'default',      args: _Args.fixed(name: 'Alice Bergmann', /*…*/)),
  _Scenario(name: 'long name',    args: _Args.fixed(name: 'Alexandria Featherstonehaugh-Montgomery', /*…*/)),
  _Scenario(name: 'large amount', args: _Args.fixed(amount: '€12,500.00', /*…*/)),
],

scenarios: [
  _Scenario(name: 'default',      args: _Args.fixed(name: 'Alice Bergmann', /*…*/)),
  _Scenario(name: 'long name',    args: _Args.fixed(name: 'Alexandria Featherstonehaugh-Montgomery', /*…*/)),
  _Scenario(name: 'large amount', args: _Args.fixed(amount: '€12,500.00', /*…*/)),
],

1. Global addons are automatically tested across all scenarios. Here, the three data scenarios are tested across two themes and two device sizes. That is already dozens of rendered and checked states in a single flutter test run, with no device attached, and the four guidelines run in every one of those cells. That multiplication is what makes the four rules worth having.

2. Contrast is checked in each theme. A grey that passes on the light card but fails on the dark one is caught, where a team that runs the contrast guideline once in one theme would miss it.

3. Labels are checked in each locale. A missing translation key that renders an empty label fails labeledTapTargetGuideline in Arabic, on a commit nobody clicked through by hand.

4. Tap targets are checked at each device size. An Expanded that squeezes the buttons on a narrow 320-logical-pixel screen is caught even though it looks fine at 430.

5. Text overflow is caught too. Rendering the long name scenario at a text scale of 2.0 throws a RenderFlex overflowed error without needing any accessibility rule at all, and that overflow affects the one-in-five users who increased their text size.

Regressions through the semantics diff

This is where the real leverage is, and it is worth being precise about why. Violation detection reaches only three WCAG criteria right now. Regression reaches every criterion you have already satisfied, because a diff does not need a rule. It does not have to know what a correct label, a correct focus order, or a correct heading structure looks like. It only has to notice that the tree changed.

That is a much bigger set than it sounds, because almost all of WCAG AA has no automated check in Flutter, and yet almost all of it leaves a trace in the semantics tree. And those that don't are caught by the visual regression tests of Widgetbook Cloud. A label, a button role, a header flag, the order nodes are visited, whether two elements are one merged node or two separate ones: all of it lives in the semantics tree. Once you have done the manual work to get those right, that correct tree becomes your baseline. From then on, every one of those properties is guarded, including the ones no rule could ever have found in the first place.

Widgetbook Cloud captures the semantics tree for every scenario and diffs it against the previous build, right next to the visual diff, and the two cover different failures. The visual diff catches what changed on the widget or screen. The semantics diff catches what changed for assistive technology, which is usually invisible on screen.

Here, you can see an example:

You fixed the accept button by adding a label, but six weeks later someone refactors the button, and the label is dropped. The render is pixel-identical, so the visual diff sees nothing, but the label is gone, and the semantics diff shows it on Widgetbook Cloud alongside the accessibility violations. The same holds if a refactor drops a Semantics wrapper, merges two nodes, removes a header flag, or reorders traversal.

Widgetbook Cloud does not get your app to AA automatically. You need to invest the manual work. But once the app is accessible, the four guidelines together with the semantics and visual regression tests make sure it stays accessible. An accessibility bug can no longer ship quietly on an unrelated pull request, which is how nearly all of them ship today.

Book a demo to see Widgetbook Cloud's accessibility regression testing in action.

The workflow, and what it cannot do

The full picture has a few stages that build on each other.

1. At the design stage you put contrast and minimum target size into your tokens and component APIs, and you annotate reading order and heading levels in Figma.

2. In static analysis, you can add a custom_lint rule that flags when no semantic label is set.

3. Locally, you run the component and screen scenarios through the four guidelines across the mode matrix, and you make that pass a requirement for merging.

4. In Widgetbook Cloud you keep a baseline, diff the semantics tree, and see per-scenario violations on the pull request.

5. Then there is manual screen-reader testing.

Summary

Flutter's four guidelines cover three of 56 WCAG criteria and miss the most common Flutter accessibility bug. Reaching WCAG AA is therefore mostly manual, but the two hard parts are separable. Detection of the automatable slice runs continuously via Widgetbook and flutter test, because the four guidelines execute in every cell of the theme, locale, text-scale, and device matrix. Regression needs no rules at all, because Widgetbook Cloud's semantics-tree diff flags the moment a refactor drops or changes a label, merges a node, or removes a header flag, which the visual diff cannot see. Widgetbook Cloud does not get your app to AA on its own, but it does stop it from regressing once you have done the manual work to get there.