Test biometric authentication on mobile devices with Espresso framework
Simulate touch ID, fingerprint, and face ID authentication flows on real Android and iOS devices during your Espresso test executions.
This feature is available only under Device Cloud Pro, Device Cloud Pro + Visual Cloud, and Enterprise Pro plans. For more details, check out our pricing page.
Most mobile devices today support biometric hardware sensors to authenticate a device owner’s identity. BrowserStack enables you to test biometric authentication, such as touch ID, fingerprint sensor, and face ID, on a BrowserStack mobile device with the Espresso framework.
Supported OS and version
| OS | Version |
|---|---|
| Android | 6.0 and higher |
| iOS | 13 and higher |
- Native apps & apps built with cross platform frameworks such as React Native, Flutter, etc. are supported.
- However, apps using code obfuscation tools such as Proguard are not supported.
Effective December 30, 2024, we have enhanced the functioning of the biometric authentication feature to support testing scenarios around failing authentication multiple times. To test such scenarios, we recommend uploading your apps again.
Enable biometric authentication
Use the BrowserStack parameter enableBiometric and set it to true in the REST API request to enable biometric authentication for your Espresso test session.
This ensures your app undergoes Sensor Instrumentation, a process that supports your app’s interaction with biometric mobile sensors on BrowserStack real devices.
Example request:
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/espresso/v2/build" \
-d '{
"enableBiometric": "true",
"devices": ["Samsung Galaxy S8-7.0"],
"app": "bs://f5L3azt9pLzE995f49376eb1fa3c284dc321f8d",
"testSuite": "bs://6eb1fa3c284ddbe9971b2d1aee0d52943b9c081"}' \
-H "Content-Type: application/json"
Test your app using biometric authentication
Prerequisite: Enable biometric authentication for your app.
To test your app, follow these steps:
- In your app, trigger the biometric authentication workflow.
- To interact with the Biometric Authentication prompt, write test scripts that click Pass, Fail, or Cancel to test authentication success or failure scenarios. BrowserStack App Automate closely mimics the biometric authentication behavior on real devices. Based on your platform, refer to this table to understand the behavior:
| Scenario | Action | Behavior |
|---|---|---|
| Pass biometric authentication | To pass biometric authentication, click Pass on the pop-up. | The biometric authentication is passed and the app behaves as designed. |
| Fail biometric authentication | On real Android devices, biometric authentication fails after five incorrect or unsuccessful attempts. To replicate this on BrowserStack Android devices, click Fail five times to fail biometric authentication. | The biometric authentication is considered failed. The exact behavior depends on whether you have a fallback defined in your app. See Fallback behavior after failed biometric authentication. |
| Cancel biometric authentication | To cancel biometric authentication, click Cancel on the pop-up. | When you click Cancel on BrowserStack devices, biometric authentication is cancelled and the BIOMETRIC_ERROR_USER_CANCELED error code is sent. If you have defined custom logic for cancellation after a certain number of failures, biometric authentication is cancelled and the BIOMETRIC_ERROR_CANCELED error code is sent. |
Fallback behavior after failed biometric authentication
After biometric authentication fails, the behavior depends on whether you have a fallback defined in your app:
- If you do not have a fallback defined, you see the error code
ERROR_LOCKOUT. Also, you do not experience the 30-second wait period like on real Android devices. - If you have a fallback defined in your app, BrowserStack App Automate displays another pop-up to simulate the device passcode. You can close this pop-up by clicking either Pass or Cancel.

On real devices running Android above version 15, the device locks itself after five failures. On BrowserStack devices, biometric authentication is directly cancelled with the ERROR_LOCKOUT error code in such cases.
Similarly, for devices running Android versions lower than 10, the device passcode screen is not displayed because Android does not offer a default fallback mechanism.

| Scenario | Action | Behavior |
|---|---|---|
| Pass biometric authentication | To pass biometric authentication, click Pass on the pop-up. | The biometric authentication is passed and the app behaves as designed. |
| Fail biometric authentication | To fail biometric authentication, click Fail on the pop-up. | Biometric authentication fails, and the app behaves as designed. |
| Cancel biometric authentication | To cancel biometric authentication, click Cancel on the pop-up. | The biometric authentication is cancelled and the app behaves as designed. |

On iOS, if the Biometric Authentication prompt does not show up and the test passes automatically, contact our Support team.
FAQs
How does biometric authentication work on BrowserStack mobile devices?
BrowserStack supports an app’s interaction with different mobile sensors such as biometric using Sensor Instrumentation. Sensor Instrumentation is the process in which, if biometric is enabled for the session, BrowserStack injects its biometric code module into the app, which mocks or overrides the Biometric APIs used by the app.
What Biometric APIs are supported by the BrowserStack Biometric feature?
The BrowserStack Biometric feature works only if the app uses one of the following supported Biometric APIs. Check with your app development team for details about the Biometric APIs your app uses.
BrowserStack supports the following Biometric APIs in the Android SDK:
-
BiometricPromptAPI. For more details, check out the BiometricPrompt Google documentation. -
BiometricManagerAPI. For more details, check out the BiometricManager Google documentation. -
KeyguardManagerAPI. For more details, check out the KeyguardManager Google documentation. -
FingerprintManagerAPI. For more details, check out the FingerprintManager Google documentation.
Do you need to register biometric on the mobile device or make changes in the app code?
No. You do not need to register any biometric on the mobile device or make any changes in the app code.
Need some help?
If you have any queries, get in touch with us.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!