Build iOS biometric regression tests with simctl on a cloud Mac

The login screen had just been refactored, and the password fallback had been verified locally. Yet no one noticed that the flow could no longer continue when biometrics had not been enrolled. The issue surfaced only when the test environment reused an old simulator and the flow began hanging intermittently. Problems like this are not caused by the algorithm; they happen because the tests do not control the authentication state. A cloud Mac makes it practical to turn simulator state, authentication events, and cleanup steps into a fixed pipeline so that every commit covers the same set of branches.

Define the limits of automation first

simctl biometric can simulate enrolled and unenrolled states as well as matching and nonmatching events. It is useful for checking the UI and state transitions after an app receives a result. It cannot validate the sensor, the real enrollment process, or device-level security. The test scope should be limited to four cases:

Simulator tests prove that the app handles system results correctly, not that the biometric mechanism itself is reliable.

Acceptance testing on physical devices is still necessary, but every business branch does not need to depend on manual interaction.

Wrap system authentication behind a replaceable boundary

If a view controller creates the authentication context directly, unit tests can do little more than wait for a system prompt. A more reliable approach is to define a small protocol: the production implementation calls the system framework, while the test implementation returns deterministic results.

import LocalAuthentication

protocol BiometricAuthenticating {
    func authenticate(reason: String) async throws -> Bool
}

struct SystemBiometricAuthenticator: BiometricAuthenticating {
    func authenticate(reason: String) async throws -> Bool {
        let context = LAContext()
        var error: NSError?
        guard context.canEvaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            error: &error
        ) else {
            throw error ?? LAError(.biometryNotAvailable)
        }
        return try await context.evaluatePolicy(
            .deviceOwnerAuthenticationWithBiometrics,
            localizedReason: reason
        )
    }
}

The business layer receives only a BiometricAuthenticating. Unit tests exhaustively verify error mapping, while UI tests retain a small number of end-to-end cases to confirm that, once the system sheet appears, the success, failure, and fallback controls lead to the correct screens. This keeps the core assertions from depending on fragile full-text matching when system wording changes between releases.

Pin the simulator and drive its authentication state

First, inspect the arguments supported by the current toolchain instead of copying command syntax from a different runtime environment:

xcrun simctl help biometric
xcrun simctl list devices available

The pipeline should not use the ambiguous booted selector. When parallel jobs start devices at the same time, it can target the wrong instance. Each job should create or acquire a unique UDID and use it consistently across all commands:

set -euo pipefail

UDID="${SIMULATOR_UDID:?missing simulator udid}"

xcrun simctl boot "$UDID" 2>/dev/null || true
xcrun simctl bootstatus "$UDID" -b
xcrun simctl biometric "$UDID" unenroll
xcrun simctl biometric "$UDID" enroll

After starting the test, wait until the authentication sheet is actually ready before sending an event. A fixed two-second sleep can easily fail as system load changes. The test build can emit its own marker, such as AUTH_PROMPT_READY, immediately before triggering authentication. The outer controller can then watch a time-limited log stream and run the event command only after it sees that marker:

xcrun simctl biometric "$UDID" match face
xcrun simctl biometric "$UDID" nonmatch face

Different runtime environments may accept different biometric type arguments. The final commands should therefore follow the local help biometric output, with incompatibilities detected during environment preflight rather than halfway through a test run.

Keep test cases independent

Biometric enrollment state belongs to the simulator, not to an individual test method. An enroll left behind by one case will contaminate the next test for the unenrolled state. Give every scenario an explicit precondition and restore the state when the test finishes:

cleanup() {
  xcrun simctl biometric "$UDID" unenroll 2>/dev/null || true
  xcrun simctl shutdown "$UDID" 2>/dev/null || true
}
trap cleanup EXIT

Do not share a device set

When multiple test shards run in parallel on the same LemonVM cloud Mac, give each job its own --set directory or assign separate UDIDs in advance. Device sets, DerivedData, and result bundles should all use job-specific directories so that one job cannot erase another job’s device.

Do not assert system copy

System dialogs vary with the OS version, language, and device capabilities. UI tests should look for the system sheet, app-owned controls, and the final business state instead of asserting the system message word for word. Verify precise error-type mapping in unit tests that use the protocol test double.

Capture failure evidence and define an acceptance checklist

On failure, preserve at least the test result bundle, app logs, target UDID, OS version, simulator model, and enrollment state at the start of the case. A single failure screenshot is rarely enough to determine whether the event was sent too early, the wrong device was selected, or the app failed to consume the callback.

Use the following checklist before accepting a change:

• The authentication implementation is injectable, and the business layer does not depend directly on the system context.
• The success, rejection, unenrolled, and unavailable paths all have deterministic assertions.
• Every parallel job owns a separate UDID and does not use the global booted selector.
• An observable readiness marker and timeout are in place before events are sent.
• Every case sets the enrollment state explicitly and runs cleanup on exit.
• Failure artifacts include the result bundle, logs, and simulator details.
• The release process still includes minimal acceptance testing on a physical device.

The value of this structure is not that it runs a few more commands. It turns authentication state from an invisible assumption into a test input. Once the input, device, and timing can all be recorded, biometric regression testing becomes a repeatable engineering process instead of an occasional manual check.

Frequently asked questions