Builds

Each build represents an execution of your Espresso test-suite on one or more devices on BrowserStack. Use our REST API to execute and manage your test builds. In addition, you can fetch build status in real-time as well as obtain access to video recording and other test execution logs.

Execute a build

POST /app-automate/espresso/v2/build

Start the execution of a new build on BrowserStack. While making a request, you must specify the application under test, Espresso test-suite as well as a list of devices to execute your tests on. In addition, you can specify a number of other parameters to customise test execution. Every build has a unique build_id associated with it. This is returned in the response to this endpoint.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/espresso/v2/build" \
-d '{"app": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3", "testSuite": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1","project" : "Espresso_Test", "devices": ["Samsung Galaxy S20-10.0","Google Pixel 3-9.0"]}' \
-H "Content-Type: application/json"

app^* String

Specify the application under test. Use app_url or custom_id or shareable_id of a previously uploaded app. Learn more about app API
testSuite^* String

Specify an Espresso test-suite. Use test_url or custom_id or shareable_id of a previously uploaded test-suite. Learn more about testSuite API
devices^* Array

List of devices to execute your tests on. Learn more about selecting devices
Example: ['Samsung Galaxy S8-7.0', 'Google Pixel 3-10.0']

shards Object

Split an Espresso test-suite into multiple shards and execute them in parallel.

▶ SHOW VALUES

numberOfShards^* Integer

The total number of shards to split the test-suite into.

deviceSelection String

Specify if a shard should run on all specified devices (using devices parameter) or on only one random device.

Possible Value	Description
`all`	Each shard will run on all specified devices. Thus, the total number of parallel tests required for test execution will be equal to (numberOfShards * number of specified devices). This is default behaviour.
`any`	Each shard will run on any one random device. Thus, the total number of parallel tests required for test execution will be equal to (numberOfShards)

mapping Array

Details of how test sharding should be handled. Each shard should have its corresponding mapping. This is optional parameter - if mapping is not provided, we will handle test sharding automatically.

▶ SHOW VALUES

name^* String

Unique identifier for each shard.
Example: 0, 1

strategy^* String

Strategy used to shard. The possible values:

Possible Value	Description
`class`	Allows you to define a list of test classes to be executed in a particular shard.
`package`	Allows you to define a list of test packages to be executed in a particular shard.
`annotation`	Allows you to run tests in a shard based on test annotations.
`size`	Allows you to run tests in a shard based on test size annoations (E.g. SmallTest, MediumTest, LargeTest).

values^* Array

Class/Package/Annotation/Size values depending on the type of strategy selected.
Example: ["com.android.dashboard.Home", "com.android.profile.addUser"] for class strategy.

project String

Unique identifier to logically group multiple builds together. Only letters (A-Z, a-z), digits (0-9), periods (.), colons (:) and underscores (_) are allowed. Any other characters are ignored.
Show 28 more
class String

Filter test cases by selected classes in the test-suite. Specify a list of fully qualified Java class name(s).
Example: ["com.android.foo.ClassA", "com.android.foo.ClassB"]
package String

Filter test cases by selected packages in the test-suite. Specify a list of fully qualified Java package name(s).
Example: ["com.android.foo"]
annotation String

Filter test cases by selected annotations in the test-suite. Specify a list of fully qualified annotation(s).
Example: ["com.android.foo.MyAnnotation"]
size String

Filter test cases of specific test size i.e tests annotated with @SmallTest, @MediumTest or @LargeTest in the test-suite. Specify a list of test size values (small/medium/large).
Example: ["small", "medium"]
singleRunnerInvocation String

Execute all test cases together with a single test runner invocation. By default, its set to false. Learn more about singleRunnerInvocation API
callbackURL String

Specify a callback URL to enable BrowserStack to notify you upon the completion of your build.
projectNotifyURL String

Specify a callback URL to enable BrowserStack to notify you upon the completion of all builds under the given project. You will receive a callback if no new builds triggered for 5 mins and all existing builds have finished execution.

Note: Set this parameter along with the project parameter.
networkLogs Boolean

Capture network logs (data such as network traffic, latency, HTTP requests and responses in the HAR format) for your test execution. By default, its set to false.
deviceLogs Boolean

Capture device logs (system logs specific to your application generated by Android) for your test execution. By default, its set to false.
enableSpoonFramework Boolean

Capture screenshots using the Spoon framework.
debugscreenshots Boolean

Capture screenshots using App Automate’s native screenshot feature. Check out the espresso-browserstack sample repository for more details on using the native screenshot feature.
video Boolean

Enable or disable video recording for your test execution. By default, its set to true.
gpsLocation String

Simulate the location of the device to specific GPS coordinates. Specify latitude followed by longitude. Learn more about gpsLocation API.
Example: 40.730610,-73.935242
geoLocation String

Test your app behavior from different countries using IP geolocation. Specify the two letter country code. Learn more about geoLocation API.
Example: CN for China, FR for France.
networkProfile String

Simulate different network conditions while testing your app.
Example: 2g-gprs-good, 2g-gprs-lossy. View the list of supported network profiles.
customNetwork String

Simulate custom network condition while testing your app. Specify download speed (kbps), upload speed (kbps), latency (ms), packet loss (%).
Example: 1000, 1000, 100, 1
language String

Set the language of the app under test.
Example: fr (for French)
locale String

Set locale to test the localized version of your app.
Example: fr_CA (for French-Canada)
appStoreConfiguration Object

Set credentials for Google account login. You need to pass:

Possible Value Description

username Username of your Google account

password Password of your Google account

Example: {"username":"xyz@gmail.com","password":"xyz@123"}
deviceOrientation Boolean

Set the screen orientation of the mobile device. Specify portrait or landscape. By default, its set to portrait .
acceptInsecureCerts Boolean

Set this parameter to true to avoid invalid certificate errors while using self-signed certificate to test your app. By default, its set to false.
uploadMedia Array

Set this parameter if you want to use your uploaded images or videos during test execution. Specify a list of media_url for previously uploaded images or video. Learn more about uploadMedia API.
local Boolean

Enable Local Testing for App Automate. With Local Testing enabled, test apps that retrieve data from servers on your local machine or other private network configurations.
localIdentifier Boolean

If you are using the same account to test multiple applications, you can set up a named connection using the localIdentifier option. Example: Test123
idleTimeout Boolean

Use this parameter to specify the maximum time limit for which your test execution can remain idle. If it exceeds this threshold, your build status will change to timed out. Accepted range of values are between 60 seconds to 900 seconds. By default, its set to 900 seconds.
clearPackageData Boolean

Use this parameter to clear app data after every test run. Check out the clear app data guide to learn more.
buildTag String

Unique identifier to tag builds. Only letters (A-Z, a-z), digits (0-9), periods (.), colons (:) and underscores (_) are allowed. Any other characters are ignored.
Example: Reg
disableAnimations Boolean

Set this parameter to true to disable animations on the device.

Possible Value	Description
`username`	Username of your Google account
`password`	Password of your Google account

Response attributes `200` `application/json`

Response

{
    "message": "Success",
    "build_id": "5c5ab4338cec13aeb78f7a6977344556ac00bccd6"
}

message String

Status of the request.
build_id String

A unique identifier for your test execution.
Example: 5c5ab4338cec13aeb78f7a6977344556ac00bccd6

Get build status

GET /app-automate/espresso/v2/builds/{buildID}

Once a build is started, you can fetch its status using this endpoint. You can obtain the overall summary of your test execution as well as results for each individual test case.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY"
  -X GET "https://api-cloud.browserstack.com/app-automate/espresso/v2/builds/{build_id}"

buildID^* String

Unique build ID for your Espresso test execution.
Example: 57dd68e05f76ca3c9c0d4600fd78ae064fa537bb

Response attributes `200` `application/json`

Response

{
    "id": "5c5ab4338cec13aeb78f7a6977344556ac00bccd6",
    "framework": "espresso",
    "duration": 83,
    "status": "failed",
    "input_capabilities": {
        "devices": [
            "Samsung Galaxy S20-10.0",
            "OnePlus 7-9.0",
            "Google Pixel 3-9.0"
        ],
        "project": "Espresso_Test",
        "app": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3",
        "testSuite": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1"
    },
    "start_time": "2020-06-04 07:43:49 UTC",
    "app_details": {
        "url": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3",
        "bundle_id": "com.sample.browserstack.samplecalculator",
        "version": "1.0",
        "name": "app-debug.apk"
    },
    "test_suite_details": {
        "url": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1",
        "bundle_id": "com.sample.browserstack.samplecalculator.test",
        "version": "",
        "name": "app-debugTest.apk"
    },
    "devices": [
        {
            "device": "Samsung Galaxy S20",
            "os": "android",
            "os_version": "10.0",
            "sharding": false,
            "sessions": [
            {
                "id": "4fc55a08d7e33651d962ad676c7d6a0a08902702",
                "status": "failed",
                "start_time": "2020-06-04 07:44:07 +0000",
                "duration": 62,
                "testcases": {
                    "count": 9,
                    "status": {
                        "passed": 3,
                        "failed": 6,
                        "skipped": 0,
                        "timedout": 0,
                        "error": 0,
                        "running": 0,
                        "queued": 0
                    }
                }
            }]
        },
        {
            "device": "OnePlus 7",
            "os": "android",
            "os_version": "9.0",
            "sharding": false,
            "sessions": [
            {
                "id": "1f5c3cb7d1f7560635f6c83eafe418a2fabbef0d",
                "status": "failed",
                "start_time": "2020-06-04 07:44:10 +0000",
                "duration": 59,
                "testcases": {
                    "count": 9,
                    "status": {
                        "passed": 3,
                        "failed": 6,
                        "skipped": 0,
                        "timedout": 0,
                        "error": 0,
                        "running": 0,
                        "queued": 0
                    }
                }
            }]
        },
        {
            "device": "Google Pixel 3",
            "os": "android",
            "os_version": "9.0",
            "sharding": false,
            "sessions": [
            {
                "id": "a8760f7f5fd21f73673060d4047899e6a94d9e6",
                "status": "failed",
                "start_time": "2020-06-04 07:44:08 +0000",
                "duration": 62,
                "testcases": {
                    "count": 9,
                    "status": {
                        "passed": 3,
                        "failed": 6,
                        "skipped": 0,
                        "timedout": 0,
                        "error": 0,
                        "running": 0,
                        "queued": 0
                    }
                }
            }]
        }
    ]
}

id String

Unique build ID for your test execution.
Example: 4fc55a08d7e33651d962ad676c7d6a0a08902702
framework String

Name of the automation framework. This is set to Espresso.
duration Integer

Total duration for build completion (in seconds). This includes the time taken to install the app, test-suite, setting up the device along with the test execution time of all the test cases.
status Integer

Status of the your build execution. This is computed based on the status of every test case executed in your entire test-suite. Learn more about status API
input_capabilities Object

Details about the input parameters passed while starting the build execution.

▶ SHOW VALUES
- devices Array
  
  List of devices on which the build was executed.
  Example: ["Samsung Galaxy S20-10.0", "OnePlus 7-9.0"]
- project String
  
  Name of your project which was set inside the project parameter inside the build execution API.
- app String
  
  The app_url of the app uploaded on BrowserStack.
  Example: bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3
- testSuite String
  
  The test-url of the test-suite uploaded on BrowserStack.
  Example: bs://89c874f21852ba57957a3fdc33f47514288c4ba1
Show 4 more
start_time String

Timestamp at which the build execution was started
app_details Object

Details about the application under test uploaded on BrowserStack

▶ SHOW VALUES
- url String
  
  The app_url of the app(.apk) file uploaded on BrowserStack.
- bundle_id String
  
  Bundle ID or the package name of the app.
- version String
  
  Version code of the app that was defined in the Android manifest file.
- name String
  
  Name of your app(.apk) file.
test_suite_details Object

Details about the test-suite uploaded on BrowserStack

▶ SHOW VALUES
- url String
  
  The test_url of the test-suite(.apk) file uploaded on BrowserStack.
- bundle_id String
  
  Bundle ID or the package name of the test-suite.
- version String
  
  Version code of the test-suite. The value is null.
- name String
  
  Name of your test-suite(.apk) file.
devices Array

Test execution details for each device in the build.

▶ SHOW VALUES
- device String
  
  The name of the device.
- os String
  
  By default, this is set to Android.
- os_version String
  
  OS version.
- sharding Boolean
  
  Indicates if the sharding was enabled for this build.
- sessions Array
  
  If sharding is disabled, each session is the execution of your test on a single device. Thus, each device will have a single session. If sharding is enabled, each session is the execution of a single shard on a single device. Thus, each device will have multiple sessions (one for each shard).
  
  ▶ SHOW VALUES
  - id String
    
    A unique session ID.
    Example: 09a018967ec8b2dc5dd391de1130f69463840039
  - status String
    
    Status of this session.
  - start_time String
    
    Timestamp at which the session execution started.
  - duration String
    
    Duration of the session execution.
  - testcases Object
    
    Test case execution summary for this session.
    
    ▶ SHOW VALUES
    - count Integer
      
      The total number of test-cases in this session.
    - status Object
      
      Count of test-cases by each status type.
      
      ▶ SHOW VALUES
      - passed Integer
        
        Total count of test cases with explicit test assertions that marks the test as passed.
      - failed Integer
        
        Total count of test cases with uncaught exceptions or explicit test assertions that marks test as failed.
      - skipped Integer
        
        Total count of test cases that never got executed by the test runner.
      - timedout Integer
        
        Total count of test cases that got timed-out.
      - error Integer
        
        Total count of test cases that errored due to an unanticipated issue on BrowserStack.
      - running Integer
        
        Total count of test cases that are currently under execution.
      - queued Integer
        
        Total count of test cases that are queued for execution.

List recent builds

GET /app-automate/espresso/v2/builds

Fetch 20 recent test builds sorted by timestamp. You can also filter builds by their project name.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/espresso/v2/builds"

# List builds using the project filter
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/espresso/v2/builds?project=SampleBuild"

project String

The project name of the build(s).
Example: Espresso_Test

Response attributes `200` `application/json`

Response

[
    {
        "id": "5c5ab4338cec13aeb78f7a6977344556ac00bccd6",
        "start_time": "2019-11-06 13:07:45 UTC"
    },
    {
        "id": "235ab7338cec13ae6b8f7a6977344556ac00bccd6",
        "start_time": "2020-06-04 07:43:49 UTC"
    }
]

Array

List of recent test builds sorted by timestamp

▶ SHOW VALUES
- id String
  
  Build ID.
- start_time String
  
  Timestamp at which the build execution was started.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Builds

Execute a build

Request parameters

app* String

testSuite* String

devices* Array

shards Object

numberOfShards* Integer

deviceSelection String

mapping Array

name* String

strategy* String

values* Array

project String

class String

package String

annotation String

size String

singleRunnerInvocation String

callbackURL String

projectNotifyURL String

networkLogs Boolean

deviceLogs Boolean

enableSpoonFramework Boolean

debugscreenshots Boolean

video Boolean

gpsLocation String

geoLocation String

networkProfile String

customNetwork String

language String

locale String

appStoreConfiguration Object

deviceOrientation Boolean

acceptInsecureCerts Boolean

uploadMedia Array

local Boolean

localIdentifier Boolean

idleTimeout Boolean

clearPackageData Boolean

buildTag String

disableAnimations Boolean

Response attributes 200 application/json

message String

build_id String

Get build status

Request parameters

buildID* String

Response attributes 200 application/json

id String

framework String

duration Integer

status Integer

input_capabilities Object

devices Array

project String

app String

testSuite String

start_time String

app_details Object

url String

bundle_id String

version String

name String

test_suite_details Object

url String

bundle_id String

version String

name String

devices Array

device String

os String

os_version String

sharding Boolean

sessions Array

id String

status String

start_time String

duration String

testcases Object

app^* String

testSuite^* String

devices^* Array

numberOfShards^* Integer

name^* String

strategy^* String

values^* Array

Response attributes `200` `application/json`

buildID^* String

Response attributes `200` `application/json`

Response attributes `200` `application/json`