🏠 Overview › ✅ Implementation Tasks ›✅ epic-membership-recruitment-peer-mentor-ui-task-013

Write widget and integration tests for referral UI

epic-membership-recruitment-peer-mentor-ui-task-013 — Write Flutter widget tests for ReferralCodeScreen, RecruitmentStatsWidget, and NewMemberOnboardingScreen covering rendering, user interactions (copy, share, form submit), loading/error states, and Riverpod provider mocking. Add integration tests for the deep-link → onboarding → attribution submission flow.

high priority medium complexity testing pending testing specialist Tier 6

Acceptance Criteria

Widget test file exists for each of the three screens/widgets: referral_code_screen_test.dart, recruitment_stats_widget_test.dart, new_member_onboarding_screen_test.dart
ReferralCodeScreen tests cover: referral code rendered, copy button triggers Clipboard.setData with correct value, share button invokes share_plus with correct payload, loading state renders spinner, error state renders error widget
RecruitmentStatsWidget tests cover: correct stat values rendered for given provider data, empty state renders placeholder, chart/stat elements have expected Semantics values
NewMemberOnboardingScreen tests cover: invalid token renders error state, valid token renders welcome + form, form validation errors shown on empty submit, form validation errors shown for invalid phone/email, valid form submit triggers ReferralAttributionService call, loading overlay shown during submission, success navigates to next route, API error shows error banner with fields retained
All Riverpod providers used by the tested widgets are overridden with mock/stub implementations — no real Supabase calls in widget tests
Integration test file deep_link_onboarding_test.dart covers the full flow: app launch with deep link → token validation → welcome screen → form fill → submit → navigation to membership registration
Integration test uses a dedicated test Supabase environment (not production); test data is seeded and torn down within the test
All widget tests pass in CI with flutter test; integration tests pass with flutter test integration_test/
Test coverage for the three screens/widgets reaches ≥ 80% line coverage as reported by flutter test --coverage

Technical Requirements

frameworks
Flutter
flutter_test
Riverpod (ProviderScope overrides)
GoRouter (MockGoRouter or NavigatorObserver)
apis
Supabase (test environment only, for integration tests)
data models
contact
assignment
accessibility_preferences
performance requirements
Full widget test suite for all three screens completes in under 30 seconds
Integration test suite completes in under 3 minutes on CI runner
security requirements
Test Supabase credentials stored in CI secrets — never committed to source control
Integration test seed data uses synthetic PII (fake names, phones, emails) — never real user data
ui components
ReferralCodeScreen
RecruitmentStatsWidget
NewMemberOnboardingScreen

Execution Context

Execution Tier
Tier 6

Tier 6 - 158 tasks

Can start after Tier 5 completes

Implementation Notes

Structure test files to mirror the source file structure (test/screens/, test/widgets/). Use a shared test_helpers.dart to define reusable widget wrapper factories (pumpApp() that wraps under ProviderScope + MaterialApp + GoRouter). Prefer pump() + tester.tap() + pump() over pumpAndSettle() to avoid flaky timeouts on async operations; use pumpAndSettle() only where animations must complete. For async provider states, use tester.pumpWidget with a ProviderContainer and explicitly set provider state before pumping the widget.

The integration test deep link simulation can use Flutter's IntegrationTestWidgetsFlutterBinding and send a platform message simulating a deep link URI. Document any skipped edge cases with a // TODO: comment referencing the specific acceptance criterion number.

Testing Requirements

This task IS the testing work. Use flutter_test for widget tests. Use Riverpod's ProviderContainer with overrides to inject mocks. Use GoRouter's NavigatorObserver or a fake router to assert navigation events without a real router instance.

For the copy button, mock Clipboard via the test binding. For the share button, mock share_plus using a platform channel mock. Write parametrized tests for form validation edge cases (boundary values, Norwegian chars). Integration tests: use flutter_driver or integration_test package; seed a referral code in Supabase test DB before each test run and clean up afterward using tearDownAll.

Component
Recruitment Stats Widget
ui low
Dependencies (1)
Audit ReferralCodeScreen, RecruitmentStatsWidget, and NewMemberOnboardingScreen for WCAG 2.2 AA compliance. Verify contrast ratios using design token color palette, ensure all interactive elements have 48dp touch targets, add Semantics widgets where Flutter defaults are insufficient, and test with TalkBack and VoiceOver. epic-membership-recruitment-peer-mentor-ui-task-012
Epic Risks (3)
medium impact medium prob technical

QR codes rendered at the minimum 200×200 size may fail to scan under typical indoor lighting conditions on older or lower-resolution phone cameras, causing recruitment moments to fail when a peer mentor shows the screen to a prospective member.

Mitigation & Contingency

Mitigation: Set the default QR render size to 260×260 logical pixels (not the 200px minimum) and apply a high-contrast white module background. Test scan reliability on at minimum three physical devices (budget Android, mid-range Android, iPhone SE) before marking the screen as done.

Contingency: If scan reliability remains an issue, add a 'Enlarge QR' full-screen mode triggered by tapping the code, and ensure the text referral URL with copy-to-clipboard is always visible as a fallback sharing method.

high impact medium prob integration

The onboarding screen submits attribution and then hands off to an external membership registration URL (HLF's Dynamics portal or similar). If the external URL is unavailable, changes its format, or requires authentication the new member does not have, the conversion funnel is broken at its final step.

Mitigation & Contingency

Mitigation: Confirm the external registration URL and its expected query parameters with HLF's portal team before implementing the handoff. Record the pending_signup attribution event before launching the URL so data is not lost if the external site fails. Display a fallback message with contact information if the URL launch fails.

Contingency: If the external membership URL is not available at feature launch, implement a temporary form that collects name and email and stores a pending_member record in Supabase, allowing coordinators to manually complete registration while the integration is finalised.

low impact medium prob integration

Embedding the RecruitmentStatsWidget on the peer mentor home screen may conflict with existing layout components (activity summary, badge shelf), causing overflow or requiring a redesign of the home screen that is outside this epic's scope.

Mitigation & Contingency

Mitigation: Design the widget as a horizontally constrained card with a maximum height of 96dp so it can be inserted into any vertical list without overflow. Coordinate with the home screen's existing layout owners before starting the embedding task.

Contingency: If home screen embedding creates unacceptable layout conflicts, defer embedding to a separate home-screen redesign task and make the widget accessible only via the dedicated ReferralCodeScreen for the initial release.

Quick Links
All Tasks Execution Plan