honeyDueKMP/iosApp/HoneyDueUITests/Framework/AuthenticatedUITestCase.swift

import XCTest

/// Base class for all tests that require a logged-in user.
class AuthenticatedUITestCase: BaseUITestCase {

    // MARK: - Configuration (override in subclasses)

    var testCredentials: (username: String, password: String) {
        ("testuser", "TestPass123!")
    }

    var needsAPISession: Bool { false }

    var apiCredentials: (username: String, password: String) {
        ("admin", "Test1234")
    }

    // MARK: - API Session

    private(set) var session: TestSession!
    private(set) var cleaner: TestDataCleaner!

    // MARK: - Lifecycle

    override class func setUp() {
        super.setUp()
        guard TestAccountAPIClient.isBackendReachable() else { return }
        // Ensure both known test accounts exist (covers all subclass credential overrides)
        if TestAccountAPIClient.login(username: "testuser", password: "TestPass123!") == nil {
            _ = TestAccountAPIClient.createVerifiedAccount(username: "testuser", email: "testuser@honeydue.com", password: "TestPass123!")
        }
        if TestAccountAPIClient.login(username: "admin", password: "Test1234") == nil {
            _ = TestAccountAPIClient.createVerifiedAccount(username: "admin", email: "admin@honeydue.com", password: "Test1234")
        }
    }

    /// When `true`, every test in the suite forces a logout → login cycle
    /// in `setUp`, guaranteeing a freshly-issued auth token on each run.
    ///
    /// Default is `false`: tests reuse the existing logged-in session
    /// from the previous test in the same suite — much faster (one login
    /// per suite, not one per test) and resilient to suites where the
    /// current screen has no logout affordance (`UITestHelpers.ensureLoggedOut`
    /// times out → the test fails before its body runs).
    ///
    /// Override to `true` in suites that have observed transient
    /// `Invalid token` 401s on POST/PATCH while reads continue to work.
    /// The recipe was added after a 2026-05 incident where the API
    /// container was rebuilt mid-suite and in-memory tokens went stale.
    /// In normal CI runs against a stable API + freshly-erased simulator,
    /// session reuse is the correct default.
    var forceFreshLoginPerTest: Bool { false }

    override func setUpWithError() throws {
        guard TestAccountAPIClient.isBackendReachable() else {
            throw XCTSkip("Backend not reachable at \(TestAccountAPIClient.baseURL)")
        }

        try super.setUpWithError()

        let tabBar = app.tabBars.firstMatch
        let alreadyLoggedIn = tabBar.waitForExistence(timeout: defaultTimeout)

        // Force-fresh path: log out (if needed) and re-authenticate per
        // test so every test starts with a freshly-issued JWT. Catches
        // server-side token invalidation that would otherwise surface
        // mid-suite as opaque 401s on the first mutation call.
        if forceFreshLoginPerTest {
            if alreadyLoggedIn {
                UITestHelpers.ensureLoggedOut(app: app)
            } else {
                UITestHelpers.ensureLoggedOut(app: app)
            }
            loginToMainApp()
        } else if !alreadyLoggedIn {
            // Legacy session-reuse path: only log in when not already in.
            UITestHelpers.ensureLoggedOut(app: app)
            loginToMainApp()
        }
        // (When `forceFreshLoginPerTest == false` AND we're already
        // logged in, fall through with the existing session.)

        if needsAPISession {
            guard let apiSession = TestAccountManager.loginSeededAccount(
                username: apiCredentials.username,
                password: apiCredentials.password
            ) else {
                XCTFail("Could not login API account '\(apiCredentials.username)'")
                return
            }
            session = apiSession
            cleaner = TestDataCleaner(token: apiSession.token)
        }
    }

    override func tearDownWithError() throws {
        cleaner?.cleanAll()
        try super.tearDownWithError()
    }

    // MARK: - Login

    func loginToMainApp() {
        let creds = testCredentials

        UITestHelpers.ensureOnLoginScreen(app: app)

        let login = LoginScreenObject(app: app)
        login.waitForLoad(timeout: loginTimeout)
        login.enterUsername(creds.username)
        login.enterPassword(creds.password)

        let loginButton = app.buttons[AccessibilityIdentifiers.Authentication.loginButton]
        loginButton.waitForExistenceOrFail(timeout: defaultTimeout)
        loginButton.tap()

        waitForMainApp()
    }

    func waitForMainApp() {
        let tabBar = app.tabBars.firstMatch
        let verification = VerificationScreen(app: app)

        let deadline = Date().addingTimeInterval(loginTimeout)
        while Date() < deadline {
            if tabBar.exists { break }
            if verification.codeField.exists {
                verification.enterCode(TestAccountAPIClient.debugVerificationCode)
                verification.submitCode()
                _ = tabBar.waitForExistence(timeout: loginTimeout)
                break
            }
            RunLoop.current.run(until: Date().addingTimeInterval(0.5))
        }

        XCTAssertTrue(tabBar.exists, "Expected tab bar after login with '\(testCredentials.username)'")
    }

    // MARK: - Tab Navigation

    func navigateToTab(_ label: String) {
        let tabBar = app.tabBars.firstMatch
        tabBar.waitForExistenceOrFail(timeout: navigationTimeout)

        let tab = tabBar.buttons.containing(
            NSPredicate(format: "label CONTAINS[c] %@", label)
        ).firstMatch
        tab.waitForExistenceOrFail(timeout: navigationTimeout)
        tab.tap()

        // Verify navigation happened — wait for isSelected (best effort, won't fail)
        // sidebarAdaptable tabs sometimes need a moment
        let selected = NSPredicate(format: "isSelected == true")
        let exp = XCTNSPredicateExpectation(predicate: selected, object: tab)
        let result = XCTWaiter().wait(for: [exp], timeout: navigationTimeout)

        // If first tap didn't register, tap again
        if result != .completed {
            tab.tap()
            _ = XCTWaiter().wait(for: [XCTNSPredicateExpectation(predicate: selected, object: tab)], timeout: navigationTimeout)
        }
    }

    func navigateToResidences()  { navigateToTab("Residences") }
    func navigateToTasks()       { navigateToTab("Tasks") }
    func navigateToContractors() { navigateToTab("Contractors") }
    func navigateToDocuments()   { navigateToTab("Doc") }
    func navigateToProfile()     { navigateToTab("Profile") }

    // MARK: - Pull to Refresh

    func pullToRefresh() {
        let scrollable = app.collectionViews.firstMatch.exists
            ? app.collectionViews.firstMatch
            : app.scrollViews.firstMatch
        guard scrollable.waitForExistence(timeout: defaultTimeout) else { return }

        let start = scrollable.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.15))
        let end = scrollable.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.85))
        start.press(forDuration: 0.3, thenDragTo: end)

        _ = app.activityIndicators.firstMatch.waitForNonExistence(timeout: navigationTimeout)
    }

    func pullToRefreshUntilVisible(_ element: XCUIElement, maxRetries: Int = 3) {
        for _ in 0..<maxRetries {
            if element.waitForExistence(timeout: defaultTimeout) { return }
            pullToRefresh()
        }
    }

    /// Tap the refresh button on the Tasks/Kanban screen (no pull-to-refresh on kanban).
    func refreshTasks() {
        let refreshButton = app.buttons[AccessibilityIdentifiers.Task.refreshButton]
        if refreshButton.waitForExistence(timeout: defaultTimeout) && refreshButton.isEnabled {
            refreshButton.tap()
            _ = app.activityIndicators.firstMatch.waitForNonExistence(timeout: navigationTimeout)
        }
    }

    // MARK: - Preconditions (Rule 17: validate assumptions via API before tests run)

    /// Ensure at least one residence exists for the current user.
    /// Required precondition for: task creation, document creation.
    func ensureResidenceExists() {
        guard let token = session?.token else { return }
        if let residences = TestAccountAPIClient.listResidences(token: token),
           !residences.isEmpty { return }
        // No residence — create one via API
        let _ = TestDataSeeder.createResidence(token: token, name: "Precondition Home \(Int(Date().timeIntervalSince1970))")
    }

    /// Ensure the current user has a specific minimum of residences.
    func ensureResidenceCount(minimum: Int) {
        guard let token = session?.token else { return }
        let existing = TestAccountAPIClient.listResidences(token: token) ?? []
        for i in existing.count..<minimum {
            let _ = TestDataSeeder.createResidence(token: token, name: "Precondition Home \(i) \(Int(Date().timeIntervalSince1970))")
        }
    }

    // MARK: - Shared Helpers

    /// Fill a text field by accessibility identifier. The ONE way to type into fields.
    func fillTextField(identifier: String, text: String, file: StaticString = #filePath, line: UInt = #line) {
        let field = app.textFields[identifier].firstMatch
        field.waitForExistenceOrFail(timeout: defaultTimeout, file: file, line: line)
        field.focusAndType(text, app: app, file: file, line: line)
    }

    /// Dismiss keyboard using the Return key or toolbar Done button.
    func dismissKeyboard() {
        KeyboardDismisser.dismiss(app: app, timeout: defaultTimeout)
    }
}

/// Robust keyboard dismissal. Numeric keyboards (postal, year, cost) often lack
/// Return/Done keys, so we fall back through swipe-down and tap-above strategies.
enum KeyboardDismisser {
    static func dismiss(app: XCUIApplication, timeout: TimeInterval = 5) {
        let keyboard = app.keyboards.firstMatch
        guard keyboard.exists else { return }

        // 1. Prefer the keyboard-toolbar "Done" button (SwiftUI ToolbarItemGroup
        //    on .keyboard placement). Tapping it sets focusedField = nil, which
        //    reliably commits TextField bindings before the keyboard dismisses.
        //    We look outside app.keyboards.buttons because the toolbar is
        //    rendered on the keyboard layer, not inside it.
        if keyboard.exists {
            let toolbarDone = app.toolbars.buttons["Done"]
            if toolbarDone.exists && toolbarDone.isHittable {
                toolbarDone.tap()
                if keyboard.waitForNonExistence(timeout: 1.0) { return }
            }
        }

        // 2. Tap above the keyboard. This dismisses via focus-loss on the
        //    underlying UITextField, which propagates the typed text to the
        //    SwiftUI binding. Works for numeric keyboards too.
        if keyboard.exists {
            app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.2)).tap()
            if keyboard.waitForNonExistence(timeout: 1.0) { return }
        }

        // 3. Last resort: keyboard Return/Done key. Avoid this first — on
        //    SwiftUI text fields the Return keystroke can dismiss the keyboard
        //    before the binding catches up with the final typed characters.
        for keyName in ["Return", "return", "Done", "done"] {
            let button = app.keyboards.buttons[keyName]
            if button.exists && button.isHittable {
                button.tap()
                if keyboard.waitForNonExistence(timeout: 1.0) { return }
            }
        }

        _ = keyboard.waitForNonExistence(timeout: timeout)
    }
}