Skip to main content

Biometric Authentication

With Sauce Labs Biometric Authentication, you can simulate biometric authentication events within your app during live and automated testing. This feature allows you to test the app's ability to recognize and respond to biometric events, without physically testing it on a device. Biometric Authentication refers to the use of physical characteristics, such as fingerprint (Touch ID) or facial recognition (Face ID) to verify the user's identity.

Sauce Labs provides biometrics interception for our customers to:

  • Access test flows that are dependent on biometrics support, such as a mandatory security layer.
  • Verify that an app responds as expected to biometrics settings (e.g., enabled/disabled and successful/unsuccessful).
caution

Make sure you have a debuggable AND non-obfuscated version of your application uploaded to Mobile App Storage. Biometrics test support in Sauce Labs is not intended to test actual biometrics values for authentication.

What You'll Need

Key Specs

Biometric Authentication is available for testing on all Sauce Labs Android and iOS real devices.

SupportedNot Supported
**Device Type **
Android real devices
iOS real devices
Android Emulators
iOS Simulators
App Type
Flutter(iOS/Android)
React Native(iOS/Android)
Cordova (iOS/Android)
Framework Type
Appium
Espresso (Android)
XCUITest (iOS)
Not Supported
  • Mobile browsers and pre-installed system apps.
  • Cross-platform development frameworks like Flutter, React Native, and Cordova (libraries and frameworks are not supported).
  • Ephemeral apps.

Android Biometrics

For Android devices, there are multiple ways to configure biometrics. From API 28 and above we support the following:

From API 23 to 28 we support the following:

iOS Biometrics

For iOS devices, biometrics can be configured with different outputs. We support the following instance methods:

Live Testing

Real Devices Only

To use biometric interception in a live mobile app test, you must ensure that the functionality is enabled for your app both through Sauce Labs AND through your app before you can mock the result as passing or failing.

  1. In Sauce Labs, click LIVE and then click Mobile App.
  2. On the App Selection page, hover over the test and then click Settings. Mobile app settings navigation
  3. On the Settings page, ensure that Biometrics Interception is enabled and then return to the App Selection page.
    Biometrics Interception - Enabled
  4. On the App Selection test page, hover over the test and then click Choose Device. Image Injection - Choose Device
  5. On the device selection page, hover over a device and then click Launch. Image Injection - Launch Biometric toolbar icons
  6. In the live test window, in the right toolbar, click More Device Options and then click Biometric Authentication.
    Biometric toolbar icons
  7. In the Biometric Authentication window, click Pass to imitate successful authentication or click Fail to imitate an unsuccessful authentication.
    Biometric Authentication

Automated Testing

Real Devices

To enable fingerprint and facial recognition on iOS and Android real devices:

  1. Add the allowTouchIdEnroll capability to your test configuration and set it to true.

    note

    Setting allowTouchIdEnroll does not update your app's biometric interception setting in Sauce Labs. It only sets the capability for the test in the event that the app setting in Sauce Labs is different from the test script capability.

    • If biometric interception is ENABLED for the app in Sauce Labs, setting allowTouchIdEnroll=true or omitting it will have no effect, but setting allowTouchIdEnroll=false will disable the enrollment for the test, overriding the app setting.
    • The opposite is true if biometric interception is DISABLED for the app in Sauce Labs.
    JavaScript iOS Capabilities Example
    loading...
  2. Use the following commands to trigger a successful or failed authentication in response to a biometric prompt:

    • driver.execute('sauce:biometrics-authenticate=true'); passes a successful authentication to the prompt.
    • driver.execute('sauce:biometrics-authenticate=false'); passes a failed authentication to the prompt.
  3. Sauce Labs intercepts this command to trigger an authentication response prior to engaging Appium, which is why the result is not captured in the Appium logs.

    The following sample test script shows the selectors for Android and iOS, as well as the command to execute the authentication.

    JS-Demo Biometrics Test Sample
    loading...

iOS Simulators

Testing biometric interception on Sauce Labs iOS Simulators or on your local machine involves writing your script to ensure biometrics is enabled for both the device and the app, and then simulating either a successful or failed authentication to ensure that the expected behavior results.

  1. In your test script, check the device setting for biometrics, as shown in the prepareBiometrics function in our demo script:
    WebdriverIO Biometrics Check Sample
    loading...
    Setting allowTouchIdEnroll capability is optional

    You can set the desired capability allowTouchIdEnroll to true to enable enrollment by default for your app, but if you are checking the enrollment in your script anyway, this is not required.

  2. If biometrics is disabled, call the driver.toggleEnrollTouchId(true) method to enable it.
    WebdriverIO Toggle Biometrics Sample
    loading...
  3. Now that biometrics is enabled for the device, make sure it is also enabled for the app.
    WebdriverIO Enable Biometrics in App
    loading...
  4. Wait for the login screen to appear, then call the submitBiometrics(true) method to simulate a successful biometric authentication.
    WebdriverIO Submit Bio Auth Sample
    loading...
  5. Run your test. Call:
    • Local environment: npm run test.local.ios.simulator
    • Sauce Labs US Data Center: npm run test.sauce.ios.simulator.us
    • Sauce Labs EU Data Center: npm run test.sauce.ios.simulator.eu

Android Emulators

As with iOS, when testing on Android Emulators, you can first perform a check to see whether the device is enabled for biometric authentication. The test script in this samples is actually the same script for both iOS and Android -- the only difference is in setting the device enrollment.

  1. In your test script, check the device setting for biometrics, as shown in the prepareBiometrics function in our demo script:
    WebdriverIO Biometrics Check Sample
    loading...
  2. Android does not have a capability to control the device's biometric enablement. Instead, you must go through the device's enrollment process and call an ADB command to set the PIN values representing the successful and failed authentication. Our demo repo uses a separate script to do this, and then calls the script in the test.
    webdriverio/appium-app/examples/biometric-login/test/screen-objects/AndroidSettings.ts
    loading...
    Enable Device Biometrics in Test Sample
    loading...
  3. Now that biometrics is enabled for the device, make sure it is also enabled for the app.
    WebdriverIO Enable Biometrics in App
    loading...
  4. Wait for the login screen to appear, then call the submitBiometrics(true) method to simulate a successful biometric authentication.
    WebdriverIO Submit Bio Auth Sample
    loading...
  5. Run your test. Call:
    • Local environment: npm run test.local.ios.simulator
    • Sauce Labs US Data Center: npm run test.sauce.ios.simulator.us
    • Sauce Labs EU Data Center: npm run test.sauce.ios.simulator.eu

Additional Resources

  • Our Biometrics Demo contains all the configuration, helper, and test script files demonstrating Biometric Login use cases for both Android and iOS real and virtual devices, including:
    • React Native Sample App for Android and iOS
    • Test script to validate successful biometric login
    • Test script to validate failed biometric login
    • Test script to exit out of biometric auth modal
  • Appium Documentation for iOS Simulator Touch ID