Integration test for full coordinator and peer mentor stats flows
epic-activity-statistics-dashboard-user-interface-task-018 — Write Flutter integration tests covering the full end-to-end stats dashboard flow: peer mentor logs in, navigates to stats screen, changes time window, verifies KPI cards and chart update; coordinator logs in, views chapter-aggregated stats, taps a peer mentor row, verifies drill-down screen shows that peer mentor's data, navigates back, and confirms state is preserved. Use mocked Supabase responses to isolate UI layer. Verify role-scoping prevents cross-user data access.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 9 - 22 tasks
Can start after Tier 8 completes
Implementation Notes
The most common source of flakiness in Flutter integration tests is `pumpAndSettle` timing out on long animations or infinite loading states — add explicit `Duration` timeouts and assert intermediate states (e.g., shimmer renders before data) rather than waiting for a fully settled state. Structure the `FakeSupabaseClient` to support per-test response configuration via a `setResponse(table, filter, response)` API to avoid a single monolithic mock that couples all tests. For the role-scoping security test, override the auth provider to return a `peer_mentor` role, then attempt to push the coordinator route via `GoRouter.of(context).go('/stats/coordinator')` and assert the redirect destination. Use `addTearDown` in each test to reset any shared provider state.
Document the fixture JSON schema in a comment at the top of each fixture file so future maintainers know the expected shape.
Testing Requirements
Use the `integration_test` Flutter package for all tests in this task — these run on a real device or simulator, not a headless widget tester. Structure tests in `integration_test/stats_dashboard_integration_test.dart`. Use `WidgetTester.pumpAndSettle()` after navigation actions to wait for async state resolution. Mock Supabase by overriding the Supabase client provider in the root `ProviderScope` with a `FakeSupabaseClient` that returns fixture JSON.
Define fixture files in `test/fixtures/stats/` (peer_mentor_stats_30d.json, coordinator_stats_chapter_a.json, etc.). Write three top-level `group()` blocks: 'Peer mentor stats flow', 'Coordinator drill-down flow', 'Role-scoping security'. Each group contains 3–5 focused `testWidgets` scenarios. CI configuration should run integration tests in a separate job using `flutter test integration_test/ -d
fl_chart renders chart elements on a Canvas, making individual bars and data points invisible to the Flutter Semantics tree by default. Without explicit Semantics wrappers, VoiceOver and TalkBack users receive no chart information, violating the WCAG 2.2 AA requirement mandated by all three partner organizations.
Mitigation & Contingency
Mitigation: Wrap the fl_chart widget in a Semantics node with a dynamically generated textual description of the chart data (e.g., 'Bar chart: January 12, February 8, March 15 sessions'). Implement a collapsible data table alternative beneath the chart that screen readers can navigate row by row. Validate with VoiceOver on iOS and TalkBack on Android before the epic is marked complete.
Contingency: If fl_chart's Canvas rendering cannot be made accessible within the epic timeline, ship the chart hidden from the Semantics tree with ExcludeSemantics and promote the data table alternative to first-class UI so screen reader users have full access to the information. Log a tech-debt item to revisit native chart accessibility in a future sprint.
Coordinators managing up to 5 chapters (NHF requirement) require the PeerMentorStatsList to display chapter affiliation labels for each row. With large chapter lists and many peer mentors, the list could become overwhelming and cause layout overflow or scrolling performance issues on lower-end Android devices.
Mitigation & Contingency
Mitigation: Implement chapter filtering as a segmented control above the list so coordinators can scope the list to one chapter at a time. Use ListView.builder (lazy rendering) rather than a Column of all rows. Profile scroll performance on a low-end Android device (Pixel 4a equivalent) with 50 peer mentors in scope during development.
Contingency: If multi-chapter display causes unacceptable performance, ship with single-chapter scope as the default view and a chapter switcher dropdown, deferring the combined cross-chapter list to a follow-up sprint.
Summary cards and the chart widget rebuilding simultaneously on provider state change could cause a visible jank frame on slower devices, degrading perceived quality especially since this screen is intended to feel motivating and polished for gamification purposes.
Mitigation & Contingency
Mitigation: Use AnimatedSwitcher with a short fade transition (150ms) on the stats cards and chart so that data replacement feels intentional rather than jarring. Profile with Flutter DevTools on a mid-range device and ensure no frame exceeds 16ms during a time-window switch.
Contingency: If animation introduces complexity that delays delivery, ship without animation and use a loading skeleton (shimmer effect) during re-fetch instead, which is simpler and equally effective at masking the data swap.
If the role-based screen dispatch is misconfigured, a peer mentor could navigate to the coordinator stats screen and see aggregated chapter data for all peer mentors, which is a data privacy violation and a compliance risk for all three organizations.
Mitigation & Contingency
Mitigation: Implement role guard at the router level using an existing role-route-guard component so the coordinator screen route is unreachable for peer mentor roles. Add a widget test that mounts the coordinator screen with a peer mentor session token and asserts that the guard redirects to the no-access screen.
Contingency: If a bypass is found in QA, add a secondary in-screen role assertion in the coordinator screen's initState that throws an AuthorizationException and navigates to the error screen, ensuring defence in depth regardless of router configuration.