🧪 Validation & Testing - Setup

This page covers the one-time setup steps for each testing tool referenced throughout the accessibility guidelines. Individual guideline pages describe what to verify; this page describes how to enable and configure each tool.

---

SemanticsDebugger

Wrap your widget tree in Flutter’s built-in SemanticsDebugger to overlay the semantic tree directly on screen. No device or screen reader required, every semantic node is highlighted in the running app.

SemanticsDebugger(
  child: MyApp(),
)

Remove the wrapper before shipping to production.

---

accessibility_tools

The accessibility_tools package provides runtime checks and a developer overlay that catches accessibility regressions during development.

Add it to your dev_dependencies:

# pubspec.yaml
dev_dependencies:
  accessibility_tools: ^x.x.x

Wrap your app widget:

AccessibilityTools(
  child: MyApp(),
)

To activate the semantic overlay, tap the settings icon in the on-screen controls and enable Screen reader mode. This produces the same view as SemanticsDebugger.

---

TalkBack & VoiceOver

Enable the platform screen reader to test with real assistive technology on a physical device or emulator.

Platform	Path
Android (TalkBack)	Settings → Accessibility → TalkBack
iOS (VoiceOver)	Settings → Accessibility → VoiceOver

Once enabled, use swipe gestures to navigate between elements and double-tap to activate. Each guideline page describes what to verify once you are navigating with a screen reader.

---

flutter_test

Use flutter_test to assert semantic properties programmatically. This is the fastest way to catch regressions in CI. Common setup:

testWidgets('example semantic assertion', (tester) async {
  await tester.pumpWidget(MaterialApp(home: Scaffold(body: MyWidget())));

  // Assert a semantic label
  expect(
    tester.getSemantics(find.byType(MyWidget)),
    matchesSemantics(label: 'Expected label'),
  );
});

Each guideline page provides a subject-specific flutter_test snippet you can drop into your test suite.