Close all 25 codex audit findings across KMP, iOS, and Android

Remediate all P0-S priority findings from cross-platform architecture audit:
- Harden token storage with EncryptedSharedPreferences (Android) and Keychain (iOS)
- Add SSL pinning and certificate validation to API clients
- Fix subscription cache race conditions and add thread-safe access
- Add input validation for document uploads and file type restrictions
- Refactor DocumentApi to use proper multipart upload flow
- Add rate limiting awareness and retry logic to API layer
- Harden subscription tier enforcement in SubscriptionHelper
- Add biometric prompt for sensitive actions (Login, Onboarding)
- Fix notification permission handling and device registration
- Add UI test infrastructure (page objects, fixtures, smoke tests)
- Add CI workflow for mobile builds

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iosApp/CaseraUITests/CriticalPath/SmokeTests.swift

@@ -0,0 +1,120 @@
+import XCTest
+
+/// Smoke tests - run on every PR. Must complete in <2 minutes.
+///
+/// Tests that the app launches successfully, the auth screen renders correctly,
+/// and core navigation is functional. These are the minimum-viability tests
+/// that must pass before any PR can merge.
+final class SmokeTests: XCTestCase {
+    var app: XCUIApplication!
+
+    override func setUp() {
+        super.setUp()
+        continueAfterFailure = false
+        app = TestLaunchConfig.launchApp()
+    }
+
+    override func tearDown() {
+        app = nil
+        super.tearDown()
+    }
+
+    // MARK: - App Launch
+
+    func testAppLaunches() {
+        // App should show either login screen or main tab view
+        let loginScreen = LoginScreen(app: app)
+        let mainScreen = MainTabScreen(app: app)
+
+        let loginAppeared = loginScreen.emailField.waitForExistence(timeout: 15)
+        let mainAppeared = mainScreen.residencesTab.waitForExistence(timeout: 5)
+
+        XCTAssertTrue(loginAppeared || mainAppeared, "App should show login or main screen on launch")
+    }
+
+    // MARK: - Login Screen Elements
+
+    func testLoginScreenElements() {
+        let login = LoginScreen(app: app)
+        guard login.emailField.waitForExistence(timeout: 15) else {
+            // Already logged in, skip this test
+            return
+        }
+
+        XCTAssertTrue(login.emailField.exists, "Email field should exist")
+        XCTAssertTrue(login.passwordField.exists, "Password field should exist")
+        XCTAssertTrue(login.loginButton.exists, "Login button should exist")
+    }
+
+    // MARK: - Login Flow
+
+    func testLoginWithExistingCredentials() {
+        let login = LoginScreen(app: app)
+        guard login.emailField.waitForExistence(timeout: 15) else {
+            // Already on main screen - verify tabs
+            let main = MainTabScreen(app: app)
+            XCTAssertTrue(main.isDisplayed, "Main tabs should be visible")
+            return
+        }
+
+        // Login with the known test user
+        let user = TestFixtures.TestUser.existing
+        login.login(email: user.email, password: user.password)
+
+        let main = MainTabScreen(app: app)
+        XCTAssertTrue(main.residencesTab.waitForExistence(timeout: 15), "Should navigate to main screen after login")
+    }
+
+    // MARK: - Tab Navigation
+
+    func testMainTabsExistAfterLogin() {
+        let login = LoginScreen(app: app)
+        if login.emailField.waitForExistence(timeout: 15) {
+            // Need to login first
+            let user = TestFixtures.TestUser.existing
+            login.login(email: user.email, password: user.password)
+        }
+
+        let main = MainTabScreen(app: app)
+        guard main.residencesTab.waitForExistence(timeout: 15) else {
+            XCTFail("Main screen did not appear")
+            return
+        }
+
+        XCTAssertTrue(main.residencesTab.exists, "Residences tab should exist")
+        XCTAssertTrue(main.tasksTab.exists, "Tasks tab should exist")
+        XCTAssertTrue(main.contractorsTab.exists, "Contractors tab should exist")
+        XCTAssertTrue(main.documentsTab.exists, "Documents tab should exist")
+        XCTAssertTrue(main.profileTab.exists, "Profile tab should exist")
+    }
+
+    func testTabNavigation() {
+        let login = LoginScreen(app: app)
+        if login.emailField.waitForExistence(timeout: 15) {
+            let user = TestFixtures.TestUser.existing
+            login.login(email: user.email, password: user.password)
+        }
+
+        let main = MainTabScreen(app: app)
+        guard main.residencesTab.waitForExistence(timeout: 15) else {
+            XCTFail("Main screen did not appear")
+            return
+        }
+
+        // Navigate through each tab and verify selection
+        main.goToTasks()
+        XCTAssertTrue(main.tasksTab.isSelected, "Tasks tab should be selected")
+
+        main.goToContractors()
+        XCTAssertTrue(main.contractorsTab.isSelected, "Contractors tab should be selected")
+
+        main.goToDocuments()
+        XCTAssertTrue(main.documentsTab.isSelected, "Documents tab should be selected")
+
+        main.goToProfile()
+        XCTAssertTrue(main.profileTab.isSelected, "Profile tab should be selected")
+
+        main.goToResidences()
+        XCTAssertTrue(main.residencesTab.isSelected, "Residences tab should be selected")
+    }
+}

iosApp/CaseraUITests/Fixtures/TestFixtures.swift

@@ -0,0 +1,120 @@
+import Foundation
+
+/// Reusable test data builders for UI tests.
+///
+/// Each fixture generates unique names using random numbers or UUIDs
+/// to ensure test isolation and prevent cross-test interference.
+enum TestFixtures {
+
+    // MARK: - Users
+
+    struct TestUser {
+        let firstName: String
+        let lastName: String
+        let email: String
+        let password: String
+
+        /// Standard test user with unique email.
+        static let standard = TestUser(
+            firstName: "Test",
+            lastName: "User",
+            email: "uitest_\(UUID().uuidString.prefix(8))@test.com",
+            password: "TestPassword123!"
+        )
+
+        /// Secondary test user for multi-user scenarios.
+        static let secondary = TestUser(
+            firstName: "Second",
+            lastName: "Tester",
+            email: "uitest2_\(UUID().uuidString.prefix(8))@test.com",
+            password: "TestPassword456!"
+        )
+
+        /// Pre-existing test user with known credentials (must exist on backend).
+        static let existing = TestUser(
+            firstName: "Test",
+            lastName: "User",
+            email: "testuser",
+            password: "TestPass123!"
+        )
+    }
+
+    // MARK: - Residences
+
+    struct TestResidence {
+        let name: String
+        let address: String
+        let type: String
+
+        static let house = TestResidence(
+            name: "Test House \(Int.random(in: 1000...9999))",
+            address: "123 Test St",
+            type: "House"
+        )
+
+        static let apartment = TestResidence(
+            name: "Test Apt \(Int.random(in: 1000...9999))",
+            address: "456 Mock Ave",
+            type: "Apartment"
+        )
+    }
+
+    // MARK: - Tasks
+
+    struct TestTask {
+        let title: String
+        let description: String
+        let priority: String
+        let category: String
+
+        static let basic = TestTask(
+            title: "Test Task \(Int.random(in: 1000...9999))",
+            description: "A test task",
+            priority: "Medium",
+            category: "Cleaning"
+        )
+
+        static let urgent = TestTask(
+            title: "Urgent Task \(Int.random(in: 1000...9999))",
+            description: "An urgent task",
+            priority: "High",
+            category: "Repair"
+        )
+    }
+
+    // MARK: - Documents
+
+    struct TestDocument {
+        let title: String
+        let description: String
+        let type: String
+
+        static let basic = TestDocument(
+            title: "Test Doc \(Int.random(in: 1000...9999))",
+            description: "A test document",
+            type: "Manual"
+        )
+
+        static let warranty = TestDocument(
+            title: "Test Warranty \(Int.random(in: 1000...9999))",
+            description: "A test warranty",
+            type: "Warranty"
+        )
+    }
+
+    // MARK: - Contractors
+
+    struct TestContractor {
+        let name: String
+        let phone: String
+        let email: String
+        let specialty: String
+
+        static let basic = TestContractor(
+            name: "Test Contractor \(Int.random(in: 1000...9999))",
+            phone: "555-0100",
+            email: "contractor@test.com",
+            specialty: "Plumber"
+        )
+    }
+}

iosApp/CaseraUITests/PageObjects/BaseScreen.swift

@@ -0,0 +1,73 @@
+import XCTest
+
+/// Base class for all page objects providing common waiting and assertion utilities.
+///
+/// Replaces ad-hoc `sleep()` calls with condition-based waits for reliable,
+/// non-flaky UI tests. All screen page objects should inherit from this class.
+class BaseScreen {
+    let app: XCUIApplication
+    let timeout: TimeInterval
+
+    init(app: XCUIApplication, timeout: TimeInterval = 10) {
+        self.app = app
+        self.timeout = timeout
+    }
+
+    // MARK: - Wait Helpers (replaces fixed sleeps)
+
+    /// Waits for an element to exist within the timeout period.
+    /// Fails the test with a descriptive message if the element does not appear.
+    @discardableResult
+    func waitForElement(_ element: XCUIElement, timeout: TimeInterval? = nil) -> XCUIElement {
+        let t = timeout ?? self.timeout
+        XCTAssertTrue(element.waitForExistence(timeout: t), "Element \(element) did not appear within \(t)s")
+        return element
+    }
+
+    /// Waits for an element to disappear within the timeout period.
+    /// Fails the test if the element is still present after the timeout.
+    func waitForElementToDisappear(_ element: XCUIElement, timeout: TimeInterval? = nil) {
+        let t = timeout ?? self.timeout
+        let predicate = NSPredicate(format: "exists == false")
+        let expectation = XCTNSPredicateExpectation(predicate: predicate, object: element)
+        let result = XCTWaiter().wait(for: [expectation], timeout: t)
+        XCTAssertEqual(result, .completed, "Element \(element) did not disappear within \(t)s")
+    }
+
+    /// Waits for an element to become hittable (visible and interactable).
+    /// Returns the element for chaining.
+    @discardableResult
+    func waitForHittable(_ element: XCUIElement, timeout: TimeInterval? = nil) -> XCUIElement {
+        let t = timeout ?? self.timeout
+        let predicate = NSPredicate(format: "isHittable == true")
+        let expectation = XCTNSPredicateExpectation(predicate: predicate, object: element)
+        _ = XCTWaiter().wait(for: [expectation], timeout: t)
+        return element
+    }
+
+    // MARK: - State Assertions
+
+    /// Asserts that an element with the given accessibility identifier exists.
+    func assertExists(_ identifier: String, file: StaticString = #file, line: UInt = #line) {
+        let element = app.descendants(matching: .any)[identifier]
+        XCTAssertTrue(element.waitForExistence(timeout: timeout), "Element '\(identifier)' not found", file: file, line: line)
+    }
+
+    /// Asserts that an element with the given accessibility identifier does not exist.
+    func assertNotExists(_ identifier: String, file: StaticString = #file, line: UInt = #line) {
+        let element = app.descendants(matching: .any)[identifier]
+        XCTAssertFalse(element.exists, "Element '\(identifier)' should not exist", file: file, line: line)
+    }
+
+    // MARK: - Navigation
+
+    /// Taps the first button in the navigation bar (typically the back button).
+    func tapBackButton() {
+        app.navigationBars.buttons.element(boundBy: 0).tap()
+    }
+
+    /// Subclasses must override this property to indicate whether the screen is currently displayed.
+    var isDisplayed: Bool {
+        fatalError("Subclasses must override isDisplayed")
+    }
+}

iosApp/CaseraUITests/PageObjects/LoginScreen.swift

@@ -0,0 +1,86 @@
+import XCTest
+
+/// Page object for the login screen.
+///
+/// Uses accessibility identifiers from `AccessibilityIdentifiers.Authentication`
+/// to locate elements. Provides typed actions for login flow interactions.
+class LoginScreen: BaseScreen {
+
+    // MARK: - Elements
+
+    var emailField: XCUIElement {
+        app.textFields[AccessibilityIdentifiers.Authentication.usernameField]
+    }
+
+    var passwordField: XCUIElement {
+        // Password field may be a SecureTextField or regular TextField depending on visibility toggle
+        let secure = app.secureTextFields[AccessibilityIdentifiers.Authentication.passwordField]
+        if secure.exists { return secure }
+        return app.textFields[AccessibilityIdentifiers.Authentication.passwordField]
+    }
+
+    var loginButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.loginButton]
+    }
+
+    var appleSignInButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.appleSignInButton]
+    }
+
+    var signUpButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.signUpButton]
+    }
+
+    var forgotPasswordButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.forgotPasswordButton]
+    }
+
+    var passwordVisibilityToggle: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.passwordVisibilityToggle]
+    }
+
+    var welcomeText: XCUIElement {
+        app.staticTexts["Welcome Back"]
+    }
+
+    override var isDisplayed: Bool {
+        emailField.waitForExistence(timeout: timeout)
+    }
+
+    // MARK: - Actions
+
+    /// Logs in with the provided credentials and returns a MainTabScreen.
+    /// Waits for the email field to appear before typing.
+    @discardableResult
+    func login(email: String, password: String) -> MainTabScreen {
+        waitForElement(emailField).tap()
+        emailField.typeText(email)
+
+        let pwField = passwordField
+        pwField.tap()
+        pwField.typeText(password)
+
+        loginButton.tap()
+        return MainTabScreen(app: app)
+    }
+
+    /// Taps the sign up / register link and returns a RegisterScreen.
+    @discardableResult
+    func tapSignUp() -> RegisterScreen {
+        waitForElement(signUpButton).tap()
+        return RegisterScreen(app: app)
+    }
+
+    /// Taps the forgot password link.
+    func tapForgotPassword() {
+        waitForElement(forgotPasswordButton).tap()
+    }
+
+    /// Toggles password visibility and returns whether the password is now visible.
+    @discardableResult
+    func togglePasswordVisibility() -> Bool {
+        waitForElement(passwordVisibilityToggle).tap()
+        // If a regular text field with the password identifier exists, password is visible
+        return app.textFields[AccessibilityIdentifiers.Authentication.passwordField].exists
+    }
+}

iosApp/CaseraUITests/PageObjects/MainTabScreen.swift

@@ -0,0 +1,88 @@
+import XCTest
+
+/// Page object for the main tab view that appears after login.
+///
+/// Provides navigation to each tab (Residences, Tasks, Contractors, Documents, Profile)
+/// and a logout flow. Uses predicate-based element lookup to match the existing test patterns.
+class MainTabScreen: BaseScreen {
+
+    // MARK: - Tab Elements
+
+    var residencesTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Residences'")).firstMatch
+    }
+
+    var tasksTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Tasks'")).firstMatch
+    }
+
+    var contractorsTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Contractors'")).firstMatch
+    }
+
+    var documentsTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Documents'")).firstMatch
+    }
+
+    var profileTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Profile'")).firstMatch
+    }
+
+    override var isDisplayed: Bool {
+        residencesTab.waitForExistence(timeout: timeout)
+    }
+
+    // MARK: - Navigation
+
+    @discardableResult
+    func goToResidences() -> Self {
+        waitForElement(residencesTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToTasks() -> Self {
+        waitForElement(tasksTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToContractors() -> Self {
+        waitForElement(contractorsTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToDocuments() -> Self {
+        waitForElement(documentsTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToProfile() -> Self {
+        waitForElement(profileTab).tap()
+        return self
+    }
+
+    // MARK: - Logout
+
+    /// Logs out by navigating to the Profile tab and tapping the logout button.
+    /// Handles the confirmation alert automatically.
+    func logout() {
+        goToProfile()
+
+        let logoutButton = app.buttons[AccessibilityIdentifiers.Profile.logoutButton]
+        if logoutButton.waitForExistence(timeout: 5) {
+            waitForHittable(logoutButton).tap()
+
+            // Handle confirmation alert
+            let alert = app.alerts.firstMatch
+            if alert.waitForExistence(timeout: 3) {
+                let confirmLogout = alert.buttons["Log Out"]
+                if confirmLogout.exists {
+                    confirmLogout.tap()
+                }
+            }
+        }
+    }
+}

iosApp/CaseraUITests/PageObjects/RegisterScreen.swift

@@ -0,0 +1,86 @@
+import XCTest
+
+/// Page object for the registration screen.
+///
+/// Uses accessibility identifiers from `AccessibilityIdentifiers.Authentication`
+/// to locate registration form elements and perform sign-up actions.
+class RegisterScreen: BaseScreen {
+
+    // MARK: - Elements
+
+    var usernameField: XCUIElement {
+        app.textFields[AccessibilityIdentifiers.Authentication.registerUsernameField]
+    }
+
+    var emailField: XCUIElement {
+        app.textFields[AccessibilityIdentifiers.Authentication.registerEmailField]
+    }
+
+    var passwordField: XCUIElement {
+        app.secureTextFields[AccessibilityIdentifiers.Authentication.registerPasswordField]
+    }
+
+    var confirmPasswordField: XCUIElement {
+        app.secureTextFields[AccessibilityIdentifiers.Authentication.registerConfirmPasswordField]
+    }
+
+    var registerButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.registerButton]
+    }
+
+    var cancelButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.registerCancelButton]
+    }
+
+    /// Fallback element lookup for the register/create account button using predicate
+    var registerButtonByLabel: XCUIElement {
+        app.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Register' OR label CONTAINS[c] 'Create Account'")).firstMatch
+    }
+
+    override var isDisplayed: Bool {
+        // Registration screen is visible if any of the register-specific fields exist
+        let usernameExists = usernameField.waitForExistence(timeout: timeout)
+        let emailExists = emailField.exists
+        return usernameExists || emailExists
+    }
+
+    // MARK: - Actions
+
+    /// Fills in the registration form and submits it.
+    /// Returns a MainTabScreen assuming successful registration leads to the main app.
+    @discardableResult
+    func register(username: String, email: String, password: String) -> MainTabScreen {
+        waitForElement(usernameField).tap()
+        usernameField.typeText(username)
+
+        emailField.tap()
+        emailField.typeText(email)
+
+        passwordField.tap()
+        passwordField.typeText(password)
+
+        confirmPasswordField.tap()
+        confirmPasswordField.typeText(password)
+
+        // Try accessibility identifier first, fall back to label search
+        if registerButton.exists {
+            registerButton.tap()
+        } else {
+            registerButtonByLabel.tap()
+        }
+
+        return MainTabScreen(app: app)
+    }
+
+    /// Taps cancel to return to the login screen.
+    @discardableResult
+    func tapCancel() -> LoginScreen {
+        if cancelButton.exists {
+            cancelButton.tap()
+        } else {
+            // Fall back to navigation back button
+            tapBackButton()
+        }
+        return LoginScreen(app: app)
+    }
+}

iosApp/CaseraUITests/README.md

@@ -0,0 +1,80 @@
+# 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)
+```bash
+xcodebuild test -project iosApp.xcodeproj -scheme iosApp \
+  -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17' \
+  -only-testing:CaseraUITests/SmokeTests
+```
+
+### Full Regression (nightly)
+```bash
+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`.

iosApp/CaseraUITests/TestConfiguration/TestLaunchConfig.swift

@@ -0,0 +1,64 @@
+import XCTest
+
+/// Centralized app launch configuration for UI tests.
+///
+/// Provides consistent launch arguments and environment variables across
+/// all test suites. Disables animations and sets locale to English for
+/// deterministic test behavior.
+enum TestLaunchConfig {
+
+    /// Standard launch arguments for UI test mode.
+    /// Disables animations and forces English locale.
+    static let standardArguments: [String] = [
+        "-UITEST_MODE", "1",
+        "-AppleLanguages", "(en)",
+        "-AppleLocale", "en_US",
+        "-UIAnimationsEnabled", "NO"
+    ]
+
+    /// Launch environment variables for UI tests.
+    static let standardEnvironment: [String: String] = [
+        "UITEST_MODE": "1",
+        "ANIMATIONS_DISABLED": "1"
+    ]
+
+    /// Configure and launch app with standard test settings.
+    ///
+    /// - Parameters:
+    ///   - additionalArguments: Extra launch arguments to append.
+    ///   - additionalEnvironment: Extra environment variables to merge.
+    /// - Returns: The launched `XCUIApplication` instance.
+    @discardableResult
+    static func launchApp(
+        additionalArguments: [String] = [],
+        additionalEnvironment: [String: String] = [:]
+    ) -> XCUIApplication {
+        let app = XCUIApplication()
+        app.launchArguments = standardArguments + additionalArguments
+        var env = standardEnvironment
+        additionalEnvironment.forEach { env[$0.key] = $0.value }
+        app.launchEnvironment = env
+        app.launch()
+        return app
+    }
+
+    /// Launch app pre-authenticated (skips login flow).
+    ///
+    /// Passes test credentials via launch arguments and environment so the
+    /// app can bypass the normal authentication flow during UI tests.
+    ///
+    /// - Parameters:
+    ///   - email: Test user email address.
+    ///   - token: Test authentication token.
+    /// - Returns: The launched `XCUIApplication` instance.
+    @discardableResult
+    static func launchAuthenticated(
+        email: String = "test@example.com",
+        token: String = "test-token-12345"
+    ) -> XCUIApplication {
+        return launchApp(
+            additionalArguments: ["-TEST_AUTH_EMAIL", email, "-TEST_AUTH_TOKEN", token],
+            additionalEnvironment: ["TEST_AUTH_EMAIL": email, "TEST_AUTH_TOKEN": token]
+        )
+    }
+}