Skip to main content

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.

warning

Important: Currently the proxy only supports Roku devices. Support for other platforms is coming soon.

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​

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 (e.g., roku)
  • make: The device manufacturer (e.g., Samsung)
  • device_type: The device type (tv, stb, or mobile)
  • model: The specific model (e.g., Express 4K+)
  • year: The device's release year (e.g., 2024)

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 during a session. You can obtain a build ID using 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

If no build ID is provided, the driver will run without a sideloaded application. Note that some drivers may not support running without an application specified - please refer to the specific driver documentation.

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.

Platform Drivers​

The TV Labs Appium integration leverages the following platform-specific drivers:

PlatformDriver
Rokuappium-roku-driver
AndroidComing Soon
Tizen TV (Samsung)Coming Soon
WebOS (LG)Coming Soon
SmartCast (Vizio)Coming Soon

Example Script​

Below is a complete NodeJS script demonstrating the TV Labs Appium proxy. To run this script, first set up your environment:

mkdir tvlabs-appium-example && cd tvlabs-appium-example
npm init -y
npm install --save webdriverio dotenv
touch roku-appium.js

echo "TVLABS_API_KEY=<tvlabs_api_key>" >> .env
echo "TVLABS_BUILD_ID=$(tvlabs upload -i ./path/to/application.zip)" >> .env

Copy and paste the following script into the roku-appium.js file, then run it with node:

const { remote } = require("webdriverio");
const fs = require("fs");
require("dotenv").config();

const capabilities = {
  "tvlabs:build": process.env.TVLABS_BUILD_ID,
  "tvlabs:constraints": {
    "platform_key": "roku",
  },
};

const wdOpts = {
  hostname: process.env.APPIUM_HOST || "appium.tvlabs.ai",
  port: parseInt(process.env.APPIUM_PORT, 10) || 4723,
  protocol: "https",
  logLevel: "info",
  capabilities,
  headers: {
    "Authorization": `Bearer ${process.env.TVLABS_API_KEY}`
  }
};

async function runTest() {
  const driver = await remote(wdOpts);

  try {
    await driver.executeScript("roku: deviceInfo", []);

    await driver.executeScript("roku: pressKey", [{ key: "Up" }]);

    await driver.executeScript("roku: pressKey", [{ key: "Down" }]);

    await driver.executeScript("roku: pressKey", [{ key: "Left" }]);
    
    await driver.executeScript("roku: pressKey", [{ key: "Right" }]);

    const screenshot = await driver.takeScreenshot();

    fs.writeFileSync("./screenshot.png", screenshot, { encoding: "base64" });
  } finally {
    await driver.pause(1000);
    await driver.deleteSession();
  }
}

runTest().catch(console.error);