Test biometric authentication on BrowserStack mobile devices

The majority of mobile devices today support biometric hardware sensors to authenticate 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 Espresso framework.

Supported OS and version

Enabling Biometric Authentication

Use BrowserStack parameter enableBiometric and set it to true in the REST API request to enable Biometric Authentication functionality for your Espresso test session.

This ensures your app undergoes Sensor Instrumentation, which is a process that supports app’s interaction with biometric mobile sensors on BrowserStack real devices.

Example request

curl -u "username:accesskey" \
-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 setting for your app.

To test your app:

1. In your app, trigger the biometric authentication workflow.
2. To interact with the Biometric Authentication prompt, you can write test scripts that click on Pass, Fail, or Cancel to test authentication success or failure scenarios. BrowserStack App Live attempts to closely mimic the biometric authentication behaviour on real devices. Based on your platform, refer to this table to understand the behaviour:

• Android
• iOS

Scenario	Action	Behaviour
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/unsuccessful attempts. Hence, on BrowserStack Android devices, click Fail five times to actually fail biometric authentication.	The biometric authentication is considered failed and - if you do not have a fallback defined, you should see the error code, ERROR_LOCKOUT. Also, you will not experience the 30-sec wait period like on real Android devices. - if you have a fallback defined in your app, BrowserStack App Live displays another pop-up to simulate device passcode. This pop-up can be closed by clicking either Pass or Cancel. Note: On real devices running Android above version 15, the device locks itself after five failures. However, in such cases, on BrowserStack devices, biometric authentication will directly get cancelled with the ERROR_LOCKOUT error code. Similarly, for devices running Android versions lower than 10, since Android does not offer a default fallback mechanism, the device passcode screen is not displayed.
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.

Scenario	Action	Behaviour
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.	The biometric authentication is failed 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.

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

Frequently Asked Questions (FAQs)

1. 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, we inject BrowserStack’s biometric code module into the app, which mocks or overrides Biometric APIs used by the app.

2. What Biometric APIs are supported by BrowserStack Biometric feature?

The BrowserStack Biometric feature works only if the app uses any of the following supported Biometric APIs. Check with your app development team for details about the Biometric APIs your app uses.

We currently support the following Biometric APIs in Android SDK :

• BiometricPrompt API. For more details, check out BiometricPrompt Google documentation.
• BiometricManager API. For more details, check out BiometricManager Google documentation.
• KeyguardManager API. For more details, check out KeyguardManager Google documentation.
• FingerprintManager API. For more details, check out FingerprintManager Google documentation.

3. Do we need to register biometric on the mobile device or make any 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, please get in touch with us.