Table of Contents
APP AUTOMATE API

Builds

Each build represents an execution of your XCUI 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/xcuitest/v2/build

Start the execution of a new build on BrowserStack. While making a request, you must specify the application under test, XCUI 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/xcuitest/v2/build" \
-d {"app": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3", "testSuite": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1","project" : "SampleBuild" "devices": ["iPhone X-11", "iPhone XS-13"]} \
-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 XCUI test-suite. Use test_url or custom_id or shareable_id of a previously uploaded test-suite. Learn more about testSuite API

  • devices* Array[String]

    List of devices to execute your tests on. Learn more about devices API
    Example: ["iPhone X-11", "iPhone 8-11"]

  • shards Object

    Split an XCUI 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[Object]

      Details of how test sharding should be handled. Each shard should have its corresponding mapping. This is a required parameter to handle the test sharding.

      SHOW VALUES
      • name* String

        Unique identifier for each shard.
        Example: 0, 1

      • strategy* String

        Strategy for using the shards. The possible values:

        Possible Value Description
        only-testing Allows you to define the classes or tests to be executed in a particular shard.
        skip-testing Allows you to define the classes or tests to be skipped in a particular shard.
      • values* Array[String]

        Class/Test names depending on the type of strategy selected.
        Example: ["SampleXCUITests/testAlert", "SampleXCUITests/testText"] for only-testing 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.

  • only-testing String

    Filter test cases by selected classes or tests in the test-suite. Specify a list of fully qualified class/test name(s).
    Example: ["SampleXCUITests/testAlert", "SampleXCUITests/testText"]

  • skip-testing String

    Filter test cases by skipping selected classes or tests in the test-suite. Specify a list of fully qualified class/test name(s).
    Example: ["SampleXCUITests/testAlert"]

  • 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.

  • setEnvVariables Object

    Use this parameter to pass custom key and value pairs that can be accessed as environment variables by your XCUI test-suite. Acceptable character limit for the key is 30 and for the value is 100 characters.
    Example: {"key1":"value1", "key2":"value2"}

  • 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) for your test execution. By default, its set to false.

  • debugscreenshots Boolean

    Enable capture of screenshots for your XCUI tests. By default, its set to false.

  • 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

  • resignApp Boolean

    Disable re-signing on iOS devices to test features such as push notifications and universal links. By default, its set to true.

  • language String

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

  • locale Boolean

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

  • deviceOrientation Boolean

    Set the screen orientation of the mobile device.
    Values: portrait, landscape. Default: 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.

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/xcuitest/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/xcuitest/v2/builds/5c5ab4338cec13aeb78f7a6977344556ac00bccd6"
  • buildID* String

    Unique build ID for your XCUITest build execution.
    Example: 57dd68e05f76ca3c9c0d4600fd78ae064fa537bb

Response Attributes 200 application/json

Response

{
    "id": "5c5ab4338cec13aeb78f7a6977344556ac00bccd6",
    "framework": "xcuitest",
    "duration": 83,
    "status": "failed",
    "input_capabilities": {
        "devices": [
            "iPhone X-11.0",
            "iPhone 8-11.0"
        ],
        "project": "SampleBuild",
        "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.ipa"
    },
    "test_suite_details": {
        "url": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1",
        "bundle_id": "com.sample.browserstack.samplecalculator.test",
        "version": "",
        "name": "app-debugTest.ipa"
    },
    "devices": [
        {
            "device": "iPhone X",
            "os": "ios",
            "os_version": "11.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": "iPhone 8",
            "os": "ios",
            "os_version": "11.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
                    }
                }
            }]
        }
    ]
}
  • id String

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

  • framework String

    Name of the automation framework. This is set to XCUITest.

  • 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 viewing test results

  • 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: ["iPhone X-11.0", "iPhone 8-11.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

  • 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(.ipa) file uploaded on BrowserStack.

    • bundle_id String

      Bundle ID of the app.

    • version String

      Version code of the app.

    • name String

      Name of your app(.ipa) file.

  • test_suite_details Object

    Details about the test-suite uploaded on BrowserStack.

    SHOW VALUES
    • url String

      The test_url of the XCUI test-suite(.zip) 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 XCUI test-suite(.zip) 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 iOS.

    • os_version String

      iOS 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-suite 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: sdfnk324skdjf234jkldfs234sdfl1231sd

      • 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/xcuitest/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 POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/builds"

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

    The project name of the build(s).
    Example: XCUI_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.

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






Thank you for your valuable feedback