Testing Passkey Flows in Native iOS & Android Apps

The transition to passkeys represents one of the most significant shifts in digital authentication in years. For the end-user, the experience is seamless: a login confirmed with a simple biometric scan or device PIN. However, for the developers, testers and quality assurance (QA) engineers building these experiences, particularly in native mobile applications, this surface-level simplicity masks a deep well of underlying complexity. Testing passkey flows in native apps is a demanding challenge, requiring its own dedicated playbook.

This reality imposes a "Developer Experience (DevX) Tax" on native development teams. The cost of implementing passkeys is not merely the initial coding effort but the substantial, ongoing investment required to build and maintain a sophisticated testing apparatus. This apparatus must be capable of validating interactions across a dizzying matrix of devices, operating systems and credential managers. Unlike web development, where the browser vendor absorbs much of this abstraction burden, native developers are on the front lines, dealing directly with issues like Apple's aggressive caching of apple-app-site-association (AASA) files or subtle UI differences in Samsung's implementation of an Android system prompt. This guide provides a comprehensive strategy for managing that complexity of native passkey testing into a structured, repeatable, and reliable process.

To systematically tackle the complexities of native passkey testing, a structured approach is essential. The classic testing pyramid offers a time-tested model, which can be effectively adapted to the passkey context. This model prioritizes a "shift-left" strategy, aiming to catch defects as early—and therefore as cheaply—as possible in the development lifecycle. This structured approach is fundamental for both progression testing (ensuring new passkey features work as designed) and regression testing (ensuring existing functionality, including legacy authentication, does not break). It organizes tests into three distinct layers, each with a specific purpose, scope, and cost.

The progression moves from a broad base of fast, inexpensive tests to a narrow peak of slower, more comprehensive and costly validations:

• Unit Tests: Forming the foundation of the pyramid, these tests are fast, isolated, and focused on the smallest pieces of application logic. They verify individual functions or classes in your codebase.
• Integration Tests: The middle layer verifies the interaction between different components. For passkeys, this means testing the full cryptographic WebAuhn ceremony involving your app, the OS APIs (on a simulator or emulator), and a staging backend environment.
• System / Acceptance Tests: At the apex of the pyramid, these tests validate the complete, end-to-end user journey on real, physical hardware. They are the most expensive to run but are indispensable for confirming the true user experience.

Adhering to this layered strategy is a prerequisite for comprehensive quality assurance. Unit tests are vital for ensuring your data parsing and state management logic is correct, but they will never detect an issue with Apple's AASA file caching. Integration tests on an iOS Simulator can validate the WebAuthn flow but will fail to uncover a UI bug present only in Samsung's custom One UI overlay. Only by implementing all three layers of the pyramid can a team confidently ship a robust and reliable passkey experience.

Unit tests for passkey features should focus on the "what," not the "how." The goal is to verify that your application's internal logic - the code you write - behaves correctly in response to various inputs and states, completely isolated from the underlying OS-level passkey APIs. These tests should be fast, deterministic and free of external dependencies like network calls or hardware interactions.

Key scenarios to cover with unit tests include:

• Request Formatting: Given a valid registration or authentication challenge received from the backend, does your code correctly construct the request object (ASAuthorizationPlatformPublicKeyCredentialProvider request on iOS, GetCredentialRequest on Android) that will be passed to the native SDK?
• Response Parsing: When provided with a mocked successful response object from the native SDK (e.g., an ASAuthorization object), does your parsing logic correctly extract critical data like the credential ID, raw client data and attestation object?
• State Management: If the native SDK returns a mocked error (e.g., ASAuthorizationError.canceled), does your application's state management layer (e.g., a ViewModel or Presenter) correctly update the UI state to show an error message or a fallback option?

Integration tests bridge the gap between isolated code logic and real-world execution. This is the first layer where the full WebAuthn cryptographic ceremony is tested end-to-end, involving communication between three key actors: your native app, the operating system (running on a simulator or emulator) and a live (but non-production) backend server.

The primary goal of this stage is to verify that the cryptographic handshakes - the creation and assertion of credentials - are functioning correctly. This involves the app fetching a challenge from a staging server, passing it to the OS's passkey APIs, receiving a signed response and sending that response back to the server for verification.

However, this layer is also where developers encounter the first major platform-specific hurdles, many of which are invisible in unit tests:

• AASA File Caching: A particularly notorious issue for iOS developers is the caching of the apple-app-site-association (AASA) file. This JSON file, hosted on your web domain, is what proves to iOS that your app has the authority to handle credentials for that domain. In staging or pre-production environments, Apple's Content Delivery Network (CDN) can cache this file for up to 24 hours. An incorrect or outdated AASA file is a common source of failures, and this caching behavior can leave development teams waiting a full day to verify a fix.

• Emulator and Simulator Limitations: A fundamental challenge for automated integration testing is interacting with biometric prompts. Simulators and emulators lack the physical hardware for Face ID, Touch ID, or fingerprint scans. While they provide some mechanisms to simulate these events, these often require special configuration or programmatic workarounds, which will be explored in detail in Section 4.

System testing, often performed as User Acceptance Testing (UAT), is the final and most critical validation stage. It moves beyond simulators and emulators to test the end-to-end passkey experience on a diverse fleet of physical, real-world devices. This step is non-negotiable, as it is the only way to uncover a class of bugs rooted in hardware, manufacturer-specific software modifications, and real-world environmental conditions.17

This is the testing layer that validates the true user experience and catches the subtle but critical issues that simulators cannot replicate:

• OEM-Specific UI Divergence: On Android, a passkey prompt rendered on a Google Pixel device may look and behave differently from the same prompt on a Samsung Galaxy or a OnePlus device. These Original Equipment Manufacturer (OEM) customizations can break fragile UI tests and introduce unexpected user experience flaws.

• Hardware-Specific Performance: The latency of a cryptographic operation performed by Apple's Secure Enclave can differ between an iPhone 15 and an older iPhone 11. Only testing on physical hardware can reveal performance bottlenecks that might impact the user's perception of the login speed.

• Real-World Credential Manager Interactions: Users may have third-party password managers like 1Password or Dashlane installed, which can also act as passkey providers. System testing is essential to verify how the OS-level credential manager presents these options alongside the native iCloud Keychain or Google Password Manager, and to ensure your app handles the user's choice correctly.

This stage serves as the final quality gate before release. To ensure its rigor, the process must be guided by a clear and comprehensive set of acceptance criteria—a formal "Definition of Done" that specifies exactly what a successful passkey implementation looks like.

To prevent ambiguity and ensure all stakeholders - developers, QA engineers, and product managers - share a common understanding of success, a formal set of acceptance criteria is indispensable. This "Definition of Done" transforms the abstract goal of "working passkeys" into a concrete, verifiable checklist. This checklist should be structured around the core user journeys defined by FIDO and platform providers: Registration, Authentication and Management.

These test cases validate the primary, successful paths a user will take when interacting with passkeys in your app.

• Registration Journey:

  • Test Case 1 (New User): A user without an existing account can complete the sign-up process and create a passkey for their new account in a single, streamlined flow.

  • Test Case 2 (Existing User - Passkey Append): An existing user who currently authenticates with a password (and legacy MFA) can navigate to their account settings and successfully add (or "append") a passkey to their account. This is a critical upgrade path for migrating your user base. This journey also includes testing "nudges" or prompts that encourage users to upgrade to a passkey. Verify that if a user dismisses or skips this nudge, it reappears at appropriate subsequent intervals without being overly intrusive.

• Authentication Journey:

  • Test Case 3 (On-Device Authentication): A returning user with a passkey stored on their current device (e.g., in iCloud Keychain or Google Password Manager) can successfully sign in using the device's native biometric or PIN prompt.

  • Test Case 4 (Cross-Device Authentication): A user attempting to sign in on one device (e.g., a Windows laptop) can successfully authenticate by using a passkey stored on a nearby second device (e.g., their iPhone). This flow typically involves scanning a QR code and must be tested across common platform pairings (e.g., iPhone to Windows, Android to macOS).

• Management Journey:

  • Test Case 5 (View Passkeys): A user can navigate to their account settings and see a clear list of all passkeys registered to their account, ideally with descriptive names indicating the device or manager they are associated with (e.g. "Google Password Manager").

  • Test Case 6 (Delete Passkey): A user can select a passkey from the management list and successfully "delete" it. This action revokes the public key on the server. The UI should provide clear confirmation that the passkey has been removed and can no longer be used.

  • Test Case 7 (MFA State Consistency): After a passkey is added or removed, verify the user's account settings correctly reflect their Multi-Factor Authentication (MFA) status. For example, adding a passkey might satisfy MFA requirements, while removing the last passkey might require the user to set up a different second factor.

A significant number of production bugs do not occur on the happy path but rather when a user aborts a flow midway. Testing cancellation and timeout scenarios is critical for building a resilient application. The passkey ceremony involves multiple steps where a user can cancel, and each requires a distinct handling strategy.

• Two-Stage Cancellation Flows:

  • Stage 1 (Passkey Overlay): The user initiates a passkey login and the OS presents an overlay listing available passkeys. The user then dismisses this sheet without making a selection.

    • Test Case: Verify that the app's UI gracefully returns to its previous state (e.g. the login screen). The app must not crash, freeze, or become stuck in an intermediate state.

  • Stage 2 (Biometric/PIN Prompt): The user selects a passkey and the OS presents the specific Face ID, Touch ID, fingerprint, or PIN prompt. The user then cancels this prompt.

    • Test Case: Verify that the app receives the appropriate cancellation error from the native SDK. The app should handle this error by displaying a helpful message (e.g., "Login cancelled") and providing a clear path to an alternative login method, rather than showing a generic failure message.

• Timeout Scenarios:

  • Test Case (Application Session Timeout): How does the passkey flow interact with your app's own session management? Consider a scenario where a user has already completed one factor of authentication (e.g., entering a username) and is about to use their passkey, but the app's overall session timer expires. The app should have a clear and predictable behavior, such as redirecting the user back to the start of the login flow, rather than leaving them on a non-functional screen.

A robust native client must be engineered to be resilient against backend failures and unexpected server responses. Testing these negative conditions ensures that the user experience degrades gracefully, providing clear feedback instead of silent failures or infinite loading spinners.

• Test Case (Backend Unavailability): Using network mocking tools or a configurable staging environment, simulate a server outage (e.g., an HTTP 503 Service Unavailable error) when the app requests a registration or authentication challenge. The app must handle this failure by displaying an appropriate message (e.g., "Our servers are currently unavailable. Please try again later.") and offering a retry mechanism.

• Test Case (Server-Side Deleted Passkey): This critical scenario tests for desynchronization. A user deletes a passkey from their account via the app's settings, but the passkey's private key still exists on their mobile device. When they attempt to authenticate with that passkey, the server must reject the assertion. The client app must then receive a specific error from the backend and display a highly contextual message, such as, "This passkey is no longer registered with your account. Please use a different passkey or register this device again".

• Test Case (Client-Side Deleted Passkey): The user manually deletes the passkey from their device's credential manager (e.g., iCloud Keychain settings). When they next attempt to log in to the app, the OS-level credential sheet should not appear, or it should not list the deleted passkey. The app's UI should correctly reflect that no passkeys are available for use.

Automating integration tests is a cornerstone of modern CI/CD, but passkeys present a formidable obstacle: how do you automate interactions with biometric prompts that require physical user presence? The answer lies in systematically faking these interactions, using different techniques for iOS and Android to enable tests to run unattended in a CI/CD pipeline.

The ability to effectively mock these dependencies is more than just a testing convenience; it serves as a litmus test for the application's architectural health. An application that is difficult to test in this manner is often one with tightly coupled components, where business logic is entangled with platform-specific framework calls. The process of making the app testable—by introducing abstractions and using dependency injection—naturally forces a refactoring towards a cleaner, more modular, and ultimately more maintainable architecture. Thus, a robust testing strategy is not just a QA function but a powerful driver of sound engineering practices.

Successful passkey implementation hinges on handling not just the happy paths, but the multitude of edge cases and failure modes that can arise from the complex interplay of hardware, OS settings, and user state. The following matrix consolidates these scenarios into a structured test plan. It serves as a reusable asset for QA teams, transforming a chaotic list of "what-ifs" into a systematic process for ensuring robustness. For each scenario, teams should define the setup, the test steps for both iOS and Android, and, most importantly, the expected user-facing outcome or fallback mechanism.

For enterprise applications, deploying a feature as significant as passkeys is rarely a "big-bang" event. A gradual rollout, managed by feature flags and often targeted to specific user segments via rollout tokens, is the recommended practice for mitigating risk. This phased approach requires its own layer of testing to ensure the flagging mechanism itself is working correctly.

The core of this testing is to validate that the application behaves correctly for all user cohorts defined by the rollout strategy.

• Token-Gated Path (Treatment Group): A test user account, associated with a valid rollout token, launches the app. Verify that the user is presented with the new passkey creation and authentication UI elements. Confirm that the entire passkey lifecycle (register, authenticate, revoke) functions correctly for this user.

• Non-Token Path (Control Group): A test user without a rollout token launches the app. Verify that this user sees the legacy authentication experience (e.g., password fields) and that no passkey-related UI or logic is triggered. This confirms that the feature is successfully hidden for the general population.

• Invalid or Expired Token: A test user with a token that is syntactically incorrect, expired, or has been revoked on the backend should be treated identically to a user with no token. Verify that they are directed to the legacy authentication path.

• Kill-Switch / Global Disable: Crucially, test the global "kill-switch" feature. When this flag is activated, verify that all passkey-related UI and entry points are completely removed from the application for all users and the system gracefully falls back to legacy authentication methods. This is a critical safety mechanism.

While Apple's official documentation provides a solid foundation, real-world implementation uncovers a variety of "gotchas"—subtle behaviors and limitations that can only be discovered through hands-on testing. A robust QA plan must account for these iOS-specific quirks.

• Overlay Latency with Large Keychains: The presentation of the ASAuthorizationController - the overlay modal that displays passkey options - is not instantaneous. If a user's iCloud Keychain contains a very large number of credentials (e.g., hundreds of passkeys), there can be a noticeable delay before this sheet appears. Performance tests should be conducted with test devices whose keychains have been populated with a large volume of dummy credentials to measure this presentation latency and ensure it remains within an acceptable range for a good user experience.

• AASA Caching in Staging: As mentioned previously, the 24-hour caching of the apple-app-site-association file is a major source of frustration in non-production environments. The tactical solution is to enable "Developer Mode" on all physical test devices (Settings > Privacy & Security > Developer Mode). Additionally, ensure that the AASA file URL includes the "?mode=development" parameter. This setup instructs iOS to bypass the CDN cache and fetch the AASA file directly from your domain on-demand, allowing for rapid iteration and testing of configuration changes.

• Understanding the Three Login UI Modes: iOS presents three distinct login interaction models that must all be tested. The Textfield Login (username) remains besides the Passkey Modal Overlay (ASAuthorizationController), which presents a list of passkeys and Conditional UI (CUI), which surfaces passkey suggestions directly in the keyboard's QuickType bar (ASAuthorizationSecurityKeyPublicKeyCredentialAssertionRequest) as a more seamless, embedded experience. Your test plan must validate the correct triggering and behavior of all three modes.

Passkey Textfield Login

Passkey Overlay Login

• Native-Only Auto-Append in iOS 16: A subtle platform difference exists for the "automatic passkey append" flow. On iOS 16, a user signing with legacy methods on a native app may be automatically prompted by the OS to save a passkey for that account (if this feature is implemented). This "auto-append" flow is a powerful upgrade path. However, it's critical to note in your testing that this specific automatic prompt does not exist for web applications in iOS 16, only for native apps. Verify this behavior if your user base includes significant numbers on this OS version.

• API Versioning and excludeCredentials: The ability to prevent a user from creating a duplicate passkey for the same account on the same device is crucial for clean credential management. This is achieved by passing a list of existing credential IDs in the excludeCredentials parameter of the registration request. However, this property was only introduced in iOS 17.5. Your test plan must be version-aware:

  • Test Case (iOS < 17.5): On a device running an older OS, verify that the app allows a user to create a second, duplicate passkey for their account. The backend should be prepared to handle multiple credentials per user.

  • Test Case (iOS >= 17.5): On a device running iOS 17.5 or newer, attempt a new registration for a user who already has a passkey. Provide that existing passkey's credential ID in the excludeCredentials list. Verify that the OS does not create a new key and instead presents an error or an alternative flow.

Android's open nature is both a strength and a significant testing challenge. Unlike the relatively homogenous iOS ecosystem, Android developers must contend with a wide array of devices, OS versions, and manufacturer customizations.

• OEM UI Divergence: Manufacturers like Samsung, Xiaomi and OnePlus often apply their own custom skins (e.g. One UI) on top of stock Android. This can lead to visual and behavioral differences in system components, including the bottom sheet presented by the CredentialManager. Automated UI tests that rely on specific screen coordinates or pixel-perfect screenshot comparisons are extremely brittle and likely to fail on different OEM devices. Tests should instead rely on stable identifiers like resource IDs and accessibility content descriptions to locate and interact with UI elements.

• The Two Android Login Modes: Unlike iOS, Android's native passkey implementation primarily supports two login modes. The most common is the Overlay-based Flow, where the GetCredentialRequest displays a system overlay sheet with available passkeys. The second is the traditional Textfield Login. A key distinction from the web and iOS is the current absence of a widespread, native Conditional UI equivalent that automatically suggests passkeys in the keyboard. Therefore, flows are typically explicitly user-initiated, and testing must confirm a graceful fallback to the textfield login if the user cancels the overlay or has no passkeys.

• Multi-Provider Complexity: The Android CredentialManager is designed to be a central hub that aggregates credentials from multiple sources, including Google Password Manager and third-party apps like 1Password or Dashlane. Test scenarios must include devices where multiple autofill providers are installed and enabled. The user experience of the aggregated credential picker must be validated to ensure it is clear and not confusing to the user.

• Android Version Fragmentation: The CredentialManager API and its behavior have evolved, particularly with the release of Android 14, which brought more mature passkey support. The test matrix must include devices running various OS versions, from your app's minSdkVersion up to the latest release, to ensure consistent and reliable behavior across the board.

To help teams navigate these platform differences, the following table provides a high-level comparison of key testing and implementation aspects.

Before deploying a native passkey implementation to production, teams should conduct a final pre-flight check to ensure all critical aspects have been thoroughly tested. This checklist condenses the key learnings from this guide into a scannable, actionable sign-off document.

The complexities of native passkey implementation and testing can be a significant undertaking, demanding substantial engineering resources. Corbado offers a streamlined path with pre-built, native SDKs for both iOS and Android that encapsulate the best practices and rigorous testing methodologies described in this guide.

Our SDKs are field-tested and proven in the wild, powering the native iOS and Android app authentication for major enterprises like VicRoads, which serves over five million customers. By choosing Corbado, you are adopting a solution that has already undergone the intensive testing gauntlet, including:

• Continuous Automated Testing: Our SDKs are continuously tested against new OS versions and beta releases, ensuring your passkey implementation remains robust and reliable as platforms evolve.
• Comprehensive Test Suites: The very tests detailed in this article—from core journey validation to edge-case scenarios and platform-specific gotchas—are an integral part of our SDK development and release process.

By leveraging Corbado's native SDKs, your team can bypass the most resource-intensive aspects of passkey development and testing, allowing you to focus on your core product while delivering a secure, modern, and reliable passwordless experience to your users with confidence.

Testing passkeys in native mobile applications is a formidable challenge, but it is a solvable one. The path to a successful, secure, and user-friendly implementation is not paved with ad-hoc manual checks, but with a disciplined, multi-layered testing strategy. By adopting the structure of the testing pyramid, establishing a clear "Definition of Done", preparing for a myriad of edge cases and platform-specific quirks, and automating where possible, development teams can effectively manage the inherent complexity. The comprehensive pre-flight checklist provided serves as a final guardrail, ensuring that every critical aspect is considered before launch. Ultimately, the significant investment in a robust testing process pays dividends—not just in a higher quality product, but in the confidence to ship a modern, passwordless experience that users can trust.