Getting Started
Introduction
Appium scripts can be used to automate testing on TV Labs devices through the TV Labs Appium proxy at appium.tvlabs.ai. This page explains how to use the TV Labs Appium proxy to run Appium scripts on TV Labs devices.
What to expect:
- ⏱️ Duration: 10-15 minutes
- 🎯 Audience: Developers interested in using Appium for automated testing on the TV Labs platform
- 🧠 Outcome: Understanding how to use Appium for automated testing on the TV Labs platform
Also see: The Appium documentation provides examples for writing Appium scripts in various languages.
Overview
The TV Labs Appium proxy serves as a gateway to the TV Labs platform for Appium scripts. It enables users to run Appium-based test scripts on TV Labs devices from a local machine, CICD pipeline, or other environments. The proxy provides a single endpoint for device matching, application sideloading, and Appium server session management. Once a session starts, you can view a live stream of the device in the TV Labs sessions dashboard, along with Appium server logs and other session assets and information. Previous sessions are also accessible on this page.
Platform support is a work in progress. Please see Platforms for the list of currently supported platforms.
Connection Information
To use the TV Labs Appium proxy, you will first need to generate an API key from the API Keys page. This key will be used to authenticate requests to the TV Labs Appium proxy, and will tie the session to your TV Labs account.
After generating an API key, set your web driver endpoint to https://appium.tvlabs.ai:4723 and add the API key to the Authorization header as a Bearer token.
Example for NodeJS WebDriverIO script
const apiKey = "YOUR_API_KEY_HERE"
const webDriverOptions = {
hostname: "appium.tvlabs.ai",
port: 4723,
protocol: "https",
headers: {
Authorization: `Bearer ${apiKey}`
},
capabilities: { ... }
}
The minimal required node version for the TV Labs Appium proxy is Node.js 20. If you are using an older version of Node.js, you will need to upgrade to at least version 20 to use the TV Labs Appium proxy.
If you're not sure which Node.js version you're using, we recommend to add the following line to your script to log the version instead of using the node -v command in the terminal, because the terminal may use a different version of Node.js than your script:
console.log(`Node.js version: ${process.version}`);
Capabilities
For information on available Appium capabilities, please see the Capabilities page.
Versions
The TV Labs platform currently runs Appium Server 2.19.0.
For specific driver versions, see the Platforms section below.
Platforms
The following platforms are supported by the TV Labs Appium proxy:
| Platform | platform_key | platform_os_variant | Appium Driver | Driver Version | Device Types | Build Format |
|---|---|---|---|---|---|---|
| Roku | roku | - | appium-roku-driver | 2.7.0 | Television, Set-Top Box | .zip |
| WebOS (LG) | web_os | - | appium-lg-webos-driver | 0.5.2 | Television | .ipk |
| Tizen TV (Samsung) | tizen | - | appium-tizen-tv-driver | 0.18.2 | Television | .wgt |
| Apple TV | tv_os | - | appium-xcuitest-driver | 9.9.1 | Set-Top Box | .ipa |
| iOS (any) | ios | - | appium-xcuitest-driver | 9.9.1 | Tablet, Phone | .ipa |
| iPhone | ios | iphone_os | appium-xcuitest-driver | 9.9.1 | Phone | .ipa |
| iPad | ios | ipad_os | appium-xcuitest-driver | 9.9.1 | Tablet | .ipa |
| SmartCast (Vizio) | smartcast | - | appium-smartcast-driver | 1.0.4 | Television | .zip |
| Android Mobile (any) | android_mobile | - | appium-uiautomator2-driver | 4.2.4 | Tablet, Phone | .apk |
| Galaxy Phone | android_mobile | galaxy | appium-uiautomator2-driver | 4.2.4 | Phone | .apk |
| Pixel Phone | android_mobile | pixel | appium-uiautomator2-driver | 4.2.4 | Phone | .apk |
| Fire Tablet | android_mobile | fire | appium-uiautomator2-driver | 4.2.4 | Tablet | .apk |
| Android TV (any) | android_tv | - | appium-uiautomator2-driver | 4.2.4 | Television, Set-Top Box | .apk |
| Stock Android TV | android_tv | stock | appium-uiautomator2-driver | 4.2.4 | Television, Set-Top Box | .apk |
| Google TV | android_tv | google_tv | appium-uiautomator2-driver | 4.2.4 | Television, Set-Top Box | .apk |
| Fire TV | android_tv | fire_tv | appium-uiautomator2-driver | 4.2.4 | Television, Set-Top Box | .apk |
When uploading a build to be used with Appium via the tvlabs upload command, the build will need to be in an expected format for the platform. Please view the documentation provided by each platform to see how to prepare the build.
On platforms where the application package needs to be signed, uploaded application packages will be re-signed using TV Labs certificates before sideloading. It is not necessary to sign the package before uploading.
ChromeDrivers
For Appium drivers that use ChromeDriver to perform automation on the device, the ChromeDriver will be automatically selected based on the version of Chromium browser that is running on the device.
The version of ChromeDriver configured for a device may not always be an exact match to the version of Chromium browser running on the television if there is not a build available, but the closest compatible version will be selected.
Some devices do not support ChromeDriver, and the use of Appium automation features will be limited, see the specific drivers documentation for more information.
Use the chromedriver_version field in your constraint query to ensure that a target device is compatible with ChromeDriver. Read more about writing constraint queries in the device targeting documentation.
| Query | Description |
|---|---|
chromedriver_version:* | Match any device with a ChromeDriver version |
chromedriver_version>=120.0.0.0 | Match any device with a ChromeDriver version 120.0.0.0 or higher |
chromedriver_version:120.* | Match any device with a ChromeDriver that has major version 120 |
Screenshots
On the TV Labs platform, Appium screenshots are not captured using the underlying driver. Instead, the screenshot request is intercepted and uses the device video capture to grab a screenshot. What this means in practice is that Appium users are able to capture screenshots on any device using any driver, regardless of whether or not the driver supports it.
One example of how this is useful: on Roku the driver can only capture the screen when a sideloaded development application is running. This is a limitation of the underlying ECP protocol that the Roku Appium driver uses. However, on the TV Labs platform, you can capture screenshots outside the development app as well.
Response Headers
The TV Labs Appium proxy includes custom response headers that provide additional metadata about the session and video recordings.
Video Timing Headers
All Appium responses include the following headers that indicate the video timing for the request:
x-video-start-time: The video timestamp (in milliseconds) when the request was receivedx-video-end-time: The video timestamp (in milliseconds) when the response was sent
These headers can be used to correlate Appium commands with specific moments in the session video recording, which is particularly useful for debugging and analysis.
To access these headers, you will need to intercept them from your HTTP client.
WebdriverIO Service
To better support the use case of running Appium tests on the TV Labs platform with the WebdriverIO framework, we have created the @tvlabs/wdio-service WebdriverIO service package.
The @tvlabs/wdio-service package uses a websocket to connect to the TV Labs platform before an Appium session begins, logging events relating to TV Labs session creation as they occur. This offloads the responsibility of creating the TV Labs session from the POST /session Webdriver endpoint, leading to more reliable session requests and creation. Additionally, the service supports build uploads and provides better logging in the form of request ID tracing.
To use @tvlabs/wdio-service, install the package with npm install @tvlabs/wdio-service or your favorite package manager, and add it to your WebdriverIO test runner configuration.
// wdio.conf.js
export const config = {
// ...
services: [
[
TVLabsService,
{
apiKey: process.env.TVLABS_API_KEY,
buildPath: process.env.TVLABS_BUILD_PATH,
},
],
],
// ...
};
The service can be used with the remote API as well, see the package README and example for more information.
Once the service is installed, you can observe logs in the test runner output relating to the TV Labs session creation process before your Appium test script begins.
[0-0] 2025-03-28T17:15:44.459Z INFO wdio-tvlabs-service: Requesting TV Labs session
[0-0] 2025-03-28T17:15:45.461Z INFO wdio-tvlabs-service: Received session request ID: 534465. Waiting for a match...
[0-0] 2025-03-28T17:15:45.872Z INFO wdio-tvlabs-service: Session request 534465 matching...
[0-0] 2025-03-28T17:15:45.873Z INFO wdio-tvlabs-service: Session request 534465 filled: https://tvlabs.ai/app/sessions/b936e307-8280-4949-8d13-ac0da83b1f5e
[0-0] 2025-03-28T17:15:45.874Z INFO wdio-tvlabs-service: Waiting for device to be ready...
[0-0] 2025-03-28T17:15:52.301Z INFO wdio-tvlabs-service: Session b936e307-8280-4949-8d13-ac0da83b1f5e ready!