Mobile App Testing Features and Functionality

Gestures#

Building a great user experience is more than just design. Equally important is creating intuitive user interactions and touch gestures.

Learn more:

Biometric Authentication (Touch ID/Face ID)#

Sauce Labs provides testing capabilities for mobile app biometric authentication (Touch ID and Face ID). You can chose two authentication options by using the Biometric Authentication Tool in the toolbar during your test session.

Security Notice

KeyStore is normally used to implement and store Touch ID and Face ID user biometrics for mobile apps. As this is a cloud security risk, Sauce Labs does not mock the KeyStore on our real devices for supporting Touch ID and Face ID; the use of KeyStore on our real devices is not supported.

Live Testing#

Real Devices only

For Live Testing, we provide biometric authentication testing capabilities on Sauce Labs real devices. Emulators and simulators are not supported at this time.

iOS Apps#

To enable Biometric Authentication for your live iOS real device tests:

  1. Click LIVE > Mobile App to get to Sauce Labs real devices.
  2. If you haven't already, upload your iOS app *.ipa file here.
  3. Hover your mouse over the line item for your app > Click Settings.
  4. Set Biometrics Interception to Enabled.
  5. Return to the app menu by clicking Back to App Selection.
  6. Start up your live test session by hovering your mouse over your app, then click Choose Device > select your device > click Launch.

To initiate a Touch ID or Face ID action in your live test session:

  1. In the toolbar, click the Authentication fingerprint icon.
  2. Select a response:
    1. When you select PASS, you're setting biometric authentication will have been successful.
    2. When you select FAIL, you're setting biometric authentication to fail.
Biometric authorization live testing
Biometric authorization live testing

NOTE: At this time, biometric authentication is not supported for Android live testing on real devices.

Automated Testing#

You can add biometric authentication (Touch ID or Face ID) in your automated mobile app tests for iOS real devices, iOS simulators, and Android emulators that support it.

Not all iOS and Android devices support Touch ID or Face ID. Be prepared to handle test cases for devices where biometrics is not supported.


iOS Simulators#

To enable Touch ID and Face ID on Sauce Labs iOS simulators or on your local machine, you need to set the desired capability allowTouchIdEnroll to true. When the Simulator starts, Touch ID enrollment will be enabled by default.

You can also toggle Touch ID enrollment during a test session by calling, for example, the WebdriverIO client method driver.toggleEnrollTouchId(true). More examples in different programming languages can be found here.

  1. Add the allowTouchIdEnroll capability in your test script and set it to true. Example:

    allowTouchIdEnroll: true,
  2. When starting the device through the capabilities, or when you are running your test runtime, add the driver.toggleEnrollTouchId capability and set it to true. A full code spec example is available here. Example:

    driver.toggleEnrollTouchId(true);
  3. To run your test locally, call npm run test.local.ios.simulator. To run your test on an Sauce Labs iOS simulator, call one of the following data centers, based on your location:

    • US Data Center: npm run test.sauce.ios.simulator.us
    • EU Data Center: npm run test.sauce.ios.simulator.eu
  4. Try running one of the below example scripts, which demonstrate the default capabilities needed to run automated tests on iOS simulators.

    Click here to see the full iOS simulator test examples
    webdriverio/appium-app/examples/biometric-login/test/configs/wdio.ios.sauce.sim.conf.js
    loading...
    See full example on GitHub

Android Emulators#

Android emulators differ from iOS simulators in that:

  • They do not have a one-off capability that enables Touch ID authentication.
  • By default, you'd need to execute the same steps as you would on a physical mobile device (i.e., enabling a pin and the fingerprint) before you can use it in your tests.
  • Android versions differ in their methods of enabling Fingerprint, particularly in the Fingerprint wizard steps.

To enable biometric authentication on Android emulators:

  1. Open an emulator.

  2. Activate Screenlock by clicking the three dots icon > Settings > Security.

  3. Go to Fingerprint to add a new fingerprint.

  4. When prompted to place your finger on the scanner, emulate the fingerprint using this adb command.

adb -e emu finger touch <finger_id>
  1. For example, adb -e emu finger touch 1234. The automation script would use 1234 as the fingerprint. Make sure you remember the fingerprint number you've selected; when you add the fingerprint through adb, you'll need to enter it there.

  2. At this point, you should see a fingerprint detected message.

  3. Return to your Android app, navigate to an action that requires fingerprint authentication, and execute the same command on the app screen.

In the script below, you'll see that the device API level is called out; each Android OS version has a corresponding API level, which may need to be reflected in your code. For more information, see Android Platform codenames, versions, API levels, and NDK releases.

enableBiometricLogin() {
if (driver.capabilities.deviceApiLevel < 26) {
// Open the settings screen
this.executeAdbCommand('am start -a android.settings.SECURITY_SETTINGS');
this.waitAndClick('Fingerprint');
this.fingerPrintWizardSevenOrLower(DEFAULT_PIN);
} else {
// Open the settings screen and set screen lock to pin
this.executeAdbCommand(`am start -a android.settings.SECURITY_SETTINGS && locksettings set-pin ${DEFAULT_PIN}`);
this.waitAndClick('Fingerprint');
this.fingerPrintWizardEightOrHigher(DEFAULT_PIN);
}
// We need to end this method where we started it, which is the current running app
// Open the app again
driver.launchApp();
}

Try running one of the below example scripts, which demonstrate the default capabilities needed to run automated tests on Android emulators.

Click here to see the full Android emulator test examples
webdriverio/appium-app/examples/biometric-login/test/configs/wdio.android.sauce.emu.conf.js
loading...
See full example on GitHub

iOS Real Devices#

To enable Touch ID and Face ID on iOS real devices, add the allowTouchIdEnroll capability in your test script and set it to true, as shown in the example below:

webdriverio/appium-app/examples/biometric-login/test/configs/wdio.ios.sauce.real.conf.js
loading...
See full example on GitHub

Android Real Devices#

At this time, biometric authentication is not supported for Android real device live testing.

Additional Resources#

Camera Image Injection#

Camera Image Injection – also known as camera mocking – is a Sauce Labs Real Device Cloud (RDC) feature that simulates taking a picture through a mobile app, allowing you to test the app’s camera-based functionality and deliver the best possible user experience.

Does your mobile app have the ability to take images and then process or store them within the app (e.g., scanning a bank check, taking a social media selfie)? To mimic camera behavior when testing your app, you'll provide the app with an image that mocks the use of the camera. During a Sauce Labs live test, you'll be prompted to upload a photo that will be fed to your app, rather than using your device camera to take the photo. For automated tests, you'll pass an image to the image injection endpoint. Image Injection intercepts the camera input and replaces the camera output with the image file via the camera APIs. When the app requests an image from the device's camera, we inject your uploaded image into the response (the app doesn't know the difference).

NOTE: Appium only; not available for Espresso and XCUITest frameworks at this time.

What You'll Need#

You'll need to upload your app to Sauce Labs prior to testing. For instructions, see Uploading your App to Real Devices using the User Interface.

Using Camera Image Injection#

Camera Image Injection is a core feature built into our RDC functionality and available for use with public and private devices. Your mobile app accesses the camera and instead of getting back the picture of the device camera, it'll retrieve your uploaded image for your test. You employ the built-in device camera in your live and automated testing and perform test cases that require taking images with any of the device cameras.

System Requirements#

See the topics under Mobile App Testing for RDC system requirements.

Key Specs#

Supported#
Not Supported#
  • Ephemeral apps (i.e., app with temporary messages that disappear after a certain timeframe).
  • Testing with Emulators, Simulators.

Common Use Cases & Examples#

Below are common use cases ideal for implementing Camera Image Injection in your tests.

Scanning a Check for a Mobile Banking App Deposit#

Many mobile banking apps allow customers to deposit checks using their smartphone. The customer takes and uploads an image of their physical paper check, and the image is then submitted to the bank for processing.

Using a QR Code to Link to an Embedded URL#

QR codes are often used as a way to bridge print media to digital. Users take a photo with a QR code reader app, the app scans the code and directs them to an embedded URL.

For use cases that involve scanning barcodes or QR codes, your own application in testing must do the actual image processing. Camera Image Injection passes your uploaded image directly to your app as if it came from the device camera; it does not do any processing.

Taking a Selfie for a User Profile Photo#

This could be taking a selfie or uploading a picture for apps that require a user profile photo. You can use Camera Image Injection to test image formats and sizes.

Taking an Image to Store or Send via Mobile App#

Whether it’s a social media app or photo sharing, this use case can encompass many different scenarios. In its simplest form, it could be taking pictures from the front or back camera to send and/or archive within the app.

Live Testing#

  1. Launch a test session by logging into Sauce Labs and going to Live > Mobile App.
  2. Hover over the app you intend to test and click the Settings icon.
  3. In the editor that appears, make sure the Image Injection toggle is enabled and then return to the app selection screen. This needs to be enabled in order to choose a mobile device.
  4. Hover over the app again and click the Choose Device icon to bring up the menu of available devices.
  5. Hover over the device of your choice and click Launch to begin a test session on that device with your app.
  6. When you want to capture an image with the app camera, go to the right toolbar and click the Camera icon to initiate Camera Image Injection.
  7. Click Choose Image to stage your image for the camera.
  8. Activate the camera inside of your app.
  9. The device will show your uploaded image in the app as if the image was taken by the device camera. The image will continue to be available, should you go back to the camera during your test session, or you can upload another image and capture it with the camera.

Video: Running iOS Mobile Device Tests#

This video illustrates how to use both biometric authentication and image injection (starting at 0:41) in an iOS live test:

Video: Running Mobile Device QR Code Tests#

When injecting an image with a QR Code or barcode, the image size in your preview may exceed the boundaries of the target scanner area, which would prevent your app from reading the code. In this scenario, you'd need to add padding to your uploaded image so that when it's scaled to full-screen, the QR Code will fit inside the scanning area limits and can be processed.

Click to view video

Automated Testing#

In your automated test script, you'll need to input the desired capabilities specific to Camera Image Injection (see below code snippets). The code will execute your image upload and opening of the device camera.

  1. First, you'll need add the camera instrumentation desired capability command, sauceLabsImageInjectionEnabled, to your test script. This capability enables image injection functionality.

Webdriver.io example

exports.config = {
//...
capabilities: [
{
deviceName: 'Samsung Galaxy S10',
platformName: 'Android',
platformVersion: '10',
automationName: 'UiAutomator2',
// Enable image-injection on RDC
sauceLabsImageInjectionEnabled: true,
},
]
//...
}

Java example

var desiredCapabilities = new DesiredCapabilities();
desiredCapabilities.setCapability("deviceName", "Samsung Galaxy S10");
desiredCapabilities.setCapability("platformVersionName", "10");
...
// Enable image-injection on RDC
desiredCapabilities.setCapability("sauceLabsImageInjectionEnabled", true);
  1. In this step, you're adding the image injection method to your test script by providing a file path to your image. You can put the below code snippet into your test script in one or more places. Then, when you execute your test, the code snippets will call the endpoint and pass the image to the app for further processing or for other use.

To change the image, you'll need to send a custom command with a different image. Note that your image file path must be converted to base64 encoding.

Webdriver.io example

const {readFileSync} = require('fs');
const {join} = require('path');
// Read the file from your project and transform it to a base64 string
const qrCodeImage = readFileSync(join(process.cwd(), 'assets/qr-code.png'), 'base64');
// Provide the transformed image to the device
driver.execute(`sauce:inject-image=${qrCodeImage}`);

Java example

import java.util.Base64;
import static org.apache.commons.io.IOUtils.toByteArray;
// Read the file from the classpath and transform it to a base64 string
String qrCodeImage = Base64.getEncoder().encodeToString(
toByteArray(getClass().getResourceAsStream("qr-code.png")));
// Provide the transformed image to the device
((JavascriptExecutor)driver).executeScript("sauce:inject-image=" + qrCodeImage);

Troubleshooting#

Here are some common errors you may see in the course of testing with Camera Image Injection and how to resolve them.

Image injection failed#

This error is displayed when you attempt to inject your image before the app fully loads during your initial test session startup. You must wait until your app has fully loaded prior to injecting your image.

Image injection is not enabled for the application#

This error is displayed due to one or more of these reasons:

  • Enable Image Injection checkbox is not checked; this needs to be checked.
  • For Android tests, the debuggable flag (android:debuggable="true") is missing from your application's manifest file.

Additional Resources#

For support in Beta, please reach out to your CSM or SE.

Virtual USB (RDC)#

Virtual USB (vUSB) is a mobile app debugging tool that simulates connecting a Sauce Labs real device directly to your local machine with a USB cable. It integrates into your development environment as if the device is connected directly to your workstation, meaning you can use your choice of homegrown development and testing tools to debug. See Virtual USB for Sauce Labs Real Devices for more information.

Last updated on by Kim