EntertainmentOS WebDriver

Introduction

This page is a reference for the available commands and key mappings for the EntertainmentOS WebDriver integration.

The EntertainmentOS WebDriver integration is written by TV Labs for web apps on EntertainmentOS devices, such as Sky Glass and Sky Stream. It implements the W3C WebDriver protocol, so it can be driven from any WebDriver client.

EntertainmentOS runs web apps in WPE, a WebKit port. The session launches the app with its WebKit inspector attached, and drives the page through that inspector. Key presses are sent over the device's remote control input.

Starting a Session

Name the app to launch with appium:appId. The app must already be installed on the device, or be carried by the catalog of the App Trials code passed in appium:apps_trial_code.

const capabilities = {
  'tvlabs:constraints': { platform_key: 'entertainment_os' },
  'appium:appId': 'com.example.myapp',
};

When a session starts:

1. If appium:apps_trial_code is set, the App Trials catalog for that code is applied and the device syncs its installed apps to it.
2. The app named by appium:appId is launched from cold. If it is already running, it is closed first, so every session attaches to a fresh page.
3. If appium:app is set, the launched app is navigated to that http(s) URL. Use this to drive a hosted web page inside the runtime of an installed app.

When the session ends, the app is closed. The App Trials catalog stays applied until the device's session cooldown restores the default catalog, so the next session always starts from the default.

Capabilities

Capability	Description
appium:appId	Required. The ID of the installed app to launch for the session
appium:app	An http(s) URL the launched app is navigated to before the session starts
appium:apps_trial_code	An App Trials code whose catalog is applied, and synced to the device, before the app launches

EntertainmentOS sessions do not take a tvlabs:build. If your testing requires sideloading builds on EntertainmentOS, contact TV Labs support.

note

The session is attached to the page of the app it launched. Terminating the app, or pressing a key that leaves it (such as home or back on the app's root screen), ends that page, and the commands that follow fail.

Available Commands

The standard W3C WebDriver commands for the document, navigation, finding elements, element state, interaction, cookies, and synchronous and asynchronous script execution are supported.

The following are not supported, and return an unsupported operation error:

• W3C Actions (performActions). Use entertainment_os: pressKey to send remote control keys instead
• Alerts (getAlertText, acceptAlert, dismissAlert)
• Element screenshots

Page screenshots are supported, and are taken from the TV Labs video capture of the device rather than from the browser.

In addition to these, the following commands are available for device interaction:

Command	Required Arguments	Description
entertainment_os: pressKey	key	Press a key on the remote control. Optional duration holds the key down for that many milliseconds.
entertainment_os: longPressKey	key	Hold a key on the remote control. Holds for one second unless duration is given, in milliseconds.
entertainment_os: as	url	Calls the device's AS REST API. See entertainment_os: as.
entertainment_os: pm	method	Calls the package management dev tools API. See Dev tools APIs.
entertainment_os: rm	method	Calls the runtime management dev tools API, for running apps and their lifecycle.
entertainment_os: settings	method	Calls the settings dev tools API, for system settings, test preferences and firmware component versions.
entertainment_os: softcat	method	Calls the soft catalog dev tools API.
entertainment_os: traced	method	Calls the tracing dev tools API.
mobile: clearApp	appId	Clears the app's local storage and reloads the page.

Any other entertainment_os: command returns an unknown method error.

entertainment_os: pressKey

await driver.executeScript('entertainment_os: pressKey', [{ key: 'down' }]);

// Hold select for two seconds
await driver.executeScript('entertainment_os: pressKey', [{ key: 'select', duration: 2000 }]);

await driver.executeScript('entertainment_os: longPressKey', [{ key: 'right' }]);

A key that is not in the key map returns an invalid argument error, and nothing is sent.

entertainment_os: as

Calls the device's AS REST API and returns its decoded JSON response, or {} for a request whose response has no body.

Arguments:

• url (required, string)
  • The route, starting with /, e.g. /as/system/information
• method (optional, string)
  • GET (default) or POST
• body (optional, object)
  • The JSON body of a POST
• params (optional, object)
  • Query parameters

// Read device information
const info = await driver.executeScript('entertainment_os: as', [
  { url: '/as/system/information' },
]);

// Read a setting, then write it
const url = '/as/system/setting/system.devicelocation';
const setting = await driver.executeScript('entertainment_os: as', [{ url }]);

await driver.executeScript('entertainment_os: as', [{ url, method: 'POST', body: setting }]);

Dev tools APIs

entertainment_os: pm, rm, settings, softcat and traced each make one JSON-RPC call to the matching dev tools API on the device, and return the call's result.

Arguments:

• method (required, string)
  • The JSON-RPC method, e.g. getAllPackageDetails
• params (optional, object or array)
  • The JSON-RPC params
• timeout (optional, number)
  • How long to wait for the reply, in milliseconds. Defaults to 10000

// List installed packages
const packages = await driver.executeScript('entertainment_os: pm', [
  { method: 'getAllPackageDetails' },
]);

// List running apps and their state
const apps = await driver.executeScript('entertainment_os: rm', [{ method: 'getStatus' }]);

// Read firmware component versions
const versions = await driver.executeScript('entertainment_os: settings', [
  { method: 'getVersions' },
]);

Each call is one request and one reply. Methods that report their outcome later, as a notification, only return their immediate result.

Errors

The device API commands map the device's response to a WebDriver error, with the device's own message:

Error	When
invalid argument	The arguments are malformed, or the device rejects the route, method, or parameters as unknown or invalid
unsupported operation	The device's firmware does not support the call
timeout	The device did not answer in time. traced does not reject unknown methods, so they return this error
unknown error	Any other failure

Key Map

The following keys are available with entertainment_os: pressKey and entertainment_os: longPressKey.

Key	Aliases	Description
up		Up
down		Down
left		Left
right		Right
select	ok, enter	Select
back	dismiss	Back
home		Home
page_up		Page Up
page_down		Page Down
volume_up	volume+	Volume Up
volume_down	volume-	Volume Down
volume_mute	mute	Mute
channel_up	channel+, ch_next	Channel Up
channel_down	channel-, ch_prev	Channel Down
play_pause	play, pause	Play/Pause
rewind		Rewind
fast_forward	ffwd, forward	Fast Forward
record		Record
guide		Guide
info		Info
search		Search
help		Help
voice		Voice (microphone)
settings		Settings
apps		Apps
sky		Sky
option		Options (...)
plus		Plus (+)
subtitles		Subtitles
audio_description	audiodesc	Audio Description
accessibility		Accessibility
input		Switch HDMI input
red		Red
green		Green
yellow		Yellow
blue		Blue
number-0 … number-9	0 … 9	Digits
youtube		YouTube
netflix		Netflix
disney_plus	disney+	Disney+
prime_video	primevideo	Prime Video
peacock		Peacock
kayo		Kayo
binge		Binge
xumo		Xumo