Skip to main content

Getting Started

Introduction​

TV Labs runs an Appium compatible WebDriver server at appium.tvlabs.ai, so you can automate testing on TV Labs devices from any Appium or WebDriver client. This page explains how to connect to it and run your scripts on TV Labs devices.

What to expect:

  • ⏱️ Duration: 10-15 minutes
  • 🎯 Audience: Developers interested in using WebDriver for automated testing on the TV Labs platform
  • 🧠 Outcome: Understanding how to use WebDriver for automated testing on the TV Labs platform

Also see: Because the server is Appium compatible, the Appium documentation's examples for writing scripts in various languages apply to TV Labs as well.

Overview​

The TV Labs WebDriver server is the gateway to the TV Labs platform for WebDriver scripts. It enables users to run test scripts written for Appium or any other WebDriver client on TV Labs devices from a local machine, CICD pipeline, or other environments. The server provides a single endpoint for device matching, application sideloading, and session management. Once a session starts, you can view a live stream of the device in the TV Labs sessions dashboard, along with driver logs and other session assets and information. Previous sessions are also accessible on this page.

Connection Information​

To use the TV Labs WebDriver server, 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 WebDriver server, and will tie the session to your TV Labs account.

After generating an API key, set your WebDriver 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: { ... }
}
warning

The minimal required node version for the TV Labs WebDriver server 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 WebDriver server.

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 capabilities, please see the Capabilities page.

Versions​

Platforms that use an Appium driver run on Appium Server 2.19.0.

For specific driver versions, see the Platforms section below.

Platforms​

The following platforms are supported by the TV Labs WebDriver server:

Platformplatform_keyplatform_os_variantDriverDriver VersionDevice TypesBuild Format
Rokuroku-TV Labs WebDriver-Television, Set-Top Box.zip
WebOS (LG)web_os-TV Labs WebDriver-Television.ipk
Tizen TV (Samsung)tizen-TV Labs WebDriver-Television.wgt
Apple TVtv_os-TV Labs WebDriver-Set-Top Box.ipa
iOS (any)ios-TV Labs WebDriver-Tablet, Phone.ipa
iPhoneiosiphone_osTV Labs WebDriver-Phone.ipa
iPadiosipad_osTV Labs WebDriver-Tablet.ipa
SmartCast (Vizio)smartcast-TV Labs WebDriver-Television.zip
Skyentertainment_osskyTV Labs WebDriver-Television, Set-Top Box-
Xumoentertainment_osxumoTV Labs WebDriver-Television, Set-Top Box-
Android Mobile (any)android_mobile-appium-uiautomator2-driver4.2.9Tablet, Phone.apk
Galaxy Phoneandroid_mobilegalaxyappium-uiautomator2-driver4.2.9Phone.apk
Pixel Phoneandroid_mobilepixelappium-uiautomator2-driver4.2.9Phone.apk
Fire Tabletandroid_mobilefireappium-uiautomator2-driver4.2.9Tablet.apk
Android TV (any)android_tv-TV Labs WebDriver-Television, Set-Top Box.apk
Stock Android TVandroid_tvstockTV Labs WebDriver-Television, Set-Top Box.apk
Google TVandroid_tvgoogle_tvTV Labs WebDriver-Television, Set-Top Box.apk
Fire TVandroid_tvfire_tvTV Labs WebDriver-Television, Set-Top Box.apk
Google Chromegoogle_chrome-ChromedriverMatches browser versionDesktop-
Firefoxfirefox-GeckodriverMatches browser versionDesktop-
Safarisafari-SafaridriverMatches browser versionDesktop-

When uploading a build to be used in a WebDriver session 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.

important

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

QueryDescription
chromedriver_version:*Match any device with a ChromeDriver version
chromedriver_version>=120.0.0.0Match 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

ChromeDriver session lifecycle​

On Tizen, webOS, and SmartCast, the ChromeDriver session attaches to the Chromium debug port exposed by the currently running application. When the launched app exits, the debug port goes away and the ChromeDriver session terminates with it — any subsequent Appium command will fail.

This is different from iOS and Android mobile, where terminateApp is a common "reset to a known state" pattern at the start of a test. The mobile drivers do not proxy through Chromium, so the analogy does not carry over to Smart TVs.

Operations that sever the session​

  • Calling terminateApp(appId) on the application the session is attached to.
  • A second client calling quit or closeApp against the same app.
  • The application crashing, or being closed by the platform's own lifecycle (e.g. backgrounding after inactivity).
  • Pressing remote keys that the TV interprets as app shutdown, such as Home or Exit.

Error signatures​

If the chromedriver attachment has been lost, you will see one of the following on the next command:

WebDriverError: An unknown server-side error occurred while processing the command.
Original error: chrome not reachable
WebDriverError: An unknown server-side error occurred while processing the command.
Original error: disconnected: unable to connect to renderer
(failed to check if window was closed: disconnected: unable to connect to renderer)
WebDriverError: Session <uuid> is not active

Re-launching the app inside a session​

If you need to re-launch the app during a test, use terminateApp followed by activateApp (or the equivalent calls for your driver). Treat this as starting a fresh ChromeDriver attachment: any element handles or page state obtained before the re-launch are invalidated and must be re-acquired.

If you only need to reset the application's data without tearing down the session, check your driver's documentation for a dedicated reset command. For example, tizen: clearApp and webos: clearApp clear the application's local data and reload it. SmartCast does not currently expose an equivalent.

If a clean app state is needed at the start of every test and your driver does not provide a reset command, prefer starting a fresh TV Labs session over calling terminateApp on a session that has already attached to the app.

Screenshots​

On the TV Labs platform, WebDriver screenshots are not captured using the underlying drivers. Instead, the screenshot request is intercepted and uses the device video capture to grab a screenshot. In practice this means that you 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: Roku's ECP protocol only exposes the screen while a sideloaded development channel is running, so a driver built on it cannot capture the home screen or a store channel. On the TV Labs platform, you can capture screenshots outside the development channel as well.

Response Headers​

The TV Labs WebDriver server includes custom response headers that provide additional metadata about the session and video recordings.

Video Timing Headers​

All WebDriver 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 received
  • x-video-end-time: The video timestamp (in milliseconds) when the response was sent

These headers can be used to correlate WebDriver commands with specific moments in the session video recording, which is particularly useful for debugging and analysis.

note

To access these headers, you will need to intercept them from your HTTP client.

WebdriverIO Service​

To better support the use case of running WebDriver 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 a WebDriver 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 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!