webOS WebDriver
Introduction
This page is a reference for the available commands, execute methods, and key mappings for the webOS WebDriver integration.
The webOS WebDriver integration is written by TV Labs for LG webOS televisions. It is an Appium compatible WebDriver, so it can be driven from any Appium or WebDriver client. It drives the app's page through a ChromeDriver attached to the TV's web app debugger, and drives the TV itself through LG's remote control API.
Starting a Session
Select a build with the tvlabs:build capability and it is sideloaded onto the TV and launched when the session starts. To launch an app that is already installed, name it with appium:appId instead.
const capabilities = {
'tvlabs:constraints': { platform_key: 'web_os' },
'tvlabs:build': 'YOUR_BUILD_ID',
};
When a session starts:
- The app is launched.
- ChromeDriver attaches to the app's page once it appears on the debugger.
A session started without an app is still a valid session. ChromeDriver attaches to whatever page the debugger exposes, if any.
Capabilities
| Capability | Description |
|---|---|
appium:appId | The ID of the app to launch. Set for you from tvlabs:build when a build is selected |
appium:remoteOnly | When true, the app is launched but no ChromeDriver is attached. See Retail and system apps |
appium:rcMode | How webos: pressKey delivers keys: rc (default) presses remote buttons, js dispatches in-page key events |
goog:chromeOptions | Passed through to ChromeDriver. debuggerAddress is always set by TV Labs |
Retail and system apps
Store apps such as Netflix and YouTube, and the TV's own system apps, don't expose a page to the debugger, so ChromeDriver can't attach to them. Set appium:remoteOnly to true to launch one of these apps without ChromeDriver. The webos: execute methods and key presses keep working, and the DOM commands return an unsupported operation error.
The session is attached to the page of the app it launched. Pressing a key that leaves the app, such as home or back on the app's root screen, ends that page, and the commands that follow fail. See ChromeDriver session lifecycle.
Available Commands
The standard W3C WebDriver commands for the document, navigation, finding elements, element state, interaction, cookies, and synchronous and asynchronous script execution are proxied to ChromeDriver, so their availability depends on the TV's Chromium version. W3C Actions (performActions) need Chromium 76 or newer.
The id, name, and class name locator strategies are translated to CSS selectors. accessibility id is not supported.
The following behave differently on webOS:
| Command | Behavior on webOS |
|---|---|
takeScreenshot | Served from the TV Labs video capture of the device, so it shows the whole screen |
getContexts | Always the single NATIVE_APP context. DOM commands already run against the page |
switchContext | Not supported |
switchToFrame | Only null (the top-level document) is supported. iframes can't be entered |
getWindowHandles | Always a single window. Resizing, maximizing, and fullscreen leave the window as is |
| Alerts | Packaged webOS apps deny native JavaScript dialogs, so alert commands find no alert |
Execute Methods
In addition to the standard WebDriver commands, the following execute methods are available for device interaction:
| Command | Required Arguments | Description |
|---|---|---|
webos: pressKey | key | Press a key on the remote control. See webos: pressKey. |
webos: longPressKey | key | Hold a key. The hold is only honored with appium:rcMode set to js. |
webos: activateApp | appId | Launch an installed app. |
webos: terminateApp | appId | Remove an app from the TV. See webos: terminateApp. |
webos: listApps | - | List the apps that can be launched, as objects with appName and appId. |
webos: activeAppInfo | - | Return the foreground app as { appId }. Errors on the home screen. |
webos: deviceInfo | - | Return the TV's system information, such as modelName and serialNumber. |
webos: clearApp | - | Clear the app's local storage and reload the page. |
mobile: pressButton | name | The same as webos: pressKey. Optional durationSeconds sets the hold. |
mobile: deviceInfo | - | See mobile: deviceInfo. |
Any other webos: command returns an unknown method error. The webos: methods are only available through synchronous execute.
webos: pressKey
await driver.executeScript('webos: pressKey', [{ key: 'down' }]);
By default, keys are pressed as remote control buttons, so they reach the TV's own UI as well as the app. With appium:rcMode set to js, keys are instead dispatched as KeyboardEvents inside the page, which supports holding a key with duration but only covers the keys marked as such in the key map.
webos: terminateApp
webos: terminateApp uninstalls the app from the TV rather than closing it. The app has to be reinstalled before it can be launched again.
await driver.executeScript('webos: terminateApp', [{ appId: 'com.example.myapp' }]);
Key Map
The following keys are available with webos: pressKey, webos: longPressKey, and mobile: pressButton. Matching is case-insensitive.
| Key | Aliases | js mode | Description |
|---|---|---|---|
up | ✓ | Up | |
down | ✓ | Down | |
left | ✓ | Left | |
right | ✓ | Right | |
enter | select, ok | ✓ | OK / Enter |
back | ✓ | Back | |
fwd | fast_forward, ff | ✓ | Fast forward |
rev | rewind | ✓ | Rewind |
playpause | ✓ | Play / Pause | |
play | Play | ||
pause | Pause | ||
stop | Stop | ||
home | root_menu | Home Dashboard | |
exit | Exit | ||
menu | Quick Settings | ||
qmenu | quick_menu, settings | Quick Settings | |
volume_up | vol_up | Volume Up | |
volume_down | vol_down | Volume Down | |
mute | volume_mute | Mute | |
channel_up | chan_up | Channel Up | |
channel_down | chan_down | Channel Down | |
red | Red | ||
green | Green | ||
yellow | Yellow | ||
blue | Blue | ||
asterisk | * |
playpause is only available with appium:rcMode set to js. The keys without a ✓ are only available in the default rc mode.