Integration tests for full biometric auth flow on both platforms
epic-biometric-session-authentication-core-services-task-016 — Write integration tests using flutter_test that cover the complete authentication flow end-to-end: biometric verification → Supabase session refresh → Riverpod state propagation → role-based navigation. Tests run on both iOS simulator (Face ID) and Android emulator (fingerprint) using mocked LocalAuth and a test Supabase project. Covers online, offline, and token-expiry scenarios to validate the full service interaction chain.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 8 - 48 tasks
Can start after Tier 7 completes
Implementation Notes
Use mocktail for mocking platform channels since local_auth uses method channels — mock the LocalAuthentication class directly. For Supabase, use the Supabase Dart client's built-in test utilities or create a fake GoTrueClient. Structure tests with arrange-act-assert pattern: (1) arrange — override providers with mocked implementations, seed SecureSessionStorage with a pre-defined StoredSession, (2) act — call the biometric auth use case / trigger the auth event, (3) assert — verify Riverpod state, verify Supabase refresh was/was not called, verify navigation route. For offline detection, mock connectivity_plus to return ConnectivityResult.none.
For token expiry, seed SecureSessionStorage with a StoredSession where expiry is DateTime.now().subtract(Duration(hours:1)). Ensure each test is fully isolated — call container.dispose() in tearDown. Avoid using real timers; use FakeAsync where time-dependent logic is involved. TestFlight distribution applies to release builds, not test execution.
Testing Requirements
This task IS the testing task. Write flutter_test integration tests in test/integration/biometric_auth_flow_test.dart. Use a ProviderContainer with Riverpod overrides to inject mocked LocalAuth, mocked Supabase client, and an in-memory SecureSessionStorage. Group tests by scenario: (1) happy path online, (2) happy path offline with valid cache, (3) expired token, (4) biometric failure cascade, (5) role-based navigation assertions.
Each group should have setup/teardown managing ProviderContainer lifecycle. Verify state transitions explicitly using container.read() after each async step. Run tests on iOS simulator and Android emulator as part of CI pipeline using flutter test integration_test/. Assert navigation using GoRouter or Navigator state checks — do not rely on UI widget text alone.
Multiple concurrent callers (e.g., SessionResumeManager and a background sync service) could simultaneously detect a near-expired token and each invoke SupabaseSessionManager.refreshSession(), causing duplicate refresh API calls and potentially a token invalidation race condition on the Supabase Auth server. This can result in one caller receiving a valid refreshed token while another receives a 401, causing intermittent authentication failures.
Mitigation & Contingency
Mitigation: Implement a single-flight pattern inside SupabaseSessionManager so that concurrent refresh calls coalesce into one in-flight request. Use a Dart Completer or AsyncMemoizer to ensure all waiters receive the same refreshed token. Write a concurrent integration test to validate the single-flight behaviour.
Contingency: If the single-flight pattern introduces deadlocks or timeout complexity, fall back to a mutex-based lock with a 10-second timeout, logging a warning if the lock is held longer than expected, and triggering a full re-login if the refresh ultimately fails.
Supabase Row-Level Security policies evaluate the JWT claims (user_id, role, org_id) on every query. If the refreshed token contains stale or changed claims — for example if a coordinator's role was updated server-side — RLS may silently block data access even though the session appears valid from the client's perspective, causing confusing empty screens rather than an authentication error.
Mitigation & Contingency
Mitigation: After every token refresh, decode the new JWT and compare key claims (role, org_id) with the cached values. If claims have changed, emit a session-claims-changed event that triggers a role re-resolution and navigation reset. Document this behaviour in the SupabaseSessionManager API contract.
Contingency: If claims drift is detected in production and causes data visibility issues, provide a force-refresh mechanism in the UI (pull-to-refresh on home screen) that clears cached role state and re-fetches from Supabase, accompanied by a user-visible toast indicating the session was refreshed.
Allowing session resumption from cached local token when offline introduces a window where a revoked or invalidated session can still grant app access. For example, if a coordinator deactivates a peer mentor's account while the mentor is offline, the mentor continues to have access until connectivity is restored and the token is validated server-side.
Mitigation & Contingency
Mitigation: Set a maximum offline grace period (e.g., 24 hours) stored alongside the token in SecureSessionStorage. If the grace period is exceeded, force a full credential re-login regardless of connectivity status. Scope offline access to read-only operations only, requiring connectivity for any write that reaches Supabase.
Contingency: If the offline grace period logic is found to be insufficient for compliance, implement remote session invalidation via a lightweight push notification that clears SecureSessionStorage even when the app is backgrounded, using FCM with a data-only message.