honeyDueKMP/iosApp/CaseraUITests/README.md

Casera iOS UI Testing Architecture

Directory Structure

CaseraUITests/
├── PageObjects/           # Screen abstractions (Page Object pattern)
│   ├── BaseScreen.swift   # Common wait/assert utilities
│   ├── LoginScreen.swift  # Login screen elements and actions
│   ├── RegisterScreen.swift
│   └── MainTabScreen.swift
├── TestConfiguration/     # Launch config, environment setup
│   └── TestLaunchConfig.swift
├── Fixtures/              # Test data builders
│   └── TestFixtures.swift
├── CriticalPath/          # Must-pass tests for CI gating
│   └── SmokeTests.swift   # Fast smoke suite (<2 min)
├── Suite0-10_*.swift      # Existing comprehensive test suites
├── UITestHelpers.swift    # Legacy shared helpers
├── AccessibilityIdentifiers.swift # UI element IDs
└── README.md              # This file

Test Suites

Suite	Purpose	CI Gate	Target Time
SmokeTests	App launches, auth, navigation	Every PR	<2 min
Suite0-2	Onboarding, registration, auth	Nightly	<5 min
Suite3-8	Feature CRUD (residence, task, etc)	Nightly	<15 min
Suite9-10	E2E integration	Weekly	<30 min

Patterns

Page Object Pattern

Every screen has a corresponding PageObject in PageObjects/. Use these instead of raw XCUIElement queries in tests. Page objects encapsulate element lookups and common actions, making tests more readable and easier to maintain when the UI changes.

Wait Helpers

NEVER use sleep() or Thread.sleep(). Use waitForElement(), waitForElementToDisappear(), or waitForHittable() from BaseScreen. These are condition-based waits that return as soon as the condition is met, making tests both faster and more reliable.

Test Data

Use TestFixtures builders for consistent, unique test data. Random numbers and UUIDs ensure test isolation so tests can run in any order without interfering with each other.

Launch Configuration

Use TestLaunchConfig.launchApp() for standard launches. Use launchAuthenticated() to skip login when the app supports test authentication bypass. The standard configuration disables animations and forces English locale.

Accessibility Identifiers

All interactive elements must have identifiers defined in AccessibilityIdentifiers.swift. Use .accessibilityIdentifier() in SwiftUI views. Page objects reference these identifiers for element lookup.

CI Configuration

Smoke Suite (every PR)

xcodebuild test -project iosApp.xcodeproj -scheme iosApp \
  -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17' \
  -only-testing:CaseraUITests/SmokeTests

Full Regression (nightly)

xcodebuild test -project iosApp.xcodeproj -scheme iosApp \
  -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17' \
  -only-testing:CaseraUITests

Flake Reduction

• Target: <2% flake rate on critical-path suite
• All waits use condition-based predicates (no fixed sleeps)
• Test data uses unique identifiers to prevent cross-test interference
• UI animations disabled via launch arguments
• Element lookups use accessibility identifiers where possible, with predicate-based fallbacks

Adding New Tests

1. If the screen does not have a page object yet, create one in PageObjects/ that extends BaseScreen.
2. Define accessibility identifiers in AccessibilityIdentifiers.swift for any new UI elements.
3. Add test data builders to TestFixtures.swift if needed.
4. Write the test in the appropriate suite file, or create a new suite if the feature is new.
5. For critical-path tests (must pass on every PR), add to CriticalPath/SmokeTests.swift.