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.
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
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
(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.
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:
.zipfile 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.
Here are some limitations of the driver to keep in mind:
Get Page Sourcecommands only work if the dev channel is active.
Click Elementcommand 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 Elementcommand, 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.
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
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
Testing your Roku TV apps using this driver involves using the following required capabilities in whichever Appium client you're most comfortable with:
||Should always be
||Should always be
||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
||The host name or IP of the Roku device on the network|
||The ECP port on the Roku device (usually
||The dev web interface port on the Roku device (usually
||The username you selected when turning on dev mode|
||The password you selected when turning on dev mode|
||The IP of the Roku device on its local network (should usually the same as
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
capability to the number of milliseconds you want to wait in between key presses.
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):
||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.|
||Returns a PNG image representing the current screen.|
||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
||Using an XPath query as your selector, get a reference to an element found in the UI hierarchy.|
||Once you have an element, you can call
||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:
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.