One of the great things about Appium 2.0 is that you can find drivers to enable your automation testing across a wider variety of platforms than ever before; now including even media streaming platforms! In this article, we'll learn how to test Roku TV applications using a relatively new Appium driver for Roku TV. I implemented this driver on behalf of HeadSpin, and it's fully open source, available on GitHub: Appium for Roku TV. The full documentation for the driver is available there at the README, but we'll be covering all the highlights in this article.

How the Appium Roku driver works

To perform automation well on a given platform, it's always worth doing a little research on how app development for the platform works, beyond finding an Appium driver for it. This helps you understand how the driver itself works and what its requirements and limitations are. The more you know about iOS development, for example, the better use you'll be able to make of Appium's iOS driver. The same goes for Roku! The best source for Roku developer information is Roku's Developer Portal. This is the documentation I used to build the Appium Roku driver.

One thing to note right off the bat is that Roku apps are called "channels" (as in TV channels) in the Roku documentation, so be aware of how this language is a bit different from most platforms.

You might also notice that Roku publishes something called the Roku WebDriver, which is a WebDriver server implementation for Roku automation, written in Go. Its purpose is very similar to the purpose of the Appium Roku driver---to allow for WebDriver-style automation of Roku apps. So why did I bother to make an Appium Roku driver at all? When I looked into the Roku WebDriver implementation, it unfortunately did not follow standard W3C protocol conventions, nor was it already Appium-compatible. Reading through the code, it became apparent that the Roku WebDriver server was a thin layer on top of another Roku developer tool called the External Control Protocol (ECP). This is an API hosted on the Roku device itself which allows limited remote control and debugging of Roku developer channels. Beyond this, I noticed that the Roku WebDriver did not have certain features I thought were important, like the ability to find element objects and trigger them by calling the Click Element command. Ultimately, it seemed like a better idea to create and maintain an Appium driver based on the same protocol, so that's what we did!

The ECP takes care of most of how the Appium driver works, since it lets you do things like get a dump of the UI element hierarchy or simulate remote control keypresses. But it doesn't let you do things like install apps or take screenshots. Luckily, the Roku comes with a special developer mode website that you can access in a web browser locally connected to the Roku device. This website lets you upload your development apps (called "dev channels"), and retrieve screenshots. The Appium driver simply calls out to this webserver when it needs to perform these tasks as part of its work, so you don't have to do it manually.

Requirements and limitations of the Appium Roku driver

Before beginning an automation project for any platform, it's important to make sure you understand the requirements and limitations of the platform, so you're not stuck in a dead end. This is definitely true for Roku test automation as well. Here are some of the requirements you'll need to keep in mind if you want Roku testing to be successful:

1. You will need a physical Roku device for testing. There is no such thing as a Roku emulator, unfortunately.
2. Your Roku needs to be on the same network as your Appium server (since the Appium server will make network calls to the Roku).
3. Your Roku needs to be in Developer Mode so that the ECP server and Dev Mode server are up and running.
4. You need to have access to your Roku channel as a .zip file in the format expected by the Roku channel sideloading (installation) service. In other words, it should be an archive of your source code, not a compiled version of the app.
5. And of course, you should have a functional Appium 2.0 server environment, ideally updated to the latest and greatest!

Here are some limitations of the driver to keep in mind:

1. You cannot automate channels that you do not have the source code to (i.e., your dev channel). (Technically, you can still use the driver's remote control emulation to do anything you want on the device, but this will be driving the device "blind"---you'll have no way to check the UI hierarchy or grab a screenshot). I.e., the Take Screenshot and Get Page Source commands only work if the dev channel is active.
2. Roku provides a way to see the UI element hierarchy, but no way to work with specific UI elements directly. The only way to interact the device is via the remote control. The Appium driver does however provide a special algorithm for emulating the Click Element command which will be highlighted below. It also has a convenience method for Send Keys, that simply sends keystrokes to the Roku as if a user were doing so with the remote. All this to say: you will be able to run the Find Element command, which is certainly useful for waiting for app state, but in general there is no way to interact with the element you have found. To trigger elements you'll need to use the driver's remote control methods or one of the few convenience methods mentioned above.
3. Only one dev channel may be sideloaded at any given time. When you (or the driver) sideloads a dev channel, it will be given the channel ID of dev. So even though your app will have its own official channel ID used for publishing, the ID of the channel for automation purposes will basically always be dev.
4. When you take a screenshot of a screen which contains video content, that video content will be shown as a black rectangle. This is because Roku does not allow DRMed video content to leave the device except to authorized playback machines (like TVs).

Installing the Appium Roku driver

With the Appium 2.0 extension CLI, installing the driver is as easy as running:

appium driver install --source=npm @headspinio/appium-roku-driver

This will get you the latest version of the Roku driver. If you would like to upgrade at any point later, you can simply run:

appium driver update roku

Starting Roku app test automation sessions

Testing your Roku TV apps using this driver involves using the following required capabilities in whichever Appium client you're most comfortable with:

Capability	Description
platformName	Should always be Roku
appium:automationName	Should always be Roku
appium:app	An absolute path to the zip file of the dev channel you want to install. If not included, a session will simply be started on the home screen. You can also just set it to dev if the dev channel is already installed.
appium:rokuHost	The host name or IP of the Roku device on the network
appium:rokuEcpPort	The ECP port on the Roku device (usually 8060)
appium:rokuWebPort	The dev web interface port on the Roku device (usually 80)
appium:rokuUser	The username you selected when turning on dev mode
appium:rokuPass	The password you selected when turning on dev mode
appium:rokuHeaderHost	The IP of the Roku device on its local network (should usually the same as rokuHost unless you are tunneling or connecting via DNS)

There is also a special capability that determines how long the driver will wait in between remote key presses. This can be useful if the automated key presses are happening too quickly for your app to react to them. If you find yourself in this position, simply set the appium:keyCooldown capability to the number of milliseconds you want to wait in between key presses.

Using a session to test Roku TV apps

Once you have a session going in your Appium client, you'll navigate your app and implement your automation test for Roku using primarily the following commands (note that the way to write these commands differs based on the client library you're using; you can refer to the client libray documentation for specific examples):

Command	Description
Get Page Source	Returns an XML document representing the current UI hierarchy. You should use this document to come up with XPath queries for elements you want to interact with.
Get Screenshot	Returns a PNG image representing the current screen.
roku: pressKey	This is an Execute Method that allows you to trigger remote control key presses, like the home button or the play/pause buttons. This method takes a single parameter named key, whose value should be one of the supported key values from the Roku documentation. Using this method, you'll be able to do anything a user would be able to do!
Find Element / Find Elements	Using an XPath query as your selector, get a reference to an element found in the UI hierarchy.
Click Element	Once you have an element, you can call .click() on it. When you do this, the Roku driver will go through a special algorithm to attempt to automatically focus the element you found and hit the Enter button to trigger its behaviour. Hopefully it will save you from having to map out the precise remote key presses required to navigate to the element.
Send Keys	If you need to type text into an input field, first make sure the input field is active and ready to receive text input. Then call the send keys / set value command (whatever it's called in your Appium client), and the driver will use the special remote control API to send literal characters instead of remote key presses.

There are a number of other commands available to help you in your Roku TV test automation (which you can learn more about at the driver documentation), including:

• Install and remove apps
• Launch apps
• List available apps
• Get information about the device

That's it! This guide should be all you need to get started with automation testing for Roku. Now go forth and test your streaming apps on Roku TV devices! Remember, the project is open source, so if you think you've found a bug, please report it at the issue tracker, and of course, contributions are also welcome.