/roku-test-automation

Helps with automating functional tests

Primary LanguageTypeScript

Roku Test Automation

Intro

Roku Test Automation (RTA from here on out) helps with automating functional tests for Roku devices. It has quite a bit more capabilities than Roku's first party option and does not require a Go server in the middle to convert ECP commands.

Integration

In your project go ahead and install the npm module:

npm install roku-test-automation --save-dev

Once installed, the standard way for using RTA is via the singletons like

import { ecp, odc, device, utils } from 'roku-test-automation';

if you tried to actually use these in your code you would likely get an exception thrown as no config is currently setup.

Currently the only necessary part of the config is at least one device host and password. Here's a sample config you could use as a start:

{
	"$schema": "https://raw.githubusercontent.com/triwav/roku-test-automation/master/server/rta-config.schema.json",
	"RokuDevice": {
		"devices": [{
			"host": "",
			"password": ""
		}]
	},
	"ECP": {
		"default": {
			"launchChannelId": "dev"
		}
	},
	"OnDeviceComponent": {
		"logLevel": "info"
	}
}

save that wherever you store config files for your project. Since device host and passwords are specific to you, you should likely also add it to your .gitignore file.

To keep a single config file and aid in running multiple tests at once, RTA reads its config from the environment variable process.env.rtaConfig. For a basic setup you can use the helper

utils.setupEnvironmentFromConfigFile('<PATH-TO-CONFIG-FILE>')

to setup the environment for you. To avoid having to do this in each test file you can setup a global include in the mocha section of your package.json as demonstrated in /testProject/package.json. Be sure to change the path to match where you put your include file.

If you're going to use the OnDeviceComponent then there are a number of files that need to be copied over into your app. If you're not using the BrightScript Extension for VSCode yet then now is a great time to try it out. If you are all you need to is add:

{
"src": [
		"${workspaceFolder}/node_modules/roku-test-automation/dist/device/**/*"
	],
	"dest": "/"
}

to your bsconfig.json or launch.json configuration files array. No need to keep the files in sync in the future when you upgrade this module.

RTA's RokuDevice also exposes a deploy() function for including these files and also turning on a bs_const for ENABLE_RTA if included in your manifest.

If you did all the steps above correct you should be ready to start making use of RTA's components.

Components

ECP

RTA contains most of the standard ECP commands including:

  • Launching/deeplinking into a channel
  • Sending keypress and keypress sequences to the device
  • Sending text to the device
  • Getting the current active app

OnDeviceComponent

The core piece of RTA is the OnDeviceComponent. It functions similarly to Roku's RALE in that you have a component that is initialized on the device as used in the testProject here
m.odc = createObject("RTA_OnDeviceComponent")
Once setup you can send requests to the device to either kick off an event or check whether the expected outcome occurred or both. The following is list of all current request types:


getValueAtKeyPath(args: ODCGetValueAtKeyPathArgs, options: ODCRequestOptions): {found: boolean, value}
At the heart of almost all requests internally is getValueAtKeyPath. It serves as your entry point from which you execute other requests but can also be used by itself to return a requested value. args takes two properties:
base?: string can be either global or scene. If not supplied it defaults to global

keyPath: string builds off of the base and supplies the path to what you are interested in getting the value for. A simple example might be something like AuthManager.isLoggedIn which would let you check if a user is logged in or not. It can operate on much more than just keyed type fields though.

Array's can access index positions array.0.id.
Nodes can access their children node.0.id as well as find nodes with a given id node.idOfChildNodeToInspect.
The getValueAtKeyPath unit tests provide a full list of what is possible for a key path


getValuesAtKeyPaths(args: ODCGetValuesAtKeyPathsArgs, options: ODCRequestOptions): {[key: string], found: boolean}
getValuesAtKeyPaths allows you to retrieve multiple values with a single request. It takes one property for args:
requests: object A list of the individual getValueAtKeyPath args with a user supplied key that will be returned as the same key for the output object.

The getValuesAtKeyPaths unit test provides an example of its usage


setValueAtKeyPath(args: ODCSetValueAtKeyPathArgs, options: ODCRequestOptions): {}
Allows you to set a value at a key path. It takes the standard base and keyPath properties along with the following for args:
value: any The value you want to set at the supplied keyPath. Setting is always done through update(value, true) so anything you can do there should be possible here as well.


callFunc(args: ODCCallFuncArgs, options: ODCRequestOptions): {value}
Allows you to run callFunc on a node. It takes the standard base and keyPath properties along with the following for args:
funcName: string the name of the interface function that you want to run

funcParams?: any[] an array of params to pass to the function. If not supplied (Invalid) will be passed for the params list.


getFocusedNode(args: ODCGetFocusedNodeArgs, options: ODCRequestOptions): ODCNodeRepresentation
Gets the currently focused node. args is currently empty but is still included for standardization and future expansion options.


hasFocus(args: ODCHasFocusArgs, options: ODCRequestOptions): boolean
Check if the node at the supplied key path has focus or not. It takes the standard base and keyPath properties.


isInFocusChain(args: ODCIsInFocusChainArgs, options: ODCRequestOptions): boolean
Check if the node at the supplied key path is in the focus chain. It takes the standard base and keyPath properties.


observeField(args: ODCObserveFieldArgs, options: ODCRequestOptions): {observerFired: boolean, value}
Instead of having to do an arbitrary delay or polling repeatedly for a field to match an expected value, you can use observeField to setup an observer and be notified when the value changes. It takes the standard base and keyPath properties along with the following for args:
match?: any | {base, keyPath, value} sometimes when you are observing a field you don't just want the first change. You're looking for a specific value. In this case you can pass the value you're looking for the match like await odc.observeField({keyPath: 'AuthManager.isLoggedIn', match: true}) In this case, base and keyPath for match are the same as those for the base level args. It's even more powerful than that though. You can also supply an object where the value your matching against actually comes from a totally different node than the one being observed.

One note, to simplify writing tests, if match is supplied and the value already matches it will not setup an observer but will just return right away. Without this you'd have to write something like:

const observePromise = odc.observeField(...);
await odc.setValueAtKeyPath(...);
const result = await observePromise;

to avoid a race condition that the value already changed by the time you setup your observer. Instead you can write your test like:

await odc.setValueAtKeyPath(...);
const result = await odc.observeField(...);

to help distinguish if the observer actually fired the property observerFired is returned in the response object


readRegistry(args: ODCReadRegistryArgs, options: ODCRequestOptions): { values: { [section: string]: {[sectionItemKey: string]: string} } }

Allows for reading from the registry. If no specific sections are requested then it will return the entire contents of the registry


writeRegistry(args: ODCWriteRegistryArgs, options: ODCRequestOptions)

Allows for writing to the registry. If null is passed for a sectionItemKey that key will be deleted. If null is passed for a section that entire section will be deleted.


deleteRegistrySections(args: ODCDeleteRegistrySectionsArgs, options: ODCRequestOptions)

Allows for deleting sections from the registry. Similar functionality can be achieved with writeRegistry passing null sections but helps to make it clearer if a mixed model isn't needed.


deleteEntireRegistry(args: ODCDeleteRegistrySectionsArgs, options: ODCRequestOptions)

Provides a way to clear out all sections in registry. Uses deleteRegistrySections under the hood but makes it clearer what is being done


RokuDevice

Serves as the middle man for ECP requests and provides access to some of the capabilities provided by the Roku's built in web server. Currently creates and retrieves a screenshot as well as provides a helper for deploying


NetworkProxy

This class serves as a wrapper around the http-network-proxy npm module. It is still in active development and will change some as testing shows necessary changes. At it's core the idea is to be able to take a Charles config file and use those same rules in your tests. The following methods are exposed:

start(configFilePath: string = 'charlesRewrite.xml')
sets up the proxy, loads the provided config in and writes to the device's registry to get it ready to proxy requests.

stop()
Used to shutdown the proxy port when you no longer want to proxy. Also sends an ODC request to the device

reloadConfig(configFilePath: string = 'charlesRewrite.xml')
Gives the ability to reload the config without having to stop and restart the entire proxy

addBreakPointListener(onProxyRequestCallback: OnProxyRequestCallback)
Allows you add a callback that will be called for every breakpoint Charles would have run into

observeRequest(url: string, onProxyResponseCallback: OnProxyResponseCallback)
Provides a simplified way of receiving a callback when a url is accessed without needing to create a Charles config file for that case.


utils

Contains a number of helpers that are mostly used internally but may also be of externally. Be sure to checkout the file for a full list.. Below are few of the most useful ones for external use:


setupEnvironmentFromConfigFile(configFilePath: string = 'rta-config.json', deviceSelector: {} | number = 0)
As mentioned in the integration section, the config needs to be setup in the environment before using some of the components. This takes a path to your config file as its first param and an optional deviceSelector param for its second. At its simplest you can give it an array index of the device you want to use. You can also pass an object as well though. If an object is supplied it will go through each key/value supplied and check them against the properties object to see if properties match. An example usage of this might that you want to segment your devices as isLowEndDevice true|false to allow you to run certain tests on only certain devices. It's user defined so feel free to use it however you'd like.


getMatchingDevices(config: ConfigOptions, deviceSelector: {}): {[key: string]: DeviceConfigOptions}
If you're wanting to run multiple tests at the same time then this helper is useful for getting a list of all devices that match your device characteristics so you split it among multiple runners


addRandomPostfix(message: string, length: number = 2)): string
A lot of times with that tests it's useful to to append something to it to make sure a string is unique.


sleep(milliseconds: number)
While doing arbitrary waiting is almost never needed thanks to observeField, there might be some use cases for this.