Refactor iOS UI tests to blueprint architecture

2026-02-20 10:38:15 -06:00
parent 710a8bd1d6
commit fe28034f3d
28 changed files with 7354 additions and 83 deletions
--- a/iosApp/CaseraUITests/Docs/Failing_Suites_0_3_Rebuild_Plan.md
+++ b/iosApp/CaseraUITests/Docs/Failing_Suites_0_3_Rebuild_Plan.md
@@ -0,0 +1,164 @@
+# Failing Suites 0-3: Coverage + Rebuild Plan
+
+## Baseline (from observed runs)
+- `Suite0_OnboardingTests`: 1 test, 1 failure
+- `Suite1_RegistrationTests`: 11 tests, 5 failures
+- `Suite2_AuthenticationTests`: 6 tests, 2 failures
+- `Suite3_ResidenceTests`: 6 tests, 6 failures
+
+Primary failure logs used:
+- `/tmp/ui_suite0.log`
+- `/tmp/ui_suites_1_3.log`
+
+---
+
+## Suite0
+
+### Failing test
+- `Suite0_OnboardingTests.test_onboarding`
+
+### What it is testing
+- End-to-end onboarding progression from welcome/login entry into account creation and onward.
+- UI interaction stability during onboarding form entry.
+
+### Observed failure point
+- Assertion failure: `Email field must become focused for typing`.
+
+### Rebuild in new arch
+Create a new test case focused on deterministic onboarding field interaction:
+- `Onboarding_EmailRegistration_FocusAndInputFlow`
+
+Coverage to preserve:
+- Email field reliably focusable and typeable.
+- Continue action only enabled after valid required inputs.
+- Onboarding progresses to next state after valid submission.
+
+Required infra:
+- `OnboardingScreen` page object with `tapEmailField()`, `typeEmail()`, `assertEmailFieldFocused()`.
+- Keyboard/overlay helper centralized (not inline in tests).
+
+---
+
+## Suite1
+Detailed plan already captured in:
+- `/Users/treyt/Desktop/code/MyCribKMM/iosApp/CaseraUITests/Docs/Suite1_Failing_Test_Rebuild_Plan.md`
+
+### Failing tests
+- `test07_successfulRegistrationAndVerification`
+- `test09_registrationWithInvalidVerificationCode`
+- `test10_verificationCodeFieldValidation`
+- `test11_appRelaunchWithUnverifiedUser`
+- `test12_logoutFromVerificationScreen`
+
+### Rebuild targets
+- `Registration_HappyPath_CompletesVerification_ThenCanLogout`
+- `Registration_InvalidVerifyCode_ShowsError_StaysUnverified`
+- `Registration_IncompleteVerifyCode_DoesNotVerify`
+- `Registration_UnverifiedUser_RelaunchStillBlockedFromMain`
+- `Registration_VerificationScreenLogout_ReturnsToLogin`
+
+---
+
+## Suite2
+
+### Failing tests
+- `Suite2_AuthenticationTests.test02_loginWithValidCredentials`
+- `Suite2_AuthenticationTests.test06_logout`
+
+### What they are testing
+
+#### `test02_loginWithValidCredentials`
+- Valid login path transitions from login screen to main app.
+- Authenticated state exposes main navigation (tab bar/app root).
+
+#### `test06_logout`
+- Logged-in user can logout.
+- Session is cleared and app returns to login state.
+
+### Observed failure points
+- `test02`: `Should navigate to main app after successful login`
+- `test06`: `Should be logged in` (precondition for logout flow failed)
+
+### Rebuild in new arch
+Create explicit state-driven auth tests:
+- `Auth_ValidLogin_TransitionsToMainApp`
+- `Auth_Logout_FromMainApp_ReturnsToLogin`
+
+Coverage to preserve:
+- Login success sets authenticated UI state.
+- Logout always clears authenticated state.
+- No false-positive “logged in” assumptions.
+
+Required infra:
+- `LoginScreen`, `MainTabScreen`, `ProfileScreen` page objects.
+- `AuthAssertions.assertAtLoginRoot()`, `assertAtMainRoot()`.
+- Test user fixture policy for valid credentials.
+
+---
+
+## Suite3
+
+### Failing tests
+- `Suite3_ResidenceTests.test01_viewResidencesList`
+- `Suite3_ResidenceTests.test02_navigateToAddResidence`
+- `Suite3_ResidenceTests.test03_navigationBetweenTabs`
+- `Suite3_ResidenceTests.test04_cancelResidenceCreation`
+- `Suite3_ResidenceTests.test05_createResidenceWithMinimalData`
+- `Suite3_ResidenceTests.test06_viewResidenceDetails`
+
+### What they are testing
+- Residence tab/list visibility.
+- Navigation to add-residence form.
+- Cross-tab navigation sanity.
+- Canceling residence creation.
+- Creating residence with minimal fields.
+- Opening residence details.
+
+### Observed failure pattern
+All 6 fail at the same gateway:
+- No `Residences` tab bar button match found.
+- This indicates tests are not reaching authenticated main-app state before residence assertions.
+
+### Rebuild in new arch
+Split auth precondition from residence behavior:
+- `Residence_Precondition_AuthenticatedAndAtResidencesTab`
+- `Residence_OpenCreateForm`
+- `Residence_CancelCreate_ReturnsToList`
+- `Residence_CreateMinimal_ShowsInList`
+- `Residence_OpenDetails_FromList`
+- `Residence_TabNavigation_MainSections`
+
+Coverage to preserve:
+- Residence flows validated only after explicit `main app ready` assertion.
+- Failures clearly classify as auth-gate vs residence-feature regression.
+
+Required infra:
+- `MainTabScreen.goToResidences()` with ID-first selectors.
+- `ResidenceListScreen`, `ResidenceFormScreen`, `ResidenceDetailScreen` page objects.
+- Shared precondition helper: `ensureAuthenticatedMainApp()`.
+
+---
+
+## Blueprint-aligned migration notes
+- Keep old-to-new mapping explicit in PR description.
+- Replace brittle text-based selectors with accessibility IDs first.
+- Use one state assertion per transition boundary:
+  - `login -> verification -> main app -> login`.
+- Move keyboard/strong-password overlay handling into one helper.
+- Do not mark legacy tests removed until replacement coverage is green.
+
+## Proposed replacement matrix
+- `Suite0.test_onboarding` -> `Onboarding_EmailRegistration_FocusAndInputFlow`
+- `Suite1.test07` -> `Registration_HappyPath_CompletesVerification_ThenCanLogout`
+- `Suite1.test09` -> `Registration_InvalidVerifyCode_ShowsError_StaysUnverified`
+- `Suite1.test10` -> `Registration_IncompleteVerifyCode_DoesNotVerify`
+- `Suite1.test11` -> `Registration_UnverifiedUser_RelaunchStillBlockedFromMain`
+- `Suite1.test12` -> `Registration_VerificationScreenLogout_ReturnsToLogin`
+- `Suite2.test02` -> `Auth_ValidLogin_TransitionsToMainApp`
+- `Suite2.test06` -> `Auth_Logout_FromMainApp_ReturnsToLogin`
+- `Suite3.test01` -> `Residence_Precondition_AuthenticatedAndAtResidencesTab`
+- `Suite3.test02` -> `Residence_OpenCreateForm`
+- `Suite3.test03` -> `Residence_TabNavigation_MainSections`
+- `Suite3.test04` -> `Residence_CancelCreate_ReturnsToList`
+- `Suite3.test05` -> `Residence_CreateMinimal_ShowsInList`
+- `Suite3.test06` -> `Residence_OpenDetails_FromList`
--- a/iosApp/CaseraUITests/Docs/Suite1_Failing_Test_Rebuild_Plan.md
+++ b/iosApp/CaseraUITests/Docs/Suite1_Failing_Test_Rebuild_Plan.md
@@ -0,0 +1,174 @@
+# Suite1 Registration Failing Tests: Coverage + Rebuild Plan
+
+## Scope
+This document captures what the currently failing registration-flow tests are trying to validate and how to recreate that coverage using the new UI test architecture.
+
+Source tests:
+- `Suite1_RegistrationTests.test07_successfulRegistrationAndVerification`
+- `Suite1_RegistrationTests.test09_registrationWithInvalidVerificationCode`
+- `Suite1_RegistrationTests.test10_verificationCodeFieldValidation`
+- `Suite1_RegistrationTests.test11_appRelaunchWithUnverifiedUser`
+- `Suite1_RegistrationTests.test12_logoutFromVerificationScreen`
+
+## Current Failure Context (Observed)
+- Registration submit does not transition to a verification screen in automation runs.
+- UI-level registration error shown during failures: `Password must be at least 8 characters`.
+- Because registration transition fails, downstream verification assertions fail.
+
+## What Each Failing Test Is Actually Testing
+
+### 1) `test07_successfulRegistrationAndVerification`
+Behavior intent:
+- User can register with valid credentials.
+- App transitions to verification state.
+- Entering valid verification code completes verification.
+- User lands in main app (tab bar available).
+- Logout returns user to login.
+
+Core business coverage:
+- Happy-path onboarding/auth state progression.
+- Verified user session gains app access.
+- Logout clears authenticated session.
+
+### 2) `test09_registrationWithInvalidVerificationCode`
+Behavior intent:
+- Registration reaches verification state.
+- Entering wrong code shows verification error.
+- User remains blocked from main app.
+
+Core business coverage:
+- Backend validation for invalid verification code.
+- No false positive promotion to verified state.
+
+### 3) `test10_verificationCodeFieldValidation`
+Behavior intent:
+- Verification screen enforces code format/length.
+- Incomplete code does not complete verification.
+- User remains on verification state.
+
+Core business coverage:
+- Client-side verification input guardrails.
+- No bypass with partial code.
+
+### 4) `test11_appRelaunchWithUnverifiedUser`
+Behavior intent:
+- User reaches unverified verification state.
+- App terminate/relaunch preserves unverified gating.
+- Relaunch must not allow direct main-app access.
+
+Core business coverage:
+- Session restore + auth gate correctness for unverified users.
+
+### 5) `test12_logoutFromVerificationScreen`
+Behavior intent:
+- Unverified user can explicitly logout from verification screen.
+- Verification UI dismisses.
+- App returns to interactive login screen.
+
+Core business coverage:
+- Logout works from gated verification state.
+- Session cleanup from pre-verified auth state.
+
+## Rebuild These in New Architecture
+
+## Shared Test Architecture Requirements
+Create/ensure these reusable pieces:
+- `AuthFlowHarness` (launch + auth preconditions + cleanup)
+- `RegistrationScreen` page object
+- `VerificationScreen` page object
+- `MainTabScreen` page object
+- `SessionStateAsserts` helpers for `login`, `verification`, `mainApp`
+- `TestUserFactory` with deterministic unique users
+
+Use stable selectors first:
+- Accessibility IDs over title text.
+- Support both auth/onboarding verification IDs only if product can route to either screen.
+
+## Suggested New-Arch Test Cases (One-to-One Replacement)
+
+### A. `Registration_HappyPath_CompletesVerification_ThenCanLogout`
+Covers legacy test07.
+
+Given:
+- Fresh launch, logged out.
+
+When:
+- Register with valid user.
+- Verify with valid code.
+- Logout from profile/main app.
+
+Then:
+- Verification gate appears after register.
+- Main app appears only after successful verify.
+- Logout returns to login root.
+
+### B. `Registration_InvalidVerifyCode_ShowsError_StaysUnverified`
+Covers legacy test09.
+
+Given:
+- User registered and on verification screen.
+
+When:
+- Submit invalid verification code.
+
+Then:
+- Error banner/message visible.
+- Verification screen remains active.
+- Main app root not accessible.
+
+### C. `Registration_IncompleteVerifyCode_DoesNotVerify`
+Covers legacy test10.
+
+Given:
+- User on verification screen.
+
+When:
+- Enter fewer than required digits.
+- Attempt verify (or assert button disabled).
+
+Then:
+- Verification completion does not occur.
+- User remains blocked from main app.
+
+### D. `Registration_UnverifiedUser_RelaunchStillBlockedFromMain`
+Covers legacy test11.
+
+Given:
+- User registered but not verified.
+
+When:
+- Terminate and relaunch app.
+
+Then:
+- User is on verification gate (or login if session invalidated).
+- User is never placed directly in main app state.
+
+### E. `Registration_VerificationScreenLogout_ReturnsToLogin`
+Covers legacy test12.
+
+Given:
+- User at verification gate.
+
+When:
+- Tap logout on verification screen.
+
+Then:
+- Verification state exits.
+- Login root becomes active and interactive.
+
+## Data + Environment Strategy for Rebuild
+- Use API mode/environment that is stable for registration + verification in CI and local runs.
+- Seed/fixture verification code contract must be explicit (example: fixed debug code).
+- Generate unique username/email per test to avoid collisions.
+- If keyboard autofill overlays are flaky, centralize handling in input helper (not per-test).
+
+## Migration Notes
+- Keep legacy tests disabled/removed only after each replacement test is green.
+- Track replacement mapping in PR description:
+  - `old test -> new test`
+- Preserve negative assertions ("must NOT access main app before verify").
+
+## Open Risks To Resolve During Rebuild
+- Registration password entry flakiness from iOS strong-password UI overlays.
+- Potential mismatch between onboarding verification screen IDs and auth verification screen IDs.
+- Environment-dependent backend behavior (local/dev) affecting registration transition.