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