Run your first test

XCTestPlans helps 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. BrowserStack App Automate supports XCTestPlans on a wide range of real iOS devices. This guide will help you run your first XCTestPlan on BrowserStack.

1. Setup

1. You will need a BrowserStack username and access-key. To obtain your access credentials, sign up for a free trial or purchase a plan.

2. Upload your app

Upload your iOS app (.ipa) file to BrowserStack servers using a REST API request.

The following sample cURL command shows how to upload an app:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/app" \
-F "file=@/path/to/app/file/app-debug.ipa"

A sample response for the request is as follows:

{
    "app_name":"app-debug.ipa",
    "app_url":"bs://j3c874f21852ba57957a3fdc33f47514288c4ba4",
    "app_version":"1.0",
    "app_id":"j3c874f21852ba57957a3fdc33f47514288c4ba4",
    "uploaded_at":"2022-05-13 06:16:49 UTC",
    "expiry":"2022-06-12 06:16:49 UTC"
}

The value of the app_url parameter in the response is used to specify the application under test when you run XCTestPlan.

3. Upload your test suite and xctestrun file

Upload your test suite .app file and .xctestrun file bundled together as a .zip file to BrowserStack servers using a REST API request.

The following sample cURL command shows how to upload a test suite:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/test-suite" \
-F "file=@/path/to/test-suite/file/and/xctestrun/file/SampleXCTestPlan.zip"

A sample response for the request is as follows:

{
    "test_suite_name":"SampleXCTestPlan.zip",
    "test_suite_url":"bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
    "test_suite_id":"f7c874f21852ba57957a3fdc33f47514288c4ba4",
    "uploaded_at":"2022-05-13 06:17:50 UTC",
    "expiry":"2022-06-12 06:17:50 UTC",
    "framework":"xcuitest"
}

The value of the test_suite_url parameter in the response is used to specify the test suite when you run XCTestPlan.

The file structure of your zipped file can be visually represented as below:
    ├── `testSuite.zip`
        └── test suite runner `.app` file
        └── `.xctestrun` file

4. Execute XCUI tests

After you upload the app and test suite to BrowserStack servers, send an API request to start the test execution as shown in the following sample cURL request:

A sample response for the request is as follows:

{
    "message":"Success",
    "build_id":"4d2b4deb810af077d5aed98f479bfdd2e64f36c3"
}

The build_id is used to uniquely identify your build in App Automate.

5. View test results

After you start the test-suite execution using the REST API request, visit your App Automate dashboard to view your test results, debugging logs, and overall test details. You can also use API requests to view test results. You can also view the details about your tests execution on BrowserStack using the XCresult bundle which is by default generated with XCTestPlan execution. You can access the result bundle at session level using the REST API.

REST API endpoint:

GET /xcuitest/v2/builds/{build_id}/sessions/{session_id}/resultbundle

Example cURL request:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X GET "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/builds/a40696273a8d1467f81f5bb63869be425ec336d6/sessions/78509dae7d5d606278bf4203a569406e27960806/resultbundle" --output result.zip

The API will have a binary response so you can save it to an empty result.zip file on your local machine. Once the result bundle has been generated, you can unzip the folder and view the report in a compatible Xcode editor.

Related topics

• Manage your uploaded app or test suite using our upload app REST API and upload test suite REST API.

• Use the get app API endpoint and list test suites API endpoint to list your recently uploaded apps and test suites.

• Delete your uploaded app or test suite using the delete app API endpoint and delete test suite API endpoint.