Appium

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.

important

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

Capabilities

The TV Labs Appium proxy supports the following capabilities, in addition to the capabilities provided by Appium and driver specific capabilities.

The platformName, appium:automationName, and device connection capabilities are automatically added to the request based on the matched platform.

tvlabs:constraints (required)

info

An API to explore available values for tvlabs:constraints is coming soon.

The tvlabs:constraints capability matches your test script to a device on the TV Labs platform. It accepts a map of key-value pairs with the following supported keys:

• platform_key: The platform key of the device (see available values in the Platforms section)
• make: The device manufacturer (e.g., Samsung)
• device_type: The device type (tv, stb, or mobile)
• model: The device model (e.g., Express 4K+)
• year: The device model year (e.g., 2024)
• minimum_chromedriver_major_version: The minimum major version of the ChromeDriver.
• supports_chromedriver: Whether the device supports ChromeDriver.

Example tvlabs:constraints capability to match with any Roku device:

{
  platform_key: 'roku';
}

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": [...]}

note

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

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.

warning

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

Platforms

The following platforms are supported by the TV Labs Appium proxy:

Platform	platform_key	Appium Driver	Supports Inspector	Build Format
Roku	roku	appium-roku-driver	Yes	.zip
WebOS (LG)	web_os	appium-lg-webos-driver	No	.ipk
Tizen TV (Samsung)	tizen	appium-tizen-tv-driver	Yes	.wgt
tvOS (Apple TV)	tv_os	appium-xcuitest-driver	Yes	.ipa
iOS (iPhone, iPad)	ios	appium-xcuitest-driver	Yes	.ipa
SmartCast (Vizio)	smartcast	Closed Source	-	.zip
Android TV	android_tv	Coming Soon	-	.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.

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 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 may not always be an exact match if there is not one available, but the closest compatible version will be selected.

Use the supports_chromedriver and minimum_chromedriver_major_version constraint capabilities to ensure that a device which supports your script is matched. For example, if you need to use the actions API introduced in major version 76 of ChromeDriver, you can set the following capabilities:

{
  "tvlabs:constraints": {
    "supports_chromedriver": true,
    "minimum_chromedriver_major_version": 76,
    // ...
  }
}

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.

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.

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 }]],
  // ...
};

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!