Skip to main content
Transform your testing process with: Real Device Features, Company-wide Licences, & App Percy
No Result Found
Get your setup working faster. Join our Discord for optimisation tips from elite testers. Join our DiscordJoin our Discord

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:

  1. In your app, trigger the biometric authentication workflow.
  2. 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.

Device Passcode Pass or Fail

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.

Authentication Pass or Fail

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.

Authentication Pass or Fail

On iOS, if the Biometric Authentication prompt does not show up and the test passes automatically, contact our Support team.

FAQs

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.

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:

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





Thank you for your valuable feedback

Is this page helping you?

Yes
No

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!

Talk to an Expert
Download Copy Check Circle