Execute your XCUITest tests on Apple TV

Start builds on dedicated Apple TV devices in your group using the REST API, and see which build parameters are supported.

After uploading your tvOS app and XCUITest test suite, you’re ready to run your tests on Apple TV devices. Execute your tests using the REST API. The request is the same as for iOS devices, except that you pass an Apple TV device in the devices parameter and set dedicatedDevice to true.

Prerequisites

• You need a BrowserStack username and access-key. To obtain your access credentials, sign up for a free trial or purchase a plan.
• You need the app_url of your tvOS app. To get it, upload your app.
• You need the test_suite_url of your XCUITest test suite. To get it, upload your test suite.

Run tests on any dedicated Apple TV in your group

Apple TV devices aren’t part of the public device catalog, so every build request must set dedicatedDevice to true. The following sample cURL request runs your XCUITest tests on any Apple TV 4K device running tvOS 26.2 that’s dedicated to your group:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/build" \
-d '{"devices": ["Apple TV 4K-26.2"], "app": "<app_url>", "testSuite": "<test_suite_url>", "dedicatedDevice": true}' \
-H "Content-Type: application/json"

In the above example, the devices parameter specifies the Apple TV device to test your app on. The app parameter specifies the tvOS app uploaded to BrowserStack. The testSuite parameter specifies the XCUITest test suite uploaded to BrowserStack. The dedicatedDevice parameter runs the build on a device dedicated to your group.

The API returns a response similar to the following:

{
    "message": "Success",
    "build_id": "741c219db523cb51d4cdf35723ce3bfc592fb74a"
}

The build_id returned in the API response uniquely identifies your test execution. Each build is an execution of your XCUITest test suite on all selected devices. To check the build status and per-test results, use GET /app-automate/xcuitest/v2/builds/<build-id>.

Run tests on a specific dedicated Apple TV device

To pin your build to one specific Apple TV device in your group, also pass the device ID in the optional deviceId parameter:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/build" \
-d '{"devices": ["Apple TV 4K-26.2"], "app": "<app_url>", "testSuite": "<test_suite_url>", "dedicatedDevice": true, "deviceId": "<device_id>"}' \
-H "Content-Type: application/json"

Navigate your app using the remote control

Apple TV apps don’t support touch input. Your tests navigate the app through the focus engine using XCUIRemote. For example, XCUIRemote.shared.press(.select) presses the select button. You can press the .up, .down, .left, .right, .select, .menu, and .playPause buttons.

These commands run inside your test on the Apple TV device, so they work on BrowserStack without any additional configuration.

Supported build parameters

You can use the following build parameters in a build request for Apple TV devices. They work the same way as for iOS devices:

Unsupported build parameters

The following build parameters and features that are available for iOS devices aren’t supported on Apple TV devices:

• deviceOrientation
• language and locale
• shards
• gpsLocation
• timezone
• networkProfile and customNetwork
• uploadMedia
• otherApps
• appProfiling
• dynamicTests
• enableBiometric
• enableCameraVideoInjection

Related topics

• Upload apps for XCUITest testing on Apple TV.
• Upload test suites for XCUITest testing on Apple TV.
• View all build parameters in the XCUITest builds REST API reference.