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 configures the state of the device before your test script runs. It accepts a map of one or more of the settings described below, which can be combined in a single map. Settings you omit leave the device unchanged.
Each setting lists the platforms it applies to. Requesting one on a platform that doesn't have it fails the session with a 400 response code rather than starting a session without it, so a capability set shared across platforms should only carry the settings every one of them supports.
Use case: Start a session from a known device state, such as:
- Verifying buffering and loading behavior on low-bandwidth connections
- Reproducing playback issues reported on slow networks
- Validating that streaming quality degrades gracefully
- Ensuring App Tracking Transparency prompts are disabled before your test runs
- Exercising your application with VoiceOver turned on
Validation: Must be a map containing one or more of the allow_apps_to_ask_to_track, network, and voice_over keys. Any other key is rejected.
App Tracking Transparency (Apple TV and iPhone only)
Type: boolean
Sets the device's App Tracking Transparency toggle. Set it to false to turn the setting off, or true to turn it on.
Apple words this setting differently on each platform, so both keys are accepted on both platforms:
| Key | Platform | Location on the device |
|---|---|---|
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" |
Both keys may be given in the same request only when they carry the same value. Conflicting values are rejected.
Example:
Turn App Tracking Transparency off on an Apple TV:
const capabilities = {
'tvlabs:device_initial_posture': {
allow_apps_to_ask_to_track: false,
},
};
The same on an iPhone, using Apple's iOS wording:
const capabilities = {
'tvlabs:device_initial_posture': {
allow_apps_to_request_to_track: false,
},
};
Network Throttling
Type: map
Limits the device's network bandwidth for the session. network takes a single throttle key, which accepts an up (upload) and a down (download) rate. At least one of the two is required, and each rate is a number in mbits / second, greater than 0 and at most 1000. A direction you omit is left unthrottled.
The throttle is applied once your build is installed, so the install is not slowed down by it, and stays in effect until the session ends. To change the throttle during a session, use the network throttling execute methods.
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,
},
},
},
};
VoiceOver (Apple TV only)
Type: boolean
Sets the device's VoiceOver toggle, found under Settings → Accessibility → VoiceOver. Set it to true to turn VoiceOver on, or false to turn it off.
TV Labs applies the setting through the device's Settings app, and returns the device to the home screen before your test script runs.
Example:
Start the session with VoiceOver turned on:
const capabilities = {
'tvlabs:device_initial_posture': {
voice_over: true,
},
};
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 |