Refactor iOS UI tests to blueprint architecture

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.