Implement Full Keyboard Access navigation test
epic-navigation-and-gesture-accessibility-service-and-audit-task-009 — Implement Full Keyboard Access navigation simulation in AccessibilityAuditRunner using Flutter integration test key injection to tab through interactive elements on key flows. Assert that every interactive element is reachable via sequential key navigation, that focus indicators are visible, and that no focus traps exist. Record FocusNavigationViolation records for failures.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Use WidgetTester.sendKeyEvent(LogicalKeyboardKey.tab) in a loop, capturing FocusManager.instance.primaryFocus after each press. Maintain a visited-node set using the FocusNode identity (or its hashCode) to detect cycles. For focus indicator detection, find the widget under the primary focus node using find.byKey or find.ancestor, then inspect its decoration. Be aware that Flutter's default focus highlight only shows on non-touch platforms — you may need to configure the test environment with TargetPlatform.macOS or use a custom focus theme.
BLoC and Riverpod providers must be injected before screen pump. This is critical for WCAG 2.2 AA compliance (SC 2.1.1 Keyboard, SC 2.4.7 Focus Visible) — a requirement stated across all three client organizations.
Testing Requirements
Unit tests: verify FocusNavigationViolation model; verify the focus-trap cycle detection algorithm with a mock FocusNode graph that has a known cycle. Integration tests: pump a screen with all interactive elements in flutter_test, simulate Tab presses, assert focus advances through all elements; pump a screen with a deliberate focus trap and assert a FocusNavigationViolation with violationType=focus_trap is produced. Also test Shift+Tab reverse traversal for completeness. Coverage target: 85% of keyboard audit logic.
Critical edge case: test that a disabled button (isEnabled=false) is correctly skipped in traversal.
Flutter's SemanticsController used in integration tests is an internal or semi-internal API that can break between Flutter stable releases. If the audit runner relies heavily on undocumented semantics tree traversal, a Flutter upgrade could silently disable the audit checks without a build failure, creating false confidence.
Mitigation & Contingency
Mitigation: Use only the public flutter_test accessibility APIs (meetsGuideline, SemanticsController.ensureSemantics) and wrap all SemanticsController calls in a versioned helper class with explicit assertions that the expected semantics tree shape is still available. Pin the Flutter SDK range in pubspec.yaml.
Contingency: If SemanticsController APIs break on a Flutter upgrade, fall back to widget-level golden tests that include the semantics tree snapshot, combined with manual Switch Access and VoiceOver QA checklists executed before each release.
Flutter integration tests that simulate Switch Access traversal on multiple screens can be slow (30–120 seconds per test flow), which may make the audit runner impractical to run on every CI commit if the test suite already has long run times.
Mitigation & Contingency
Mitigation: Scope the audit runner to a dedicated integration test target that runs on pull requests targeting main and on nightly builds, not on every push. Parallelise test shards in CI to keep wall-clock time acceptable. Profile audit run times during development and trim any flows that duplicate coverage.
Contingency: If CI run times exceed acceptable thresholds, split the audit runner into a fast smoke suite (touch targets and semantic labels only, runs on every PR) and a thorough traversal suite (Switch Access simulation, runs nightly), with the nightly failure blocking the release branch rather than every PR.