Protocols in Selenium Web Driver

Protocol

WebDriver remote ends must provide an HTTP-based, RESTish wire protocol where the endpoints map to different commands.

As this standard only defines the remote end protocol, it puts no demands to how local ends should be implemented. Local ends are only expected to be compatible to the extent that they can speak the remote end’s protocol; no requierements are made upon their exposed user-facing API.

4.1 Algorithms

Various parts of this specification are written in terms of step-by-step algorithms. The details of these algorithms do not have any normative significance; implementations are free to adopt any implementation strategy that produces equivalent output to the specification. In particular algorithms in this document are optimised for readability rather than performance.

Where algorithms that return values are fallible, they are written in terms of returning either success or error. Asuccess value has an associated data field which encapsulates the value returned, whereas an error response has an associated error code.

The result of getting a property with name from an Object is defined as the result of calling the[[GetOwnProperty]] internal method of with property name name.

4.2 Commands

The WebDriver protocol is organised into commands. Each HTTP request with a method and template defined in this specification represents a single command and therefore each command produces a single HTTP response. In response to a command, a remote end will run a series of actions against the remote browser.

Each command defined in this specification has an associated list of remote end steps. This provides the sequence of actions that a remote end takes when it receives a particular command.

4.3 Processing Model

The remote end acts as a HTTP server reading requests from the client and writing responses, typically over TCP socket. For the purposes of this specification we model the data transmission between a particular local endand remote end with a connection to which the remote end may write bytes and read bytes. However the exact details of how this connection works and how it is established are out of scope.

After such a connection has been established, a remote end must run the following steps:

1. Read bytes from the connection until a complete HTTP request can be constructed from the data. Letrequest be a request constructed from the received data, according to the requirements of [RFC7230].
2. Let request match be the result of the algorithm to match a request with request’s method and URL as arguments.
3. If request match is of type error, send an error with request match’s error code and jump to step 1.
   Otherwise, let command and url variables be request match’s data.
4. Let session id be the corresponding variable from url variables.
5. If command is not New Session:
   1. If session id is not equal to the ID of any session in the list of active sessions, send an error with error code invalid session id, then jump to step 1 in this overall algorithm.
      Otherwise, let the current session be the session with ID session id.
6. If request’s method is POST:
   1. Let parse result be the result of parsing as JSON with request’s body as the argument.
   2. If parse result is an error or if it is a success but its associated data is not an Object, send an error witherror code invalid argument and jump back to step 1 in this overall algorithm.
      Otherwise, let parameters be parse result’s data.
   Otherwise, let parameters be null.
7. Let response result be the return value obtained by running the remote end steps for command with url variables as arguments.
8. If response result is an error, send an error with error code equal to response result’s error code and jump back to step 1 in this overall algorithm.
   Otherwise, if response result is a success, let response data be response result’s data.
9. Send a response with status 200 and response data.
10. Jump to step 1.

When required to send an error, with error code, a remote end must run the following steps:

1. Let http status and name be the error response data for error code.
2. Let message be an implementation-defined string containing a human-readable description of the reason for the error.
3. Let stacktrace be an implementation-defined string containing a stack trace report of the active stack frames at the time when the error occurred.
4. ISSUE 3

   Really need a better way to construct JSON literals.
   Let data be a new JSON Object initialised with the following properties:

   "error"

   Value of name.

   "message"

   Value of message.

   "stacktrace"

   Value of stacktrace.

5. Send a response with status and data as arguments.

When required to send a response, with arguments status and data, a remote end must run the following steps:

1. Let response be a new response.
2. Set response’s HTTP status to status, and status message to the string corresponding to the description ofstatus in the status code registry.
3. If data is not null, let response’s body be the result of serializing as JSON with data as the argument.
4. Let response bytes be the byte sequence resulting from serializing response according to the rules in [RFC7230].
5. Write response bytes to the connection.

4.4 Routing Requests

Request routing is the process of going from a HTTP request to the series of steps needed to implement thecommand represented by that request.

A remote end has an associated URL prefix, which is used as a prefix on all WebDriver-defined URLs on that remote end. This must either be undefined or an path-absolute URL.

EXAMPLE 1

For example a remote end wishing to run alongside other services on example.com might set its URL prefix to/wd so that a new session command would be invoked by sending a POST request to /wd/session, rather than /session.

In order to match a request given a method and URL, the following steps must be taken:

1. Let endpoints be a list containing each row in the table of endpoints.
2. Remove each entry from endpoints for which the concatenation of the URL prefix and the entry’s URI template does not match URL’s path.
3. If there are no entries in endpoints, return error with error code unknown command.
4. Remove each entry in endpoints for which the method column is not an exact case-sensitive match formethod.
5. If there are no entries in endpoints, return error with error code unknown method.
6. There is now exactly one entry in endpoints; let entry be this entry.
7. Let parameters be the result of extracting the variables from URL using entry’s URI template.
8. Let command be entry’s command.
9. Return success with data command and parameters.

4.5 List of Endpoints

The following table of endpoints lists the method and URI template for each endpoint node command.

Method	URI Template	Command
POST	/session	New Session
DELETE	/session/{session id}	Delete Session
POST	/session/{session id}/url	Go
GET	/session/{session id}/url	Get Current URL
POST	/session/{session id}/back	Back
POST	/session/{session id}/forward	Forward
POST	/session/{session id}/refresh	Refresh
GET	/session/{session id}/title	Get Title
GET	/session/{session id}/window	Get Window Handle
DELETE	/session/{session id}/window	Close Window
POST	/session/{session id}/window	Switch To Window
GET	/session/{session id}/window/handles	Get Window Handles
POST	/session/{session id}/window/fullscreen	Fullscreen Window
POST	/session/{session id}/window/maximize	Maximize Window
POST	/session/{session id}/window/size	Set Window Size
GET	/session/{session id}/window/size	Get Window Size
POST	/session/{session id}/frame	Switch To Frame
POST	/session/{session id}/frame/parent	Switch To Parent Frame
POST	/session/{session id}/element	Find Element
POST	/session/{session id}/element/{element id}/element	Find Element From Element
POST	/session/{session id}/elements	Find Elements
POST	/session/{session id}/element/{element id}/elements	Find Elements From Element
GET	/session/{session id}/element/active	Get Active Element
GET	/session/{session id}/element/{element id}/selected	Is Element Selected
GET	/session/{session id}/element/{element id}/attribute/{name}	Get Element Attribute
GET	/session/{session id}/element/{element id}/property/{name}	Get Element Property
GET	/session/{session id}/element/{element id}/css/{property name}	Get Element CSS Value
GET	/session/{session id}/element/{element id}/text	Get Element Text
GET	/session/{session id}/element/{element id}/name	Get Element Tag Name
GET	/session/{session id}/element/{element id}/rect	Get Element Rect
GET	/session/{session id}/element/{element id}/enabled	Is Element Enabled
GET	/session/{session id}/source	Get Page Source
POST	/session/{session id}/execute/sync	Execute Script
POST	/session/{session id}/execute/async	Execute Async Script
GET	/session/{session id}/cookie/{name}	Get Cookie
POST	/session/{session id}/cookie	Add Cookie
DELETE	/session/{session id}/cookie/{name}	Delete Cookie
DELETE	/session/{session id)/cookie	Delete All Cookies
POST	/session/{session id}/timeouts	Set Timeout
POST	/session/{session id}/actions	Perform Actions
DELETE	/session/{session id}/actions	Releasing Actions
POST	/session/{session id}/element/{element id}/click	Element Click
POST	/session/{session id}/element/{element id}/clear	Element Clear
POST	/session/{session id}/element/{element id}/sendKeys	Element Send Keys
POST	/session/{session id}/alert/dismiss	Dismiss Alert
POST	/session/{session id}/alert/accept	Accept Alert
GET	/session/{session id}/alert/text	Get Alert Text
POST	/session/{session id}/alert/text	Send Alert Text
GET	/session/{session id}/screenshot	Take Screenshot
GET	/session/{session id}/element/{element id}/screenshot	Take Element Screenshot

4.6 Handling Errors

Errors are represented in the WebDriver protocol with a HTTP response with a HTTP status in the 4xx or 5xx range, and a JSON body containing details of the error. This JSON body has three fields: error, containing a string indicating the error type; message, containing an implementation-defined string with a human readable description of the kind of error that occured; and stacktrace, containing an implementation-defined string with a stack trace report of the active stack frames at the time when the error occurred.

EXAMPLE 2

A DELETE request to /session/1234, where 1234 is not the session id of a current session would return an HTTP response with the status 404 and a body of the form:

{
  "error": "invalid session id",
  "message": "No active session with id 1234",
  "stacktrace": ""
}

The following table lists each error code, its associated HTTP status, JSON error code, and a non-normative description of the error. The error response data for a particular error code is the values of the HTTP Status andJSON Error Code columns for the row corresponding to that error code.

Error Code	HTTP Status	JSON Error Code	Description
element not selectable	400	element not selectable	An attempt was made to select an element that cannot be selected.
element not visible	400	element not visible	An element command could not be completed because the element is not visible on the page.
invalid argument	400	invalid argument	The arguments passed to a command are either invalid or malformed.
invalid cookie domain	400	invalid cookie domain	An illegal attempt was made to set a cookie under a different domain than the current page.
invalid element coordinates	400	invalid element coordinates	The coordinates provided to an interactions operation are invalid.
invalid element state	400	invalid element state	An element command could not be completed because the element is in an invalid state, e.g. attempting to click an element that is no longer attached to the document.
invalid selector	400	invalid selector	Argument was an invalid selector.
invalid session id	404	invalid session id	Occurs if the given session id is not in the list of active sessions, meaning the session either does not exist or that it’s not active.
javascript error	500	javascript error	An error occurred while executing JavaScript supplied by the user.
move target out of bounds	500	move target out of bounds	The target for mouse interaction is not in the browser’s viewport and cannot be brought into that viewport.
no such alert	400	no such alert	An attempt was made to operate on a modal dialog when one was not open.
no such element	404	no such element	An element could not be located on the page using the given search parameters.
no such frame	400	no such frame	A request to switch to a frame could not be satisfied because the frame could not be found.
no such window	400	no such window	A request to switch to a window could not be satisfied because the window could not be found.
script timeout	408	script timeout	A script did not complete before its timeout expired.
session not created	500	session not created	A new session could not be created.
stale element reference	400	stale element reference	An element command failed because the referenced element is no longer attached to the DOM.
timeout	408	timeout	An operation did not complete before its timeout expired.
unable to set cookie	500	unable to set cookie	A request to set a cookie’s value could not be satisfied.
unable to capture screen	500	unable to capture screen	A screen capture was made impossible.
unexpected alert open	500	unexpected alert open	A modal dialog was open, blocking this operation.
unknown command	404	unknown command	A command could not be executed because the remote end is not aware of it.
unknown error	500	unknown error	An unknown error occurred in the remote end while processing thecommand.
unknown method	405	unknown method	The requested command matched a known URL but did not match an method for that URL.
unsupported operation	500	unsupported operation	Indicates that a command that should have executed properly cannot be supported for some reason.

4.7 Protocol Extensions

The protocol is designed to allow extension to meet vendor-specific needs. Commands that are specific to a user agent are called extension commands and behave no differently than other commands; each has a dedicated HTTP endpoint and a set of remote end steps.

Each extension command has an associated extension command name that is a lowercased ASCII string, and which should bear some resemblance to what the command performs. The name is used to form an extension command’s URL.

The extension command’s extension command URL is a URL composed of the extension prefix, followed by "/", and the extension command’s name. The extension command URL, along with the HTTP method andextension command, is added to the table of endpoints and thus follows the same rules for request routing as that of other built-in commands.

EXAMPLE 3

This might lead to a URL of the form /session/5d376174-36f0-11e5-9b9a-6bdf200a3f7f/moz/context, wheremoz is an extension prefix and the vendor prefix associated with Mozilla, and context the extension command name that, in the context of Firefox, allows a local end to switch between content- and chrome contexts. Requesting this URL will call the extension command’s remote end steps.

The remote end’s extension prefix is a lowercased ASCII string that forms a URL path element, separatingextension commands from other commands to avoid potential resource conflicts with other implementations. It is suggested that vendors use their vendor prefixes without additional characters as outlined in [CSS21], notably insection 4.1.2.2 on vendor keywords, as the name for this path element.