Roku WebDriver

The Roku WebDriver is required to control an app. It can be used in conjunction with the Roku Robot Framework Library, Roku JavaScript library, another test framework, or a programming language or a programming language such as Python, Java, or Go to execute test cases.

Roku WebDriver APIs

Roku's WebDriver includes a set of Selenium-based REST APIs for sending commands to a Roku device. These APIs conform to the WebDriver standards specified by the World Wide Web Consortium (W3C). Specifically, the Roku WebDriver provides an HTTP-compliant JSON wire protocol with endpoints that map to their respective commands.

Path segments that are prefixed with a colon (:) represent variables. For example, the :sessionId variable is included in most command paths. This variable represents the ID of the session to be retrieved or the session where a command is to be sent.

The following table lists the available commands:

HTTP Method Path Summary
GET /status Queries the server's current status.
POST v1/session Creates a new session.
GET v1/sessions Returns a list of the currently active sessions.
GET v1/session/:sessionId Retrieves information about the specified session.
DELETE v1/session/:sessionId Deletes the session.
POST v1/session/:sessionId/input
(available since release 2.0)		 Deep links into content while the app is already running.
POST v1/session/:sessionId/install Installs the specified app.
POST v1/session/:sessionId/launch Launches the specified app.
POST v1/session/:sessionId/load
(available since release 2.0)		 Sideloads the specified app.
POST v1/session/:sessionId/press Simulates a keypress on a Roku remote control.
POST v1/session/:sessionId/timeouts Configures the amount of time that a specific operation can be executed before it is aborted.
POST v1/session/:sessionId/timeouts/press_wait Configures the amount of time between press cmd execution (if a button_sequence is used in the /press endpoint)
POST v1/session/:sessionId/timeouts/implicit_wait Configures the amount of time that a command can be executed before it is aborted.
POST v1/session/:sessionId/element Searches for an element on the screen.
POST v1/session/:sessionId/elements Searches for multiple elements on the page, starting from the screen root.
POST v1/session/:sessionId/element/active Gets the element on the page that currently has focus.
GET v1/session/:sessionId/apps Returns a list of apps installed on the device.
GET v1/session/:sessionId/current_app Returns information about the app currently loaded on the device.
GET v1/session/:sessionId/source Gets the current screen source.

Command requests

All command requests and POST/PUT message bodies are sent with a content-type of application/json;charset=UTF-8.

Command responses

Command responses are sent as HTTP/1.1 response messages. The following sections describe how the successful, invalid, and failed commands responses are sent.

Success

For successful requests, a 2xx HTTP response is returned. Successful command responses and the included message body are sent with a Content-Type of application/json;charset=UTF-8. The JSON message body includes the following properties:

Key Type Description
sessionId string The advertising ID of the device.
status number A status code summarizing the result of the command:
Code Summary Detail
0 Success The command executed successfully.
6 NoSuchDriver A session is either terminated or not started
7 NoSuchElement An element could not be located on the page using the given search parameters.
9 UnknownCommand The requested resource could not be found, or a request was received using an HTTP method that is not supported by the mapped resource.
13 UnknownError An unknown server-side error occurred while processing the command.
21 Timeout An operation did not complete before its timeout expired.
32 InvalidSelector Argument was an invalid selector.
33 SessionNotCreatedException A new session could not be created.
value * The response JSON value.

Invalid

For invalid requests (unknown command or resource not found), a 4xx HTTP response is returned. Invalid command responses are sent with a content-type of text-plain, and include a message body with a descriptive error message.

Failed

If a request maps to a valid command and contains all of the expected parameters in the request body, but fails to execute successfully, a 500 Internal Server Error is returned. The response and included message body have a Content-Type of application/json;charset=UTF-8. The message body includes two JSON objects—one with the applicable command response status, and the other with a description of the failure:

Key Type Description
status number A status code summarizing the result of the command. See the success section for the possible values.
message string A descriptive message for the command failure.

GET /status

Method Type Path Return Value Description
GET status A JSON object with the server's platform and build date. This object contains the following fields:
Key Type Description
sessionId string The advertising The advertising ID of the device
status number The status code summarizing the result of the command.
value object
value.build object The build element contains the following attributes: version and time.
value.build.version string A generic release label.
value.build.time string A timestamp specifying when the server was built.
value.os object The os element contains the following attributes: arch and name.
value.os.arch string The current system architecture.
value.os.name string The name of the operating system the server is currently running on (for example, "windows", "linux", and so on).
Queries the server's current status and returns the general state of the server. A 200 OK response is returned if the server is alive and accepting commands.

This method returns The server should respond with a general "HTTP 200 OK" response if it . The response body should be a JSON object describing.

POST v1/session

Method Type Path Parameters Return Value Description
POST session ip - {string}: The IP address of the device.

Example:

{ "ip": "117.1.1.1" }

 A JSON object with the device's advertisement ID, which is used as the sessionId. This object has the following fields:
Key Type Description
sessionId string The advertisement ID of the device.
status int A status code summarizing the result of the command.
value object
value.vendorName string The vendor of the device.
value.modelName string The model of the device.
value.language string The language of the device.
value.country string The country of the device.
value.ip string The IP address of the device.
value.timeout int The specified timeout for WebDriver client requests.
value.pressDelay int The specified delay between key presses.
Creates a new session.

GET v1/sessions

Method Type Path Return Value Description
GET sessions A JSON object with an array of sessions. This object has the following fields:
Key Type Description
sessionId string The advertisement ID of the device.
status int A status code summarizing the result of the command.
value object
value[i].vendorName string The vendor of the device.
value[i].modelName string The model of the device.
value[i].language string The language of the device.
value[i].country string The country of the device.
value[i].ip string The IP address of the device.
value[i].timeout int The specified timeout for ECP client requests.
value[i].pressDelay int The specified delay between key presses.
Returns a list of the currently active sessions.

GET v1/session/:sessionId

Method Type Path Return Value Description
GET session/:sessionId A JSON object with device information. This object has the following fields:
Key Type Description
sessionId string The advertisement ID of the device.
status int A status code summarizing the result of the command.
value object
value.vendorName string The vendor of the device.
value.modelName string The model of the device.
value.language string The language of the device.
value.country string The country of the device.
value.ip string The IP address of the device.
value.timeout int The specified timeout for WebDriver client requests.
value.pressDelay int The specified delay between key presses.
Returns device information based on the session specified in the URL path.

DELETE v1/session/:sessionId

Method Type Path Return Value Description
DELETE session/:sessionId A JSON object that has the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Deletes the session specified in the URL path.

POST v1/session/:sessionId/input

(available since release 2.0)

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/input channelId - {number}: The ID of the app to be launched.

contentId - {string} (optional): The contentId of the content to be played. You can include this parameter and the contentType to execute deep linking tests.

contentType - {string} (optional): The mediaType of the content to be played. You can include this parameter and the contentId to execute deep linking tests.

Example:
{
  "channelId": "dev",
  "contentId": "myMovie123",
  "contentType": "movie"
}
A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Deep links into content while the app is already running.

POST v1/session/:sessionId/install

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/install channelId - {number}: The ID of the app to be installed.

Example:
{
    "channelId": "dev"
}
A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Installs the specified the app.

POST v1/session/:sessionId/launch

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/launch channelId - {number}: The ID of the app to be launched.

contentId - {string} (optional): The contentId of the content to be played. You can include this parameter and the contentType to execute deep linking tests.

contentType - {string} (optional): The mediaType of the content to be played. You can include this parameter and the contentId to execute deep linking tests.

Example:
{
  "channelId": "dev",
  "contentId": "myMovie123",
  "contentType": "movie"
}
A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Launches the specified app.

You can use this method to launch an app into playback or an episodic picker screen in order to test deep linking.

POST v1/session/:sessionId/load

(available since release 2.0)

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/load channel - {file}: A zipped package file.

username - {file}: Enter rokudev, which is the user name for the Development Application Installer.

password - {file}: The password for accessing the Development Application Installer on your Roku device.

Example:
{
    "channel": "myChannel.zip",
    "username": "rokudev",
    "password": "your_device_password",
}
A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Sideloads an app.

POST v1/session/:sessionId/press

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/press button - {string}: The name of the key to be pressed ("home", "up", "down", "left", "right").

button_sequence - {array: string}: An array of keys to be pressed in the specified sequence.

button_delays - {array: string} (optional): An array of delays (in ms) between buttons executions. The default value is 1000ms.

Example: 
{
   "button_sequence": ["up", "down", "left"],
   "buttons_delays": ["1000", "2000"]
}


In this example, the delay after the "up" keypress is 1000ms and 2000ms after the "down" keypress.		 A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device
status int A status code summarizing the result of the command
value object null
Simulates the press and release of the specified key.

POST v1/session/:sessionId/timeouts

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/timeouts type - {string}: Either "implicit" (ECP commands) or "pressDelay" (delay between press cmd execution)

ms - {number}: The amount of time, in milliseconds, that time-limited commands are permitted to run.

Example: 
{
  "type": "implicit",
  "ms": 2000
}
A JSON object with the specified session. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command
value object null
Configure the amount of time that an operation can be executed before it is aborted.

POST v1/session/:sessionId/timeouts/implicit_wait

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/timeouts/implicit_wait ms - {number}: The amount of time (in milliseconds) that commands are allowed to run.

Example: 
{
    "ms": 2000
}
A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Specify the amount of time that commands can be executed before being aborted.

POST v1/session/:sessionId/timeouts/press_wait

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/timeouts/press_wait ms - {number}: The amount of time (in milliseconds) between keypress commands.

Example:
{
    "ms": 2000
}
A JSON object with the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object null
Specify the amount of time to wait between key presses.

POST v1/session/:sessionId/elements

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/elements An array of the following objects, which can be used to located an element:

using - {string}: The locator strategy to use. This may be one of the following values:
  • text: Returns an element whose text matches the search value.
  • attr: Returns an element whose specified attributes matches the search value.
  • tag: Returns an element whose tag name matches the search value.


attribute - {string}: The attribute name (used only for "attr" strategy)

value - {string}: The search target.

Example:
{
  "elementData": [{
    "using": "tag",
    "value": "Label"
  },
  {
    "using": "text",
    "value": "series"
  },
  {
    "using": "attr",
    "attribute": "index"
    "value": "0"
  }
 ]
  "parentData": [{
    "using": "tag",
    "value": "Grid"
  }
 ]
}
A WebElement JSON object representing the retrieved elements. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object
value.XMLName object
value.XMLName.Local string The name of the retrieved element
value.XMLName.Space string The namespace identifier for the element.
value.Attr array
value.Attr[i].Name object
value.Attr[i].Name.Local string The name of attribute.
value.Attr[i].Name.Space string The namespace identifier for the attribute.
value.Attr[i].Value string The value of the attribute.
value.Nodes array The child elements.
Searches for elements on the page matching the search criteria, starting from the screen root. All the matching elements will be returned in a WebElement JSON object.

POST v1/session/:sessionId/element

Method Type Path JSON Parameters Return Value Description
POST session/:sessionId/element An elementData array and optional parentData array with the following objects that can be used to locate an element:

using - {string}: The locator strategy to use. This may be one of the following values:
  • text: Returns an element whose text matches the search value.
  • attr: Returns an element whose specified attributes matches the search value.
  • tag: Returns an element whose tag name matches the search value.


attribute - {string}: The attribute name (used only for "attr" strategy)

value - {string}: The search target.

Example:
{
  "elementData": [{
    "using": "tag",
    "value": "Label"
  },
  {
    "using": "text",
    "value": "series"
  },
  {
    "using": "attr",
    "attribute": "index"
    "value": "0"
  }
 ]
  "parentData": [{
    "using": "tag",
    "value": "Grid"
  }
 ]
}
A WebElement JSON object representing the retrieved element. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object
value.XMLName object
value.XMLName.Local string The name of the retrieved element.
value.XMLName.Space string The namespace identifier for the element.
value.Attr array
value.Attr.Name object
value.Attr.Name.Local string The name of the attribute.
value.Attr.Name.Space string The namespace identifier for the attribute.
value.Attr.Value string The value of the attribute.
value.Nodes array The child elements.
Searches for an element on the page, starting from the screen root. The first located element will be returned as a WebElement JSON object.

GET v1/session/:sessionId/element/active

Method Type Path Return Value Description
GET session/:sessionId/element/active A JSON object with the element that currently has focus. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value object
value.XMLName object
value.XMLName.Local string The name of the element retrieved.
value.XMLName.Space string The namespace identifier of the element retrieved.
value.Attr array
value.Attr[i].Name object
value.Attr[i].Name.Local string The name of the attribute.
value.Attr[i].Name.Space string The namespace identifier of the attribute.
value.Attr[i].Value string The value of the attribute.
value.Nodes array The child elements of the retrieved item.
Retrieves the element on the page that currently has focus.

GET v1/session/:sessionId/source

Method Type Path Return Value Description
GET session/:sessionId/source A JSON object with the current page source. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device.
status int A status code summarizing the result of the command.
value string A base64 string that can be decoded to XML.
Retrieves the current page source.

GET v1/session/:sessionId/apps

Method Type Path Return Value Description
GET session/:sessionId/apps A JSON object with an array of installed apps. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device
status int A status code summarizing the result of the command.
value array
value[i].Title string The title of the app.
value[i].ID string The ID of the app.
value[i].Version string The build version of the app.
value[i].Subtype string "ndka"/"rsga"
value[i].Type string "menu"/"appl"
Retrieves a list of apps currently installed on the device.

GET v1/session/:sessionId/current_app

Method Type Path Return Value Description
GET session/:sessionId/current_app A JSON object with the app currently loaded on the device. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device
status int A status code summarizing the result of the command.
value array
value[i].Title string The title of the app.
value[i].ID string The ID of the app.
value[i].Version string The build version of the app.
value[i].Subtype string "ndka"/"rsga"
value[i].Type string "menu"/"appl"
Retrieves the app currently running on the device.

GET v1/session/:sessionId/player

Method Type Path Return Value Description
GET session/:sessionId/player A JSON object with the information about the Roku media player. This object has the following fields:
Key Type Description
sessionId string The advertising ID of the device
status int A status code summarizing the result of the command
value object
value.error string Indicates whether there was a playback error. If no error occurred, this is set to "false"
value.state string Indicates the current playback state ("play", "pause", "resume", and so on)
value.format object The format element contains the following attributes: audio, caption, container, drm, video, and res.
value.format.audio string The audio compression method ("aac", "aac_adts", and so on.)
value.format.caption string The closed caption format ("608_708", for example). This value is set to "none" if there are no captions.
value.format.container string The container format ("hls", for example)
value.format.drm string The encoding type. If no encoding is used, this us set to "none".
value.format.video string The format of the currently playing video stream ("mpeg4-15", for example)
value.format.res string The resolution of the currently playing video stream ("1280X720", for example).
value.buffering object The buffering element contains the following attributes: current, max, target.
value.buffering.current string The current buffering speed (in kbps).
value.buffering.max string The maximum possible buffering speed (in kbps).
value.buffering.target string The target buffering speed (in kbps).
value.newStream object The newStream element contains the following attribute: speed.
value.newStream.speed string The current playback speed (in bps)
value.position string The time of the current position in the stream, expressed as the elapsed time (in ms) since the start of stream or UTC time, depending on the content.
value.duration string The duration of the video being played (in seconds). This becomes valid when playback begins and may change if the video is dynamic content, such as a live event.
value.isLive string A flag indicating whether the video being played is a live stream.
value.runtime string The runtime of the video being played (in seconds).
value.streamSegment object The streamSegment attribute contains Information about the video segment that is currently streaming. This is only meaningful for segmented video transports, such as DASH and HLS

This element contains the following attributes: bitrate, mediaSequence, segmentType, and time.
value.streamSegment.bitrate string The bitrate of the video segment (in bps).
value.streamSegment.mediaSequence string The HLS media sequence ID of the segment in the video.
value.streamSegment.segmentType string The type of data in the segment, which may be one of the following values: "audio", "video", "captions", "mux".
value.streamSegment.time string The chunk start time.
Retrieves information about the Roku media player.

Testing production apps

To test production apps with the Roku Web Driver APIs, package the app on your Roku device using the same Roku developer account linked to the production version of the app.