Skip to content

feat!: support Appium v3 #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dlenroc merged 1 commit into from
Aug 20, 2025
Merged

feat!: support Appium v3 #102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 21 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Appium Roku Driver · [![NPM Version](https://img.shields.io/npm/v/@dlenroc/appium-roku-driver?cacheSeconds=86400)](https://www.npmjs.com/package/@dlenroc/appium-roku-driver) ![Node.js Version](https://img.shields.io/node/v/@dlenroc/appium-roku-driver) [![Node.js CI](https://github.com/dlenroc/appium-roku-driver/actions/workflows/nodejs.yml/badge.svg?branch=main)](https://github.com/dlenroc/appium-roku-driver/actions/workflows/nodejs.yml)

Roku Driver is a WebDriver that allows testing channels/screensavers using any webdriver client.
Roku Driver is a WebDriver that allows testing channels and screensavers using any WebDriver client.

## Prerequisites

- Appium 2
- Roku Device with fresh OS and mentioned below settings:
- [Roku OS 9.4 or Newest](https://support.roku.com/en-gb/article/208755668)
- Appium 2.x or 3.x
- Roku device with a recent OS and the settings mentioned below:
- [Roku OS 9.4 or newer](https://support.roku.com/en-gb/article/208755668)
- [Enable Developer Settings](https://developer.roku.com/en-gb/docs/developer-program/getting-started/developer-setup.md#step-1-set-up-your-roku-device-to-enable-developer-settings)
- [Disable Screensaver](https://www.solveyourtech.com/how-to-disable-the-screensaver-on-a-roku-tv/) (optional)

Expand All @@ -18,21 +18,21 @@ appium driver install --source npm @dlenroc/appium-roku-driver

## Documentation

Thanks to the [Appium](https://github.com/appium/appium) and [WebDriver](https://www.w3.org/TR/webdriver/) protocol, this driver works just like other web drivers, but there are a couple of things worth mentioning.
Thanks to the [Appium](https://github.com/appium/appium) and [WebDriver](https://www.w3.org/TR/webdriver/) protocols, this driver works just like other WebDriver implementations, but there are a couple of things worth mentioning.

### Initialization

Like other drivers, roku-driver by default uses the so-called `fast reset` algorithm, in which registries are cleared before each test, and a full reinstallation occurs only if the channel differs from the one already installed.
Like other drivers, Roku Driver uses the `fast reset` algorithm by default: registries are cleared before each test, and a full reinstallation occurs only if the channel differs from the one already installed.

### Locators

The following location strategies are supported: `tag name`, `link text`, `partial link text`, `css selector` and `xpath`.
The following locator strategies are supported: `tag name`, `link text`, `partial link text`, `css selector`, and `xpath`.

### Contexts

- `ECP` (default) [External Control Protocol](https://github.com/dlenroc/node-roku/blob/main/packages/ecp#readme) is a context that finds elements quickly, but does not see many attributes.
- `ECP` (default) [External Control Protocol](https://github.com/dlenroc/node-roku/blob/main/packages/ecp#readme) is a context that finds elements quickly but does not expose many attributes.

- `ODC` (WIP) [On Device Component](https://github.com/dlenroc/node-roku/blob/main/packages/odc#readme) is a context that finds elements slower, but see all attributes. (can be tunned using `elementResponseAttributes` setting).
- `ODC` (WIP) [On-Device Component](https://github.com/dlenroc/node-roku/blob/main/packages/odc#readme) is a context that finds elements more slowly but exposes all attributes. It can be tuned using the `elementResponseAttributes` setting.

### Deep linking

Expand All @@ -50,18 +50,18 @@ The following location strategies are supported: `tag name`, `link text`, `parti

### Channels

In roku `appId` is always `dev` for sideloaded channel or a number for channels installed from store (ex: `12` for Netflix).
In Roku, `appId` is `dev` for a sideloaded channel or a number for channels installed from the store (e.g., `12` for Netflix).

```js
driver.queryAppState('dev');
driver.queryAppState('12');
```

> **Note:** most commands only work with SceneGrapth based sideloaded channels.
> **Note:** most commands only work with SceneGraph-based sideloaded channels.

### Screensaver / Screensaver Settings

Given driver allows testing of [Screensavers](https://developer.roku.com/en-gb/docs/developer-program/media-playback/screensavers.md) via `appium:entryPoint` capability.
This driver allows testing of [screensavers](https://developer.roku.com/en-gb/docs/developer-program/media-playback/screensavers.md) via the `appium:entryPoint` capability.

- `channel` (default) - Opens channel itself.
- `screensaver` - Opens your channel screen saver.
Expand All @@ -76,7 +76,7 @@ In Roku world:
- [Registries](https://developer.roku.com/en-gb/docs/developer-program/getting-started/architecture/file-system.md) are used to store persistent information such as sessions and settings.
- [Input / Launch parameters](https://developer.roku.com/en-gb/docs/developer-program/discovery/implementing-deep-linking.md) are used for deep linking and/or controlling app behavior.

So, knowing this, we can significantly speed up the automation by skipping authorization/configuration steps.
Knowing this, you can significantly speed up automation by skipping authorization and configuration steps where appropriate.

> **Note:** `appium:arguments` and `appium:registry` will contain different values in your case.

Expand Down Expand Up @@ -112,17 +112,15 @@ await driver.sessionSubscribe({ events: ['log.entryAdded'] });
await driver.sessionUnsubscribe({ events: ['log.entryAdded'] });
```

> **Note:**

### Actions

The following action types are supported:

- `keyDown`, `keyUp` - presses/releases given key.
- `keyDown`, `keyUp` - presses/releases the given key.
- `pointerMove` - focuses the element using arrow buttons.
- `pause` - waits given amounts of milliseconds.
- `pause` - waits a given number of milliseconds.

Below are the key codes and their equivalents in the roku remote.
Below are key codes and their equivalents on a Roku remote.

| Code | Keyboard Key | Roku Key |
| -------- | ------------- | --------------- |
Expand Down Expand Up @@ -182,7 +180,7 @@ If adding a vendor prefix is a problem, [@appium/relaxed-caps-plugin](https://ww
| `appium:printPageSourceOnFindFailure` | - | boolean | When a find operation fails, print the current page source. Defaults to `false` |
| `appium:newCommandTimeout` | - | number | How long (in seconds) Appium will wait for a new command from the client before assuming the client quit and ending the session |
| `appium:settings[<key>]` | - | any | Update [driver settings](#settings) on session creation |
| `appiun:shouldTerminateApp` | - | boolean | If `true`, the channel will be closed after the session is finished. Defaults to `false` |
| `appium:shouldTerminateApp` | - | boolean | If `true`, the channel will be closed after the session is finished. Defaults to `false` |

## Settings

Expand Down Expand Up @@ -217,7 +215,7 @@ driver.switchContext('ECP');
| [findElementFromElement](src/commands/findElOrEls.ts) | Search for an element in parent element |
| [findElementsFromElement](src/commands/findElOrEls.ts) | Search multiple elements in parent element |
| [getAttribute](src/commands/getAttribute.ts) | Get the value of an attribute from a given element |
| [getProperty](src/commands/getProperty.ts) | Get the value of an property from a given element <ul><li>`isFocused` - returns `true` if the element is focused.</li><li>`isInFocusChain` - returns `true` if the element or any of its descendants are focused</li><li>`isInFocusHierarchy` - returns `true` if the element or any of its ancestors or descendants is focused</li></ul> |
| [getProperty](src/commands/getProperty.ts) | Get the value of a property from a given element <ul><li>`isFocused` - returns `true` if the element is focused.</li><li>`isInFocusChain` - returns `true` if the element or any of its descendants are focused</li><li>`isInFocusHierarchy` - returns `true` if the element or any of its ancestors or descendants is focused</li></ul> |
| [getText](src/commands/getText.ts) | Get the visible text of a given element |
| [getName](src/commands/getName.ts) | Get the tag name of given element |
| [getElementRect](src/commands/getElementRect.ts) | Get the position and size of the given element |
Expand All @@ -226,9 +224,9 @@ driver.switchContext('ECP');
| [clear](src/commands/clear.ts) | Clears the content of the given element |
| [setValue](src/commands/setValue.ts) | Send a sequence of keystrokes to an element |
| [getPageSource](src/commands/getPageSource.ts) | Get the XML representation of the current UI |
| [execute](src/commands/execute.ts) | Execute an roku command |
| [execute](src/commands/execute.ts) | Execute a Roku command |
| [performActions](src/commands/performActions.ts) | Performs a chain of actions |
| [releaseActions](src/commands/releaseActions.ts) | Release depressed key |
| [releaseActions](src/commands/releaseActions.ts) | Release pressed key |
| [getScreenshot](src/commands/getScreenshot.ts) | Take a screenshot |

### Appium Commands
Expand Down Expand Up @@ -258,7 +256,7 @@ driver.switchContext('ECP');

### Roku Commands

In addition to the standard apium commands, Roku has several additional features that go beyond the appium protocol, so they are available through a javascript executor and a script in the following format `<component>:<command>`
In addition to the standard Appium commands, Roku has several additional features that go beyond the Appium protocol. These are available through a JavaScript executor and a script in the following format: `<component>:<command>`

The following components are available: [ecp](https://npmjs.com/package/@dlenroc/roku-ecp/v/2.0.0), [debugServer](https://www.npmjs.com/package/@dlenroc/roku-debug-server/v/2.0.0), [developerServer](https://www.npmjs.com/package/@dlenroc/roku-developer-server/v/2.0.0), and [odc](https://www.npmjs.com/package/@dlenroc/roku-odc/v/2.0.1)

Expand Down
Loading