Capabilities
The TV Labs Appium proxy allows you to specify capabilities to configure your Appium session. Any capabilities that are provided by Appium or provided by the platform-specific driver will be available on the condition that they are not explicitly set by the proxy.
Capabilities which are necessary to run the session (like platformName, appium:automationName, device connection configuration, etc.) will be automatically set by the proxy. See the full list of overridden capabilities in the Capability Overrides section below.
TV Labs Specific Capabilities
These capabilities are non-standard and are only available when running your script through the TV Labs Appium proxy.
tvlabs:constraints (required)
The tvlabs:constraints capability matches your test script to a device on the TV Labs platform. It accepts a constraint query string, e.g. platform_key:ios. Read more about writing a constraint query in the device targeting documentation.
tvlabs:build (optional)
The tvlabs:build capability specifies a TV Labs build ID for sideloading onto the device before an Appium session starts. If the driver does not require a build ID, then you can omit this capability.
You can obtain a build ID from the App management page, or through the tvlabs upload command, which will upload your application to a secure blob storage:
❯ tvlabs upload -i ./path/to/application.zip
e6f2a4b1-8160-4147-8493-5e3aa18ddcc8
tvlabs:auto_launch_build (optional, Tizen TV only)
For Tizen TV sessions, set tvlabs:auto_launch_build to false to install or validate the selected build without launching it when the Appium session starts. The default is true.
When this capability is disabled, launch the app later with the tizen: activateApp execute method. Pass debug: true to tizen: activateApp if the session needs ChromeDriver-backed automation after launch.
tvlabs:teleport_region (optional)
The tvlabs:teleport_region capability allows you to specify a dynamic teleport region for the Appium session. When the session starts, the device will have an IP address that exists in the specified region. If no teleport region is specified, the device will be in the default region (New York, USA).
A list of available teleport regions can be found by requesting the teleport regions API endpoint with your API key:
curl -H 'Authorization: Bearer <api_key>' https://tvlabs.ai/api/v1/teleport/regions
{"data": [...]}
If you don't have an API key, you can create one on the API Keys page.
tvlabs:match_timeout (optional)
The tvlabs:match_timeout capability defines the maximum time (in seconds) to wait for a device matching your tvlabs:constraints. If no device is found within this timeout, the session fails with a 400 response code. Set this value lower for fast failures or higher to allow more matching time. The default is 300 seconds (5 minutes) when making a request through the TV Labs Appium proxy endpoint, or 900 seconds (15 minutes) when making a request through the TV Labs WebDriverIO service.
tvlabs:device_timeout (optional)
The tvlabs:device_timeout capability defines the maximum time (in seconds) to wait for a matched device to become ready. If the device isn't ready within this timeout, the session fails with a 400 response code. The default is 60 seconds, which should be sufficient for most use cases.
Many webdriver clients have client-side configuration for timeouts, for example, webdriverio provides a connectionRetryTimeout configuration option that defaults to 2 minutes. If this value is set too low, the request may timeout before the TV Labs device has been matched to the request, or before the device has had time to warm up. To avoid this, configure your webdriver client request timeout to be greater than the sum of tvlabs:match_timeout and tvlabs:device_timeout capabilities.
tvlabs:licensing_timeout (optional)
The tvlabs:licensing_timeout capability defines the maximum time (in seconds) to wait for a license to become available. If no license is available within this timeout, the session fails with a 400 response code. The default value is 300 seconds (5 minutes).
tvlabs:session_id (optional)
If a TV Labs session has already been created, the tvlabs:session_id capability can be provided to skip TV Labs session creation on the WebDriver New Session command. This is used by the @tvlabs/wdio-service WebdriverIO service to provide a pre-created session, and is not normally provided by the end user.
tvlabs:log_network (optional)
The tvlabs:log_network capability enables network logging for the Appium session. See the Network Capture page for more information.
tvlabs:correlation_id (optional)
The tvlabs:correlation_id capability allows you to specify a string identifier that is shared across multiple sessions from the same test run. This enables grouping and filtering of related sessions. For example, if a single test suite creates 20 sessions against different devices, they can all share the same correlation ID.
Use case: When running a test suite that creates multiple Appium sessions, you can tag all sessions with the same correlation_id (e.g., "pipeline-run-abc-123") to:
- View all sessions from a particular test run
- Filter sessions by correlation id
Validation: Must be a string with a maximum length of 255 characters.
Example:
const capabilities = {
'tvlabs:build': 'build-uuid-here',
'tvlabs:constraints': { platform_key: 'roku' },
'tvlabs:correlation_id': 'pipeline-run-abc-123',
};
tvlabs:metadata (optional)
The tvlabs:metadata capability allows you to attach arbitrary key-value pairs to a session for tracking purposes. This is useful for storing test case IDs, environment information, build numbers, priority levels, or any other custom tracking data. The metadata will be included in session API responses and displayed on the session details page in the TV Labs dashboard.
Use case: When running tests, you can include metadata such as:
- Test case identifiers
- Environment names (staging, production, etc.)
- Build numbers or versions
- Test priority levels
- Feature flags or experimental indicators
- Any other custom tracking information
Validation: Must be a flat map (object) with:
- String keys
- Values that are strings, numbers, or booleans
- No nested objects or arrays
- Maximum of 20 items
- String values limited to 128 characters
Example:
const capabilities = {
'tvlabs:build': 'build-uuid-here',
'tvlabs:constraints': { platform_key: 'roku' },
'tvlabs:correlation_id': 'pipeline-run-abc-123',
'tvlabs:metadata': {
testCaseId: 'TC-4521',
testSuite: 'smoke-tests',
environment: 'staging',
buildNumber: '42',
priority: 'high',
},
};
tvlabs:device_initial_posture (optional)
The tvlabs:device_initial_posture capability shapes the device's initial state before the session starts. It supports network throttling and, on Apple TV and iPhone, the App Tracking Transparency privacy setting.
Use case: Exercise your application under a specific device posture, such as:
- Verifying buffering and loading behavior on low-bandwidth connections
- Reproducing playback issues reported on slow networks
- Validating that streaming quality degrades gracefully
- Enforcing that App Tracking Transparency prompts are disabled (or enabled) before your test runs
Validation: Must be a map with one or both of the following top-level keys:
networkshapes network conditions as{ throttle: { … } }.throttlemust specify at least one ofup(upload) ordown(download); no other keys are allowed, and each rate is a number in mbit/s, greater than0and at most1000.allow_apps_to_ask_to_track(alias:allow_apps_to_request_to_track) is a boolean that forces the device's App Tracking Transparency (ATT) toggle before the session. Setfalseto turn it off,trueto turn it on. Omit the key to leave the device's current setting unchanged.
App Tracking Transparency: one setting, two names
Apple worded this toggle differently on each platform, so TV Labs accepts both spellings on both platforms. They are aliases for exactly the same setting; use whichever matches the device you are testing.
| Key | Platform that uses this wording | Where the toggle lives |
|---|---|---|
allow_apps_to_ask_to_track | Apple TV (tvOS) | Settings → General → Privacy → Tracking → "Allow Apps to Ask to Track" |
allow_apps_to_request_to_track | iPhone (iOS) | Settings → Privacy & Security → Tracking → "Allow Apps to Request to Track" |
Either key works on either platform: allow_apps_to_ask_to_track on an iPhone and allow_apps_to_request_to_track on an Apple TV both do the right thing. Giving both keys is allowed only when they carry the same value; conflicting values are rejected rather than silently resolved.
The setting is applied only on Apple TV and iPhone. It is ignored on every other platform, so leaving it in a shared capability set is safe.
Example:
Throttle both directions:
const capabilities = {
'tvlabs:device_initial_posture': {
network: {
throttle: {
up: 10,
down: 100,
},
},
},
};
Throttle a single direction by omitting the other:
const capabilities = {
'tvlabs:device_initial_posture': {
network: {
throttle: {
down: 5,
},
},
},
};
Turn App Tracking Transparency off on an Apple TV, where Apple calls it "Allow Apps to Ask to Track" (this can be combined with a network throttle):
const capabilities = {
'tvlabs:device_initial_posture': {
allow_apps_to_ask_to_track: false,
},
};
The same thing on an iPhone, using Apple's iOS wording. allow_apps_to_ask_to_track: false would be equivalent:
const capabilities = {
'tvlabs:device_initial_posture': {
allow_apps_to_request_to_track: false,
},
};
Capability Overrides
This section describes the capabilities that the TV Labs Appium proxy configures automatically for each platform. Any capabilities not mentioned here are overridable. Capabilities that will always be overridden regardless of the target platform include platformName and appium:automationName. See platform specific capability overrides below.
Roku (appium-roku-driver)
| Capability | Description | Overridable? |
|---|---|---|
appium:app | The application ID to launch for the session (determined by tvlabs:build) | No |
appium:rokuHost | The target device host | No |
appium:keyCooldown | The cooldown time for the remote control key press, defaults to 1000 | Yes |
appium:rokuUser | The username for the Roku device | No |
appium:rokuPass | The password for the Roku device | No |
appium:rokuEcpPort | The port for the Roku device | No |
appium:rokuWebPort | The port for the Roku device | No |
Tizen TV (appium-tizen-tv-driver)
| Capability | Description | Overridable? |
|---|---|---|
appium:appPackage | The application package ID to launch for the session (determined by tvlabs:build) | No |
appium:deviceName | The device name to use for the session (set to the target device IP) | No |
appium:chromedriverExecutable | The configured ChromeDriver. Uses the newest available version that is compatible with the device. | No |
appium:rcToken | The pre-paired remote control token | No |
appium:sdbExecTimeout | The timeout for sdb execution, defaults to 30000 | Yes |
appium:sdbExecRetryCount | The number of times to retry sdb execution, defaults to 2 | Yes |
The ChromeDriver session attaches to the application's Chromium runtime when the session starts. Calling terminateApp (or otherwise closing the app) during a session will sever the ChromeDriver connection. See ChromeDriver session lifecycle for details.
WebOS (appium-lg-webos-driver)
| Capability | Description | Overridable? |
|---|---|---|
appium:appId | The application package ID to launch for the session (determined by tvlabs:build) | No |
appium:deviceName | The device name to use for the session | No |
appium:chromedriverExecutable | The configured ChromeDriver. Uses the newest available version that is compatible with the device. | No |
appium:debuggerPort | The port for the WebOS debugger | No |
appium:websocketPort | The port for the WebSocket connection | No |
appium:websocketPortSecure | The port for the secure WebSocket connection | No |
appium:useSecureWebsocket | Whether to use a secure WebSocket connection, always true | No |
appium:autoExtendDevMode | Renew the developer mode token. This is handled internally by TV Labs | No |
The ChromeDriver session attaches to the application's Chromium runtime when the session starts. Calling terminateApp (or otherwise closing the app) during a session will sever the ChromeDriver connection. See ChromeDriver session lifecycle for details.
SmartCast (appium-smartcast-driver)
| Capability | Description | Overridable? |
|---|---|---|
appium:app | The application URL to launch for the session (determined by tvlabs:build) | No |
appium:deviceHost | The host for the SmartCast device | No |
appium:chromedriverExecutable | The configured ChromeDriver. Uses the newest available version that is compatible with the device. | No |
appium:deviceRemotePort | The remote control protocol port | No |
appium:deviceDebugPort | The debugger port for the SmartCast device | No |
appium:remoteToken | The pre-paired remote control token | No |
The ChromeDriver session attaches to the application's Chromium runtime when the session starts. Calling terminateApp (or otherwise closing the app) during a session will sever the ChromeDriver connection. See ChromeDriver session lifecycle for details.
tvOS / iOS (appium-xcuitest-driver)
| Capability | Description | Overridable? |
|---|---|---|
appium:platformVersion | The platform version of the target device | No |
appium:bundleId | The bundle identifier of the target application (determined by tvlabs:build) | No |
appium:deviceName | The name of the target device | No |
appium:udid | The UDID of the target device | No |
appium:xcodeOrgId | xcodeOrgId used to load the web driver agent | No |
appium:xcodeSigningId | xcodeSigningId used to load the web driver agent | No |
appium:useNewWDA | Whether to use a new WDA instance for each session, always true | No |
appium:fullReset | Whether to perform a full reset of the device before the session starts, always false. This is handled internally by TV Labs. | No |
Android Mobile / TV (appium-uiautomator2-driver)
| Capability | Description | Overridable? |
|---|---|---|
appium:appPackage | The package identifier of the target application (determined by tvlabs:build) | No |
appium:appActivity | The main activity to launch for the session (determined by tvlabs:build) | Yes |
appium:deviceName | The device name to use for the session | No |