The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing

Insights

External Resources

More Info


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

When testing mobile applications, you now have the option to upload your application to our new temporary application storage. Application storage is quite different and more flexible than our previous iteration (Sauce Storage) in multiple ways:

  • Upload all your apps to the same location for cross-device automated and live testing with both virtual or real devices
  • Share your uploaded apps between your Extended Team Management (xTM) team members
  • Store apps in the new application storage for 60 days rather than 7 in Sauce Storage

See the following sections for more information:

What You'll Need

Upload an App with App-Upload

  1. Log in to Sauce Labs and select LIVE from the options in the left-hand navigation.
  2. Select Mobile-App.
  3. You will see a list of previously uploaded apps.
  4. To the right of the page, select App Upload to upload a new application (Note: Live Testing on Real Devices only at the moment):



You can either drag and drop and application, or browse for the file. Supported application file types include *.APK, *IPA, or *.ZIP (.ZIP must include a valid iOS application bundle) files of up to 4 GB. Non-app file uploads are not supported in the UI at this time, but can be uploaded through the API.


Delete Apps with the Delete Button

The Delete button will delete a whole application (e.g., a group of builds belonging to the same app package). Files associated with app identifiers (i.e., belong to the same platform and are accessible to the same team) are indicated by the + symbol next to version number. Also, the version number shown is the most recently updated file, not necessarily the "latest" version of the application.

Upload Files with the REST API

Below are some examples of how to use the Sauce Labs REST API to upload your mobile file to Sauce Storage. If you do not have a file to test, consider using the Sauce Labs Swag Labs sample app for validating this process.

REST API Authentication

The APIs and authorization credentials are located here: app.saucelabs.comA recommended best practice is to set your credentials as environment variables like so:

SAUCE_USERNAME='valid.username'
SAUCE_ACCESS_KEY='valid.key'

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

Accepted File Types 

App Storage recognizes *.apk files as iOS apps and  *.ipa files as Android apps, and will also parse a *.zip file to determine whether a valid *.app bundle exists, accepting it as an iOS app if it does. You can also upload and store other file types for generic use, such as a pre-run executable, package, or binary. Some of the formats for this type of use case include:

  • *.js
  • *.py
  • *.tar
  • *.zip
  • *.sh
  • *.bat

Extended Team Management Sync

App Storage uses an XTM (Extended Team Management) sync feature which allows for user permissions schemes. In other words, a Sauce Labs admin (either an org admin or a team admin) can control access to individual application files or specific binary/script files. By default, all uploaded files are shared with the same team where the user participates currently. You, as a user, can only access files that are shared with the team where you contribute/participate unless your role is an organization admin in which case you have access to all files in your particular organization.

To manage access to your organization go to Account > Team Management

Storage API Endpoints

There are two main contexts/branches for the storage API:

  • One for working with separate application builds (individual builds, application files, etc.)
  • One for working with apps (groups of application builds with the same unique identifier, belonging to the same platform and team)

NOTE: Data center-specific endpoints should be used whenever possible. For more information, see Data Center Endpoints.

Upload 

Supported application files for upload are *.APK, *.IPA, or *.ZIP format of up to 4GB.

Mac OSX / Linux Example
$ curl -F 'payload=@/Users/<user-name>/Downloads/<file_name>.apk' -F name=<file_name>.apk -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY"  'https://api.us-west-1.saucelabs.com/v1/storage/upload'
Windows Example
> curl -F "payload=@\Users\%SAUCE_USERNAME%\Downloads\<file_name>.apk" -F name=<file_name>.apk -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%"  'https://api.us-west-1.saucelabs.com/v1/storage/upload'
Example Response (JSON)
{
   "item":{
      "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
      "owner":{
         "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
         "org_id":"c064890612424e34a12fca98ce4f32c6"
      },
      "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
      "upload_timestamp":1593450387,
      "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
      "kind":"android",
      "group_id":2807,
      "metadata":{
         "identifier":"com.swaglabsmobileapp",
         "name":"Swag Labs Mobile App",
         "version":"2.3.0",
         "icon":"<long-serial-number>",
         "version_code":13,
         "min_sdk":16,
         "target_sdk":28
      },
      "access":{
         "team_ids":[
            "a15e40997f2b44ee9615d9803cb4b439"
         ],
         "org_ids":[

         ]
      }
   }
}
Mac OSX / Linux Example
$ curl -F 'payload=@/Users/<user-name>/Downloads/<file_name>.apk' -F name=<file_name>.apk -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY"  'https://api.eu-central-1.saucelabs.com/v1/storage/upload'
Windows Example
> curl -F 'payload=@\Users\<user-name>\Downloads\<file_name>.ipa' -F name=<file_name>.ipa -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%"  'https://api.eu-central-1.saucelabs.com/v1/storage/upload'
Example Response (JSON)
{
   "item":{
      "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
      "owner":{
         "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
         "org_id":"c064890612424e34a12fca98ce4f32c6"
      },
      "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
      "upload_timestamp":1593450387,
      "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
      "kind":"android",
      "group_id":2807,
      "metadata":{
         "identifier":"com.swaglabsmobileapp",
         "name":"Swag Labs Mobile App",
         "version":"2.3.0",
         "icon":"<long-serial-number>",
         "version_code":13,
         "min_sdk":16,
         "target_sdk":28
      },
      "access":{
         "team_ids":[
            "a15e40997f2b44ee9615d9803cb4b439"
         ],
         "org_ids":[

         ]
      }
   }
}

Download

NOTE: Each instance of an uploaded application generates a unique identification number. If you're not sure of the file_id number, you can use the files management endpoints to find the desired key.

Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.us-west-1.saucelabs.com/v1/storage/download/<file_id>' -o /path/to/test/code/app-name
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.us-west-1.saucelabs.com/v1/storage/download/<file_id>' -o \path\to\test\code\app-name
Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.eu-central-1.saucelabs.com/v1/storage/download/<file_id>' -o /path/to/test/code
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.eu-central-1.saucelabs.com/v1/storage/download/<file_id>' -o \path\to\test\code

Files 

Possible Parameters for /files:

  • q: search term (semantic version, build number, file name, app name, app identifier, etc.)
  • kind = ios, android, other
  • file_id = one or more file ids to be listed
  • team_id = one or more team ids the listed file(s) should be shared with
  • page = the number of the current page to show, by default it starts from one
  • per_page = the count of items per listed page. By default it is 25, and the acceptable range is 1-100
Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.us-west-1.saucelabs.com/v1/storage/files?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.us-west-1.saucelabs.com/v1/storage/files?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Example Response (JSON)
{
   "items":[
      {
         "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
         "owner":{
            "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
            "org_id":"c064890612424e34a12fca98ce4f32c6"
         },
         "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
         "upload_timestamp":1593450387,
         "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
         "kind":"android",
         "group_id":2807,
         "metadata":{
            "identifier":"com.swaglabsmobileapp",
            "name":"Swag Labs Mobile App",
            "version":"2.3.0",
            "icon":"<long-serial-number",
            "version_code":13,
            "min_sdk":16,
            "target_sdk":28
         },
         "access":{
            "team_ids":[
               "a15e40997f2b44ee9615d9803cb4b439"
            ],
            "org_ids":[

            ]
         }
      }
   ],
   "links":{
      "prev":null,
      "next":null,
      "self":"?379c301a-199c-4b40-ad45-4a95e5f30a3a=&page=1&per_page=25"
   },
   "page":1,
   "per_page":25,
   "total_items":1
}
Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.eu-central-1.saucelabs.com/v1/storage/files?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.eu-central-1.saucelabs.com/v1/storage/files?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Example Response (JSON)
{
   "items":[
      {
         "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
         "owner":{
            "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
            "org_id":"c064890612424e34a12fca98ce4f32c6"
         },
         "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
         "upload_timestamp":1593450387,
         "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
         "kind":"android",
         "group_id":2807,
         "metadata":{
            "identifier":"com.swaglabsmobileapp",
            "name":"Swag Labs Mobile App",
            "version":"2.3.0",
            "icon":"<long-serial-number",
            "version_code":13,
            "min_sdk":16,
            "target_sdk":28
         },
         "access":{
            "team_ids":[
               "a15e40997f2b44ee9615d9803cb4b439"
            ],
            "org_ids":[

            ]
         }
      }
   ],
   "links":{
      "prev":null,
      "next":null,
      "self":"?379c301a-199c-4b40-ad45-4a95e5f30a3a=&page=1&per_page=25"
   },
   "page":1,
   "per_page":25,
   "total_items":1
}

Groups (App)

Possible Parameters for /groups:

  • q: search term (semantic version, build number, file name, app name, app identifier, etc.)
  • kind = ios, android, other
  • group_id = one or more group ids to be listed
  • page = the number of the current page to show, by default it starts from one
  • per_page = the count of items per listed page. By default it is 25, and the acceptable range is 1-100


Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.us-west-1.saucelabs.com/v1/storage/groups?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.us-west-1.saucelabs.com/v1/storage/groups?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Mac OSX / Linux Example
$ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.eu-central-1.saucelabs.com/v1/storage/groups?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Windows Example
> curl -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.eu-central-1.saucelabs.com/v1/storage/groups?q=Android.SauceLabs.Mobile.Sample.app.2.3.0.apk&kind=android'
Example Response (JSON)
{
   "items":[
      {
         "id":2807,
         "name":"com.swaglabsmobileapp",
         "recent":{
            "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
            "owner":{
               "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
               "org_id":"c064890612424e34a12fca98ce4f32c6"
            },
            "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
            "upload_timestamp":1593450387,
            "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
            "kind":"android",
            "group_id":2807,
            "metadata":{
               "identifier":"com.swaglabsmobileapp",
               "name":"Swag Labs Mobile App",
               "version":"2.3.0",
               "icon":"<long-serial-number>",
               "version_code":13,
               "min_sdk":16,
               "target_sdk":28
            },
            "access":{
               "team_ids":[
                  "a15e40997f2b44ee9615d9803cb4b439"
               ],
               "org_ids":[

               ]
            }
         },
         "count":1,
         "access":{
            "team_ids":[
               "a15e40997f2b44ee9615d9803cb4b439"
            ],
            "org_ids":[

            ]
         },
         "settings":{
            "proxy":{
               "host":"",
               "port":0
            },
            "proxy_enabled":false,
            "lang":"en_GB",
            "orientation":null,
            "instrumentation_enabled":true,
            "instrumentation":{
               "image_injection":true
            }
         }
      }
   ],
   "links":{
      "prev":null,
      "next":null,
      "self":"?2807=&page=1&per_page=25"
   },
   "page":1,
   "per_page":25,
   "total_items":1
}


Delete

Generally there are two ways to delete existing applications in App Storage API:

  • Delete a group of files by group_id (for example application builds with the same identifier)
  • Delete a single file/application build by file_id

Mac OSX / Linux Example
// Delete a Single File
$ curl -X DELETE -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.us-west-1.saucelabs.com/v1/storage/<file_id>'


// Delete a Group of Files
$ curl -X DELETE -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.us-west-1.saucelabs.com/v1/storage/groups/<group_id>'
Windows Example
// Delete a Single File
> curl -X DELETE -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.us-west-1.saucelabs.com/v1/storage/<file_id>'

// Delete a Group of Files
> curl -X DELETE -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.us-west-1.saucelabs.com/v1/storage/groups/<group_id>'
Mac OSX / Linux Example
// Delete a Single File
$ curl -X DELETE -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.eu-central-1.saucelabs.com/v1/storage/<file_id>'


// Delete a Group of Files
$ curl -X DELETE -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" 'https://api.eu-central-1.saucelabs.com/v1/storage/groups/<group_id>'
Windows Example
// Delete a Single File
> curl -X DELETE -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.eu-central-1.saucelabs.com/v1/storage/<file_id>'

// Delete a Group of Files
> curl -X DELETE -u "%SAUCE_USERNAME%:%SAUCE_ACCESS_KEY%" 'https://api.eu-central-1.saucelabs.com/v1/storage/groups/<group_id>'



Using Application Storage with Automated Test Builds

In the past you had the option of using Sauce Storage to retrieve your apps to use in automated tests. Now after successfully uploading your file to application storage, you can reference the unique app identifier in your test code to retrieve and us the app for automated tests.


File Name instead of File ID

You can also use the app "name" field from the storage API in the "app" capability. This approach is particularly useful if you uploaded your build to Application Storage via a CI pipeline, and you either don't know the id, or you do not wish to perform JSON parsing in order to retrieve the id. The filename field also includes any supported file that can be uploaded to application storage.

Example of uploading an Android .apk file:

App Name Example
caps.setCapability("app", "storage:filename=<file-name>.apk");
App Name Example
caps['app'] = 'storage:filename=<file-name>.apk';
App Name Example
caps['app'] = "storage:filename=<file-name>.apk"
App Name Example
caps['app'] = 'storage:filename=<file-name>.apk'
App Name Example
caps.SetCapability("app","storage:filename=<file-name>.apk");

Limitations:

  • File names are NOT unique, therefore they will always default to the latest version.
  • Currently you cannot specify the version of the app using this feature.
  • build capability not supported in VDC at this time.

Retrieving the Unique App Identifier

In order to use the applications in storage for your automated tests, you need to retrieve the unique app Identifier (file_id). For example, let's assume after you've updated a new version of your app using the /upload endpoint and the JSON response is something like below: 

Example Upload Response (JSON)
{
   "item":{
      "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a",
      "owner":{
         "id":"286c0fbb0cb644c4a012d505b8a0a1ac",
         "org_id":"c064890612424e34a12fca98ce4f32c6"
      },
      "name":"Android.SauceLabs.Mobile.Sample.app.2.3.0.apk",
      "upload_timestamp":1593450387,
      "etag":"0cf189b1c4c17a56656ada5e2d75cd51",
      "kind":"android",
      "group_id":2807,
      "metadata":{
         "identifier":"com.swaglabsmobileapp",
         "name":"Swag Labs Mobile App",
         "version":"2.3.0",
         "icon":"<long-serial-number>",
         "version_code":13,
         "min_sdk":16,
         "target_sdk":28
      },
      ...
      }
   }
}

Then the file_id would be  "id":"379c301a-199c-4b40-ad45-4a95e5f30a3a". If you're unsure of the id of an existing app, you can use the endpoint, along with the necessary parameters to find the desired application.

Updating WebDriver Capabilities

If you were previously using application stored in  sauce-storage, you can convert your existing test capabilities by replacing sauce-storage:myapp with storage:<file_id>.

Example Code Snippets

These examples assume file_id = c8511dd6-38ec-4f58-b8b9-4ec8c23ad882

Before
caps.setCapability("app", "sauce-storage:some-app.apk");
After
caps.setCapability("app", "storage:c8511dd6-38ec-4f58-b8b9-4ec8c23ad882");
Before
caps['app'] = 'sauce-storage:my_app.apk';
After
caps['app'] = 'storage:c8511dd6-38ec-4f58-b8b9-4ec8c23ad882';
Before
caps['app'] = "sauce-storage:my_app.apk"
After
caps['app'] = "storage:c8511dd6-38ec-4f58-b8b9-4ec8c23ad882"
Before
caps['app'] = 'sauce-storage:my_app.apk'
After
caps['app'] = 'storage:c8511dd6-38ec-4f58-b8b9-4ec8c23ad882'
Before
caps.SetCapability("app","sauce-storage:my_app.apk");
After
caps.SetCapability("app","storage:c8511dd6-38ec-4f58-b8b9-4ec8c23ad882");