The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing

Analytics

External Resources

More Info


Page tree
Skip to end of metadata
Go to start of metadata

Getting Started

Please choose your preferred platform for your Automated Mobile Application Testing use case:

Prerequisites for Emulators & Simulators

Before you can upload your application and leverage device emulators and simulators, you must fulfill the project support and requirements. Please review the Automated Mobile Application Testing Admin Guide for further details.

Uploading Your Application to Emulators & Simulators

Please select your preferred method for uploading your application in order to view the instructions:

Sauce Storage is a private storage space. Files uploaded will expire seven days after upload, and be removed.  If it has been over seven days since you uploaded your application to Sauce Storage, you will need to upload it again. You can upload the application you want to test to Sauce Storage using our REST API, and then access it for testing by specifying sauce-storage:myapp for the app capability in your test script.  You upload apps using  the  upload_file  method of the Sauce Labs REST API

You can use any REST client; cURL is a convenient command-line option.

Example Sauce Labs REST API command using cURL
curl -u <$SAUCE_USERNAME>:<$SAUCE_ACCESS_KEY> -X POST -H "Content-Type: application/octet-stream" \
https://saucelabs.com/rest/v1/storage/<sauce_username>/<upload_filename>?overwrite=true --data-binary @<path/to/your_file_name>

Uploading with cURL

If you're using cURL for the upload, you must include the @ before path/to/your_file_name

Uploading Other Test Assets to Sauce Storage

You can also use Sauce Storage for other assets that you want to use in your tests, such as pre-run executables.

There may be situations where you want to install an application from a downloadable remote location (AWS S3 bucket, a GitHub repository, etc.).

Please review the following guidelines below before uploading your application:

  1. Make sure your application meets the prerequisite requirements for Android and iOS Mobile Application Testing.
  2. Upload your application to the hosting location.
  3. Ensure Sauce Labs has READ access to the app URL.
  4. In your test script, enter the URL for the application as the "app" desired capability. Below is an example Java snippet: 

Running Your Test on Emulators & Simulators

Please select your Automated Mobile Application Testing use case:

Setting Your Sauce Labs Credentials in Your Test

Authentication of the Sauce Labs Platform, as well as advanced test configuration options, requires the use of the sauce:options capability. It's also recommended to export your Sauce Labs Credentials to Environment Variables.

Below are some examples of how to configure your Appium tests for Device Emulators & Simulators. You can also create your own examples using the Platform Configurator. Please visit the Test Configuration Options page for more advanced configurations, and also visit the sample test frameworks repository in GitHub for more detailed language-specific examples.

Setting Appium Capabilities for Emulators and Simulators

Below are examples of an iPhone 8 project using iOS version 12.2

DesiredCapabilities caps = DesiredCapabilities.iphone();
	caps.setCapability("appiumVersion", "1.13.0");
	caps.setCapability("deviceName","iPhone 8 Simulator");
	caps.setCapability("deviceOrientation", "portrait");
	caps.setCapability("platformVersion","12.2");
	caps.setCapability("platformName", "iOS");
	caps.setCapability("browserName", "");
	caps.setCapability("app", "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/iOS.Simulator.SauceLabs.Mobile.Sample.app.2.1.0.zip");
caps['browserName'] = ""
caps['appiumVersion'] = "1.13.0"
caps['deviceName'] = "iPhone 8 Simulator"
caps['deviceOrientation'] = "portrait"
caps['platformVersion'] = "12.2"
caps['platformName'] = "iOS"
caps['app'] = "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/iOS.Simulator.SauceLabs.Mobile.Sample.app.2.1.0.zip"
caps['browserName'] = '';
caps['appiumVersion'] = '1.13.0';
caps['deviceName'] = 'iPhone 8 Simulator';
caps['deviceOrientation'] = 'portrait';
caps['platformVersion'] = '12.2';
caps['platformName'] = 'iOS';
caps['app'] = 'https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/iOS.Simulator.SauceLabs.Mobile.Sample.app.2.1.0.zip';
caps = Selenium::WebDriver::Remote::Capabilities.iphone()
caps['appiumVersion'] = '1.13.0'
caps['deviceName'] = 'iPhone 8 Simulator'
caps['deviceOrientation'] = 'portrait'
caps['platformVersion'] = '12.2'
caps['platformName'] = 'iOS'
caps['browserName'] = ''
caps['app'] = 'https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/iOS.Simulator.SauceLabs.Mobile.Sample.app.2.1.0.zip'
DesiredCapabilities caps = new DesiredCapabilities();
	caps.SetCapability("appiumVersion", "1.13.0");
	caps.SetCapability("deviceName", "iPhone 8 Simulator");
	caps.SetCapability("deviceOrientation", "portrait");
	caps.SetCapability("platformVersion", "12.2");
	caps.SetCapability("platformName", "iOS");
	caps.SetCapability("browserName", "");
	caps.SetCapability("app", "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/iOS.Simulator.SauceLabs.Mobile.Sample.app.2.1.0.zip");

Below are examples of an Samsung Galaxy S9 Plus project using Android version 8.1

DesiredCapabilities caps = DesiredCapabilities.android();
	caps.setCapability("appiumVersion", "1.9.1");
	caps.setCapability("deviceName","Samsung Galaxy S9 Plus FHD GoogleAPI Emulator");
	caps.setCapability("deviceOrientation", "portrait");
	caps.setCapability("browserName", "");
	caps.setCapability("platformVersion","8.1");
	caps.setCapability("platformName","Android");
	caps.setCapability("app", "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/Android.SauceLabs.Mobile.Sample.app.2.2.0.apk");
caps = {}
caps['appiumVersion'] = "1.9.1"
caps['deviceName'] = "Samsung Galaxy S9 Plus FHD GoogleAPI Emulator"
caps['deviceOrientation'] = "portrait"
caps['platformVersion'] = "8.1"
caps['platformName'] = "Android"
caps['app'] = "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/Android.SauceLabs.Mobile.Sample.app.2.2.0.apk"
caps = {};
caps['appiumVersion'] = '1.9.1';
caps['deviceName'] = 'Samsung Galaxy S9 Plus FHD GoogleAPI Emulator';
caps['deviceOrientation'] = 'portrait';
caps['browserName'] = '';
caps['platformVersion'] = '8.1';
caps['platformName'] = 'Android';
caps['app'] = 'https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/Android.SauceLabs.Mobile.Sample.app.2.2.0.apk';
caps = Selenium::WebDriver::Remote::Capabilities.android()
caps['appiumVersion'] = '1.9.1'
caps['deviceName'] = 'Samsung Galaxy S9 Plus FHD GoogleAPI Emulator'
caps['deviceOrientation'] = 'portrait'
caps['browserName'] = ''
caps['platformVersion'] = '8.1'
caps['platformName'] = 'Android'
caps['app'] = 'https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/Android.SauceLabs.Mobile.Sample.app.2.2.0.apk'
DesiredCapabilities caps = new DesiredCapabilities();
	caps.SetCapability("appiumVersion", "1.9.1");
	caps.SetCapability("deviceName", "Samsung Galaxy S9 Plus FHD GoogleAPI Emulator");
	caps.SetCapability("deviceOrientation", "portrait");
	caps.SetCapability("browserName", "");
	caps.SetCapability("platformVersion", "8.1");
	caps.SetCapability("platformName", "Android");
	caps.SetCapability("app", "https://github.com/saucelabs/sample-app-mobile/releases/download/2.2.0/Android.SauceLabs.Mobile.Sample.app.2.2.0.apk");

Example Appium Scripts

For Example Purposes Only

The code in these scripts is provided on an "AS-IS” basis without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement. Your tests and testing environments may require you to modify these scripts. Issues regarding these scripts should be submitted through GitHub. These scripts are not maintained by Sauce Labs Support.

For Example Purposes Only

The code in these scripts is provided on an "AS-IS” basis without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement. Your tests and testing environments may require you to modify these scripts. Issues regarding these scripts should be submitted through GitHub. These scripts are not maintained by Sauce Labs Support.

 



Using Native Test Frameworks on Sauce Labs requires the Sauce Runner. Please visit the following pages for further information, example scripts, and demos using the Sauce Runner with native frameworks.

Product Announcements


Blog Posts

Additional Topics


Prerequisites for Real Devices

Before you can upload your application and leverage real devices, you must fulfill the project support and requirements. Please review the Automated Mobile Application Testing Admin Guide for further details.

HockeyApp EOL

Sauce Labs RDC will no longer support apps that exist in HockeyApp. Please read the following announcement for further details: HockeyApp End of Life: How to Prepare as well as the transition guide here: https://hockeyapp.net/faq/

Uploading Your Application to Real Devices

Please select your preferred method for uploading your application in order to view the instructions:

Using the Legacy Test Object UI:
  1. Log into your account. 
  2. Select whether you want to create an Android, iOS, or web-based mobile application project
    1. For an application project, browse to the file containing your application, and upload it.

    2. For a website project, enter the URLName, and Version Number for the website. 
  3. Enter the Device Settings for your project.

    DO NOT set a PIN lock at any point when managing the device settings; this disables the device and disrupts the device maintenance process. Refer to this page for more details

  4. Click Save.
  5. Your project will appear on the Apps dashboard.  
  6. Select your project to view the project dashboard. 
    On the project dashboard you can now select Manual or Automated Tests to begin testing your project. Once your tests run, you can view the results by selecting the type of test 

When you create a real device project, normally you upload and store the application you want to test on the Sauce Labs servers. As you develop your application and upload new versions of it, Sauce Labs will keep track of the different versions. However, there may be situations where you want to install an application directly onto a real device from a remote location. The application is completely removed from the real device after the test completes, providing an added layer of security for your application.


Each Session is a "Fresh" Install

You will not be able to access information about different versions of your application because each session includes a "fresh" installation of your application. 

For Automated Appium Testing Only

You can only install remote applications for automated Appium testing. Espresso and Robotium automated tests are not supported. Live Testing is also not supported.

Using the Legacy Test Object UI:

  1. Click New App to create your project.
  2. Click Install Remote, enter the name of your application, and click Save.
  3. In your Appium test script, enter the URL for the application as the app desired capability, as shown in this example.

    desiredCapabilities.setCapability("app", "https://drive.google.com/uc?export=download&id=1balA7M1p4cM-JgGh6aKbuGiPE4bPStDK");

Choosing a REST API

If you run Appium tests with your:

Sauce Labs CredentialsTest Object  Credentials

Please use the Unified Platform Storage REST API (app.saucelabs.com

To retrieve your Sauce Labs credentials:

Please use the Legacy Real Device Cloud REST API (app.testobject.com)

To retrieve your Test Object credentials:

Below are some examples of how to use the Sauce Labs REST API to upload your mobile application to Sauce Storage. Please select your Sauce Labs Testing Platform whether you're using Test Object (Legacy) or the Sauce Labs Unified Platform.

Unified Platform API

US Data Center

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://api.us-west-1.saucelabs.com/v1/rdc/apps/upload -H \
"Content-Type: application/octet-stream" --data-binary @your_app.apk

Useful Header Parameters

App-DisplayName

A custom display name for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://api.us-west-1.saucelabs.com/v1/rdc/apps/upload -H \
"Content-Type: application/octet-stream" -H \
"App-DisplayName: yourCustomDisplayName" --data-binary @your_app.apk


App-Identifer

A custom identifier for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://api.us-west-1.saucelabs.com/v1/rdc/apps/upload -H \
"Content-Type: application/octet-stream" -H \
"App-Identifier: identifier_for_your_app" --data-binary @your_app.apk

EU Data Center

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://api.eu-central-1.saucelabs.com/v1/rdc/apps/upload -H \
"Content-Type: application/octet-stream" --data-binary @your_app.apk

Useful Header Parameters

App-DisplayName

A custom display name for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://api.eu-central-1.saucelabs.com/v1/rdc/apps/upload -H \
"Content-Type: application/octet-stream" -H \
"App-DisplayName: yourCustomDisplayName" --data-binary @your_app.apk


App-Identifer

A custom identifier for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://api.eu-central-1.saucelabs.com/v1/rdc/apps/upload -H \
"Content-Type: application/octet-stream" -H \
"App-Identifier: identifier_for_your_app" --data-binary @your_app.apk



Legacy Real Device API

US Data Center

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" --data-binary @your_app.apk

Useful Header Parameters

App-DisplayName

A custom display name for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" -H \
"App-DisplayName: yourCustomDisplayName" --data-binary @your_app.apk


App-Identifer

A custom identifier for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" -H \
"App-Identifier: identifier_for_your_app" --data-binary @your_app.apk

EU Data Center

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" --data-binary @your_app.apk

Useful Header Parameters

App-DisplayName

A custom display name for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" -H \
"App-DisplayName: yourCustomDisplayName" --data-binary @your_app.apk


App-Identifer

A custom identifier for your app.

curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" -H \
"App-Identifier: identifier_for_your_app" --data-binary @your_app.apk

Check if App Already Exists

You can use a custom app identifier to to check if an app was already uploaded.

First, get all the apps for a specified MD5:

curl -u "your_username:your_api_key" -X GET \
https://app.testobject.com:443/api/storage/app?appIdentifier=MD5_hash_of_your_app

If the call returns an empty JSON array, start uploading the file:

curl -u "your_username:your_api_key" -X POST \
https://app.testobject.com:443/api/storage/upload -H \
"Content-Type: application/octet-stream" -H \
"App-Identifier: MD5_hash_of_your_app" --data-binary @your_app.apk




Running Your Test on Real Devices

Please select your Automated Mobile Application Testing use case:

Below are some examples of how to configure Appium tests for Real Devices.  For real device testing you'll need to grab the project API key and app ID. Please visit the Appium Capabilities for Real Device Testing page for required/optional capabilities and more advanced test configuration options. Also visit the sample test frameworks repository in GitHub for more detailed language-specific examples.

Below are examples of an iPhone 8 project using iOS version 12.2

DesiredCapabilities caps = DesiredCapabilities();
	caps.setCapability("appiumVersion", "1.13.0");
	caps.setCapability("test_object_api_key", "project_api_key");
	caps.setCapability("test_object_app_id", "1");
	caps.setCapability("deviceName","iPhone 8");
	caps.setCapability("deviceOrientation", "portrait");
	caps.setCapability("platformVersion","12.2");
	caps.setCapability("platformName", "iOS");
	caps.setCapability("browserName", "");
caps['browserName'] = ""
caps['appiumVersion'] = "1.13.0"
caps['test_object_api_key'] = "project_api_key"
caps['test_object_app_id'] = "1"
caps['deviceName'] = "iPhone 8"
caps['deviceOrientation'] = "portrait"
caps['platformVersion'] = "12.2"
caps['platformName'] = "iOS"
caps['browserName'] = '';
caps['appiumVersion'] = '1.13.0';
caps['test_object_api_key'] = "project_api_key";
caps['test_object_app_id'] = "1";
caps['deviceName'] = 'iPhone 8';
caps['deviceOrientation'] = 'portrait';
caps['platformVersion'] = '12.2';
caps['platformName'] = 'iOS';
caps = Selenium::WebDriver::Remote::Capabilities()
caps['appiumVersion'] = '1.13.0'
caps['test_object_api_key'] = 'project_api_key'
caps['test_object_app_id'] = '1'
caps['deviceName'] = 'iPhone 8'
caps['deviceOrientation'] = 'portrait'
caps['platformVersion'] = '12.2'
caps['platformName'] = 'iOS'
caps['browserName'] = ''
DesiredCapabilities caps = new DesiredCapabilities();
	caps.SetCapability("appiumVersion", "1.13.0");
	caps.SetCapability("deviceName", "iPhone 8");
	caps.setCapability("test_object_api_key", "project_api_key");
	caps.setCapability("test_object_app_id", "1");
	caps.SetCapability("deviceOrientation", "portrait");
	caps.SetCapability("platformVersion", "12.2");
	caps.SetCapability("platformName", "iOS");
	caps.SetCapability("browserName", "");

Below are examples of an Samsung Galaxy S9 Plus project using Android version 8.1

DesiredCapabilities caps = DesiredCapabilities();
	caps.setCapability("appiumVersion", "1.9.1");
	caps.setCapability("test_object_api_key", "project_api_key");
	caps.setCapability("test_object_app_id", "1");
	caps.setCapability("deviceName","Samsung Galaxy S9 Plus");
	caps.setCapability("deviceOrientation", "portrait");
	caps.setCapability("browserName", "");
	caps.setCapability("platformVersion","8.1");
	caps.setCapability("platformName","Android");
caps = {}
caps['appiumVersion'] = "1.9.1"
caps['test_object_api_key'] = "project_api_key"
caps['test_object_app_id'] = "1"
caps['deviceName'] = "Samsung Galaxy S9 Plus"
caps['deviceOrientation'] = "portrait"
caps['platformVersion'] = "8.1"
caps['platformName'] = "Android"
caps = {};
caps['appiumVersion'] = '1.9.1';
caps['test_object_api_key'] = 'project_api_key';
caps['test_object_app_id'] = '1';
caps['deviceName'] = 'Samsung Galaxy S9 Plus';
caps['deviceOrientation'] = 'portrait';
caps['browserName'] = '';
caps['platformVersion'] = '8.1';
caps['platformName'] = 'Android';
caps = Selenium::WebDriver::Remote::Capabilities()
caps['appiumVersion'] = '1.9.1'
caps['test_object_api_key'] = 'project_api_key'
caps['test_object_app_id'] = '1'
caps['deviceName'] = 'Samsung Galaxy S9 Plus'
caps['deviceOrientation'] = 'portrait'
caps['browserName'] = ''
caps['platformVersion'] = '8.1'
caps['platformName'] = 'Android'
DesiredCapabilities caps = new DesiredCapabilities();
	caps.SetCapability("appiumVersion", "1.9.1");
	caps.setCapability("test_object_api_key", "project_api_key");
	caps.setCapability("test_object_app_id", "1");
	caps.SetCapability("deviceName", "Samsung Galaxy S9 Plus");
	caps.SetCapability("deviceOrientation", "portrait");
	caps.SetCapability("browserName", "");
	caps.SetCapability("platformVersion", "8.1");
	caps.SetCapability("platformName", "Android");



Using Native Test Frameworks on Sauce Labs requires the Sauce Runner. Please visit the following pages for further information, example scripts, and demos using the Sauce Runner with native frameworks.

Product Announcements

Blog Posts

Additional Topics