Skip to main content
Table of Contents


Xcode test plans help us manage Unit/UI tests using XCode with multiple configurations and settings. To test XCTestPlan on Browserstack, the process is different from that of running XCUI Tests. While the app is uploaded as in case of XCUI Tests, the next steps change.

Upload an app

In order to test your native and hybrid apps on BrowserStack using XCTestplans, you also need to upload your test-suite (.zip file) to BrowserStack servers. Use our REST API endpoints to upload and manage your test-suites on BrowserStack.

Upload a bundled test-suite and xctestrun file

    ├── `` <br>
      └── test suite runner `.app` file<br>
      └── `.xctestrun` file<br>

While the request and response structure remains identical to XCUI Tests test-suite,
the test suite .zip consists of a bundled test .app file and .xctestrunfile.

The file structure of your zipped file can be visually represented as shown here.

Execute a build

POST /app-automate/xcuitest/v2/xctestrun-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


-X POST "" \
-d {"app": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3", "testSuite": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1","project" : "SampleBuild" "devices": ["iPhone 14-16"]} \
-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* Array[String]

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

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

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

  • debugscreenshots Boolean

    Enable capture of screenshots for your Xcode 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 String

    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.

  • 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

Response Attributes 200 application/json


    "message": "Success",
    "build_id": "5c5ab4338cec13aeb78f7a6977344556ac00bccd6"
  • message String

    Status of the request.

  • build_id String

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

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