The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

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

PAGE DEPRECATED: updated content available here.

In this topic, you'll learn how to create and configure a real device test project and upload an app.

What You'll Need

Select your preferred platform: Sauce Labs or TestObject, which is our legacy real device platform (under Sauce Apps > Legacy RDC).

Creating a Real Device Project on Sauce Labs

Upload an App with the REST API

Below are some examples of how to use the Sauce Labs REST API to upload your mobile application to Sauce Storage. If you do not have an app, consider using the Sauce Labs Swag Labs sample app for validating your account functionality as well as your tests.

REST API Authentication

The APIs and authorization credentials you use depend on what you run Appium tests with:

A recommended best practice is to set your credentials as environment variables like so:


For specific instructions on how to set environment variables visit, the following links:

RDC on Sauce Labs Examples

Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST -w "%{http_code}\n" \
-H "Content-Type: application/octet-stream" \
--data-binary @/path/to/
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY% -X POST -w "%{http_code}\n" \
-H "Content-Type: application/octet-stream" \
"" \
--data-binary @\path\to\
Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" -X POST -w "%{http_code}\n" \
-H "Content-Type: application/octet-stream" \
--data-binary @/path/to/
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" -X POST -w "%{http_code}\n" \
-H "Content-Type: application/octet-stream" \
"" \
--data-binary @\path\to\

Running Real Device Tests on Sauce Labs

From the Sauce Labs platform, you'll have access both our virtual device cloud (emulators, simulators) and real device cloud. This allows you to use the same features – APIs, endpoints, reporting, secure tunnels, analytics, and more – for both clouds.

Supported Use Cases for Real Devices on Sauce Labs (RDC on Sauce)

  • Execute Appium tests against a private real device hosted in the US, using your Sauce Labs username and access key

  • Use Sauce Storage, for Appium testing, as you usually do for emulators and simulators tests

  • Analyze Appium test executions, on Sauce Labs similar to the way you do it for desktop, emulators and simulators

  • Consume Real Device Cloud (RDC) API similar to the way you do for emulators and simulators (with applicable RDC settings)

RDC on Sauce Labs Endpoints

See Data Center Endpoints for details. 

RDC on Sauce API

See Mobile App Testing API.

RDC on Sauce Examples

Unified Platform Appium Testing Example
private URL createUrl() throws MalformedURLException {
    return new URL("https://$SAUCE_USERNAME:$");
void setUp() throws MalformedURLException {
    DesiredCapabilities desiredCapabilities = new DesiredCapabilities();
    desiredCapabilities.setCapability("platformName", "iOS");
    IOSDriver driver = new IOSDriver(createUrl(), desiredCapabilities);

Creating Real Device Projects on TestObject

Legacy RDC only

This information applies only to TestObject, our legacy real device platform

Uploading an Application to the TestObject Platform

When you create a project, you'll need to provide information about the website or app you want to test, and the device settings you want to use in your tests. You can also create versions of the project to reflect changes in the app or website throughout your development process. 

  1. Log into Sauce Labs, then click SAUCE APPS > Legacy RDC.
  2. Click the New App button.

  3. Choose the type of app you'd like to create. You can choose from an Android/iOS App project, a Mobile Website test project, or an Install Remote app (see App Center Integration for more info). For this example, we'll select Android/iOS App.

  4. Click Choose File, browse to the file containing your app, and upload it. 

    To view and download sample apps for iOS and Android, head to the Sauce Labs sample app page on GitHub

  5. Input your app name and version, then click Save.

  6. Edit the Device Settings as needed, then click Save.

Accessing Setup Instructions (Appium Test Automation Framework)

  1. Log into Sauce Labs, then click SAUCE APPS > Legacy RDC > select your app > AUTOMATED TESTING > Appium.

  2. Click Setup Instructions.

  3. Once you've created your app project, the setup instruction will prompt you to input required test script information:
    • API Key as desired capability

    • Data Center URL to be used as your WebDriver Hub URL

    • If you want to test on a specific mobile device – static device allocation – you'll need to provide the ID for that device. If you'd like to test on a broader array of devices – dynamic device allocation – you can specify your criteria via WebDriver desired capabilities (e.g., all Android devices with OS 9).

      To read more about Dynamic vs. Static Device Allocation, see Dynamic Device Allocation.

Versioning Real Device Projects on TestObject

Once you've created a real device project, you can create versions of it. Each of these versions will be stored in your project, and you can run tests against the current Active version, or a previous version. 

  1. Log into your account.
  2. In the Apps dashboard, select your project.

    When the project loads, you'll see an Active Versions panel. This provides information about the current version of the project.

    You can also:
    1. Click Upload New Version to add a new version of the application if this is a mobile application project.

    2. Click  Upload New URL to change the URL for a mobile website project.
    3. Click All Versions to view and select a version of your project to run your tests against. This will also change the current Active Version of the project.