🏠 Overview › ✅ Implementation Tasks ›✅ epic-email-password-login-auth-logic-task-010

Unit test AuthService error mapping and session logic

epic-email-password-login-auth-logic-task-010 — Write unit tests for the GoTrue error mapper covering all mapped error categories (invalid credentials, network, rate limit, server error, and unknown fallback). Test AuthService.signIn() with mocked Supabase client responses. Test session persistence and restoration paths. Target 100% branch coverage on the error mapper.

high priority medium complexity testing pending testing specialist Tier 5

Acceptance Criteria

GoTrue error mapper unit test covers: 'Invalid login credentials' → InvalidCredentialsException
GoTrue error mapper unit test covers: network timeout/unreachable → NetworkException
GoTrue error mapper unit test covers: 429 Too Many Requests → RateLimitException
GoTrue error mapper unit test covers: 5xx server responses → ServerException
GoTrue error mapper unit test covers: unrecognized error code → generic ServerException (unknown fallback branch)
AuthService.signIn() test with mocked successful Supabase response → returns AuthSession with correct fields
AuthService.signIn() test with mocked Supabase AuthException → mapper invoked and typed exception rethrown
AuthService.persistSession() test: stores session token in secure storage (mock storage verified)
AuthService.restoreSession() test: returns AuthSession when valid token found in secure storage
AuthService.restoreSession() test: returns null when no token in storage
AuthService.restoreSession() test: returns null and clears storage when token is expired
100% branch coverage reported on the GoTrue error mapper function
All tests pass with flutter_test and use mocktail or Mockito for dependencies

Technical Requirements

frameworks
Flutter
flutter_test
apis
Supabase GoTrue client (mocked)
AuthService.signIn()
AuthService.persistSession()
AuthService.restoreSession()
data models
AuthSession
InvalidCredentialsException
NetworkException
RateLimitException
ServerException
GoTrueException
performance requirements
All unit tests must run in under 2 seconds total — no real network calls
Use fake/mock Supabase client; never call real Supabase endpoints in unit tests
security requirements
Tests must verify that raw GoTrue error messages are NOT exposed in thrown exceptions — only typed domain exceptions
Verify session tokens are stored in secure storage mock, not in-memory plain maps

Execution Context

Execution Tier
Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

Implementation Notes

Mock the Supabase GoTrue client by creating a fake implementation or using mocktail's mock. The error mapper is a pure function (GoTrueException input → domain exception output) — test it in isolation first before testing AuthService as a whole. For session storage tests, inject a mock SecureStorage interface into AuthService rather than using the real flutter_secure_storage package in tests. Group test files by component: `test/auth/gotrue_error_mapper_test.dart` and `test/auth/auth_service_test.dart` — keep them separate for clarity.

Use `throwsA(isA())` matchers for exception assertions.

Testing Requirements

Use flutter_test with mocktail for mocking. Structure test file as: (1) 'GoTrue error mapper' group with one test per error branch; (2) 'AuthService.signIn' group with success and each exception path; (3) 'AuthService session persistence' group covering persistSession and restoreSession scenarios. Use setUp() to create fresh mocks per test. Run coverage with `flutter test --coverage` and verify 100% on the mapper.

All tests must be hermetic — no shared mutable state between tests.

Component
Authentication Service
service medium
Dependencies (1)
After successful authentication, AuthService resolves the authenticated user's role (admin, coordinator, peer_mentor) by querying the role repository. Return the role alongside the session result so the caller can route to the correct home screen. Handle the case where a user has no assigned role by returning a NoRoleResult that triggers the no-access screen. epic-email-password-login-auth-logic-task-005
Epic Risks (2)
high impact medium prob integration

Supabase GoTrue returns HTTP error codes and string messages that may change between SDK versions. Incorrect or incomplete mapping could cause the wrong user-facing message to be shown (e.g., showing a generic error instead of a specific credential error), violating the plain-language feedback acceptance criteria and potentially exposing security-sensitive information.

Mitigation & Contingency

Mitigation: Pin the supabase_flutter SDK to a specific minor version in pubspec.yaml. Write integration tests that mock the Supabase HTTP layer and assert each error code maps to the correct domain exception. Document the mapping table as a constant in AuthService.

Contingency: If an unrecognized error code is received at runtime, catch it as an UnknownAuthException and display a generic safe message. Alert via crash reporting for triage and SDK update.

medium impact medium prob technical

If the user taps the sign-in button multiple times rapidly, concurrent authentication requests could result in race conditions: duplicate network calls, out-of-order state emissions, or multiple session tokens being written to secure storage.

Mitigation & Contingency

Mitigation: Use bloc concurrency transformer (droppable or restartable) to ensure only one authentication event is processed at a time. The BLoC should guard against submission while in LoginLoading state.

Contingency: Add a UI-level disable on the submit button when loading state is active as a secondary guard independent of BLoC concurrency control.

Quick Links
All Tasks Execution Plan