Home Documentation App Automate Espresso Espresso REST API

Espresso REST API

BrowserStack supports the use of REST API to access information about your tests via the command-line interface.

App Upload

Upload App

An API to upload the App you want to test on the BrowserStack servers

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/upload" -F "file=@/path/to/app/file/Application-debug.apk" -F 'data={"custom_id": "MyApp"}'

Upload app from a Public Location

If you do not have your app file on the local machine from where you are running the test and it is hosted on a different location, you can upload it to the BrowserStack servers from any public hosted location. You can achieve that by just providing the app public url in the API call to upload an app. The url should be accessible over the internet so that BrowserStack can directly upload it from that location. Use the below API call to upload app from a publicly accessible location.

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/upload" -F "data={\"url\": \"https://www.browserstack.com/app-automate/sample-apps/android/Calculator.apk\"}"

Note:You can also test your AppCenter builds on Browserstack devices using the App Center’s public download URL. For more details on how to generate the public URL and run test on our devices, refer our App Center documentation.

Define Custom Id for your app

You can choose to set a custom_id for your apps. You can use this custom_id while executing your test in step 3. Every time you upload an app with the same custom id, the test execution will pick the last uploaded app for the custom_id you used. Custom Id is optional.

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/upload" -F "file=@/path/to/app/file/Application-debug.apk" -F "data={\"custom_id\": \"MyApp\"}"

Note: custom_id is optional. You can upload multiple builds under same custom_id. Use custom_id in 'app' capability for Espresso to always pick the last uploaded build.

Note:

  1. App upload will take few seconds to about a minute depending on the size of your app. Do not interrupt the curl command until you get the response back.
  2. If you upload an iOS app, we will resign the app with our own provisioning profile to be able to install your app on our devices during test execution.
  3. We will delete the uploaded app after 30 days from the date of upload.

Get recent uploads

An API to retrieve details about your recent App uploads. The response will not include the deleted apps

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/recent_apps"
Get recent uploads for custom id

An API to retrieve details about your recent App uploads under a specific custom id. The response will not include the deleted apps

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/recent_apps/<custom_id>"
Get recent uploads for entire group

An API to retrieve details about your recent App uploads for the entire group. The response will not include the deleted apps

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/recent_group_apps"
Delete App

An API to DELETE an uploaded App

curl -u "USERNAME:ACCESS_KEY" -X DELETE "https://api-cloud.browserstack.com/app-automate/app/delete/<app_id>"

Test Upload

Upload Test

An API to upload your test suite

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/espresso/test-suite" -F "file=@/path/to/test/file/Application-test.apk" -F 'data={"custom_id": "MyTest"}'

Upload test app from a Public Location

If you do not have your test app file on the local machine from where you are running the test and it is hosted on a different location, you can upload it to the BrowserStack servers from any public hosted location. You can achieve that by just providing the test app public url in the API call to upload an test app. The url should be accessible over the internet so that BrowserStack can directly upload it from that location. Use the below API call to upload test app from a publicly accessible location.

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/espresso/test-suite" -F "data={\"url\": \"https://www.browserstack.com/app-automate/sample-apps/android/CalculatorTest.apk\"}"
Delete Test Suite

An API to DELETE an uploaded Test Suite

curl -u "USERNAME:ACCESS_KEY" -X DELETE "https://api-cloud.browserstack.com/app-automate/espresso/test-suites/<hashed_id>"
Get recent Test Suite Uploads

An API to retrieve details of your recently uploaded test suites

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/test-suites"
Get Test Suite info

An API to get detail information about the uploaded test suite

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/test-suites/<hashed_id>"

Execute Test

Execute your test using the below API

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/espresso/build" -d \ "{\"devices\": [\"Samsung Galaxy S8 Plus-9.0\"], \"app\": \"bs://<hashed appid>\", \"deviceLogs\" : true, \"testSuite\": \"bs://<hashed testID>\"}" -H "Content-Type: application/json"
Shard Your Tests

Divide your Espresso test cases into the required number of shards and select a particular shard of your choice for execution. This enables you to run all tests in shards so as to optimize total test execution time. Two capabilities need to be defined numShards and shardIndex for test sharding. The API to shard your tests is:

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/espresso/build" -d \ "{\"devices\": [\"Samsung Galaxy S8 Plus-9.0\"], \"app\": \"bs://<hashed appid>\", \"deviceLogs\" : true, \"testSuite\": \"bs://<hashed testID>\", \"numShards\": \"<numShards_value>\", \"shardIndex\": \"<shardIndex_value>\"}" -H "Content-Type: application/json"

Note: Both the capabilities are mandatory and should be non-negative, to allow the sharding of your test cases. The numShards capability value should be greater than zero and shardIndex should be anywhere between 0 to (numShards-1). Also, if you want to group all your shards under one build, make use of the capability project for grouping. Example: "project": "project123"

Projects

Project name for Builds

To group your builds under one project, execute your tests using the parameter project. The REST API for grouping is:

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/espresso/build" -d \ "{\"devices\": [\"Samsung Galaxy S8 Plus-9.0\"], \"app\": \"bs://<hashed appid>\", \"deviceLogs\" : true, \"testSuite\": \"bs://<hashed appid>\", \"project\": \"<your_project_name>\"}" -H "Content-Type: application/json"
Notify URL

Set the notify URL for projects using the parameter projectNotifyURL to enable us to send a confirmation once the execution of all the builds under a project is completed. The callback will be sent if there are no builds triggered for 5 mins with the same project name post the previous execution. Set this parameter along with project parameter. The REST API for setting notify URL for a project is:

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/espresso/build" -d \ "{\"devices\": [\"Samsung Galaxy S8 Plus-9.0\"], \"app\": \"bs://<hashed appid>\", \"deviceLogs\" : true, \"testSuite\": \"bs://<hashed appid>\", \"project\": \"<your_project_name>\", \"projectNotifyURL\": \"<your_notify_url>\"}" -H "Content-Type: application/json"
List all builds

To display all builds associated with a project (grouped using project parameter while execution). The REST API is:

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/projects/<project_name>"

Builds

Build Summary / Test status

An API to get the status of your test execution or fetch the summary of your build

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/builds/<build_id>"

Sessions

Session Details

An API to get the details of your test sessions. Each session is the execution of your test suite on individual devices.

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/builds/<build_id>/sessions/<session_id>"
Retrieving JUnit Reports for a Session

Once your build completes, you can access your test reports in the standard JUnit XML format. The reports are available for each session run inside a build. To fetch the report:

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/builds/<build_id>/sessions/<session_id>/report"

Debug

Retrieve App Automate network logs

Logs are available to you in HAR (HTTP Archive) format, and these can be retrieved using REST API.

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/builds/<build_id>/sessions/tests/<test_id>/networklogs"
Retrieving App Profiling data

An API to get the details of your test sessions. Each session is the execution of your test suite on individual devices.

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/espresso/builds/<build_id>/sessions/tests/<test_id>/appprofiling"

Media Upload

Upload Media

An API to upload media files you want to use in your tests running on the BrowserStack servers

curl -u "USERNAME:ACCESS_KEY" -X POST "https://api-cloud.browserstack.com/app-automate/upload-media" -F "file=@/path/to/media/file/mediaFile.jpg" -F 'data={"custom_id": "MyMedia"}'
Get recent uploads

An API to retrieve details about your recent Media File uploads. The response will not include the deleted Media Files

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/recent_media_files"
Get recent uploads for custom id

An API to retrieve details about your recent Media File uploads under a specific custom id. The response will not include the deleted Media Files

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/recent_media_files/<custom_id>"
Get recent uploads for entire group

An API to retrieve details about your recent Media File uploads for the entire group. The response will not include the deleted Media Files

curl -u "USERNAME:ACCESS_KEY" -X GET "https://api-cloud.browserstack.com/app-automate/recent_group_media"
Delete Media File

An API to DELETE an uploaded Media File

curl -u "USERNAME:ACCESS_KEY" -X DELETE "https://api-cloud.browserstack.com/app-automate/custom_media/delete/<MediaId>"