`selenium.driver`

A handle to a WebDriver session and its navigation commands.

`Driver`

class Driver;

A handle to a single WebDriver session.

W3C and most clients treat a driver as 1:1 with a session, but that is not the shape here. A Bridge can own several sessions at once, and each Driver is a handle to exactly one of them, so multiple drivers may share a single Bridge.

Unlike Bridge, a Driver does not destruct automatically. stop ends only this driver's session and deliberately leaves the Bridge alive for its other sessions.

`bridge`

Bridge bridge;

The connection hosting this session.

`browser`

Browser browser;

The browser whose capabilities were negotiated for this session.

`logger`

Logger logger;

The logger aggregating client, driver, and remote logging for this session.

`id`

string id;

The W3C session id.

`Timeouts`

template Timeouts()

Live session timeout commands, accessed through the timeouts alias.

Getters return cached negotiated values. Setters send whole milliseconds and, on success, cache the original duration.

Sub-millisecond values truncate to zero and negatives aren't validated.

`implicit`

@property Duration implicit() const;

The current element-location wait.

`implicit`

@property void implicit(Duration value);

Sets the element-location wait on the remote session.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`pageLoad`

@property Duration pageLoad() const;

The current page-load wait.

`pageLoad`

@property void pageLoad(Duration value);

Sets the page-load wait on the remote session.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`script`

@property Duration script() const;

The current script wait.

`script`

@property void script(Duration value);

Sets the script wait on the remote session.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`timeouts`

alias timeouts = Timeouts!();

Live session timeout commands, accessed through the timeouts alias.

`start`

static Driver start(Bridge bridge, Browser alwaysMatch, Browser[] firstMatch, Logger logger = null, Duration timeout = 60.seconds);

Starts a session on an existing bridge.

Each browser's logging configuration is merged into the logger before the capabilities are built, so per-browser preferences propagate upward into the single session logger. The capabilities use alwaysMatch for the required browser and firstMatch for acceptable alternatives. alwaysMatch and every firstMatch entry must be non-null.

Parameters:

Name	Description
`Bridge bridge`	The connection to create the session on.
`Browser alwaysMatch`	The required browser capabilities.
`Browser[] firstMatch`	Alternative capability sets the server may pick from.
`Logger logger`	The logger to attach, or null to create a default one.
`Duration timeout`	Maximum time to wait for the session response, defaulting to 60 seconds.

Returns: A driver bound to the new session.

Throws: WebDriverConnectionException if the session cannot be created. WebDriverException subtypes mapped from a server error response.

`start`

static Driver start(Browser alwaysMatch, Browser[] firstMatch = null, Logger logger = null, Duration timeout = 60.seconds);

Resolves a driver binary, spawns a bridge for it, and starts a session.

Convenience entry point for the common case of owning a freshly spawned driver process. Driver-process logging arguments are derived from the logger.

firstMatch is not considered for binary resolution.

alwaysMatch and every firstMatch entry must be non-null.

Parameters:

Name	Description
`Browser alwaysMatch`	The required browser capabilities, also used to resolve the binary.
`Browser[] firstMatch`	Alternative capability sets the server may pick from.
`Logger logger`	The logger to attach, or null to create a default one.
`Duration timeout`	Maximum time to wait for the session response, defaulting to 60 seconds.

Returns: A driver bound to a session on a newly spawned bridge.

Throws: WebDriverConnectionException if no binary is found or the session cannot be created. ProcessException if the process cannot be spawned. WebDriverException subtypes mapped from a server error response.

`start`

static Driver start();

Starts a session with a generic browser, letting the first driver on PATH win.

Returns: A driver bound to a session on a newly spawned bridge.

Throws: WebDriverConnectionException if no driver binary is found or the session cannot be created. ProcessException if the process cannot be spawned. WebDriverException subtypes mapped from a server error response.

`connect`

static Driver connect(string address, Browser alwaysMatch, Browser[] firstMatch = null, Logger logger = null, Duration timeout = 60.seconds);

Connects to a remote WebDriver server or grid and starts a session on it.

The created Bridge has a capacity of 1, so only this driver's session may use it. The bridge does not own a process, so stop will not kill the remote server. The address is used verbatim; a trailing slash is not normalized. alwaysMatch and every firstMatch entry must be non-null. This is the entry point for remote endpoints and grids, mirroring Ruby's RemoteWebDriver.

Parameters:

Name	Description
`string address`	Base URL of the running server.
`Browser alwaysMatch`	The required browser capabilities.
`Browser[] firstMatch`	Alternative capability sets the server may pick from.
`Logger logger`	The logger to attach, or null to create a default one.
`Duration timeout`	Maximum time to wait for the session response, defaulting to 60 seconds.

Returns: A driver bound to a session on the remote server.

Throws: WebDriverConnectionException if the session cannot be created. WebDriverException subtypes mapped from a server error response.

`stop`

void stop();

Ends this session, leaving the bridge and its other sessions intact.

The bridge and any local driver process remain alive; call bridge.stop to kill a locally spawned process.

Throws: WebDriverConnectionException if the close request fails. WebDriverException subtypes mapped from a server error response.

`url`

string url();

The current document URL.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`title`

string title();

The current document title.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`source`

string source();

The serialized source of the current document.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`screenshot`

string screenshot();

A base64 PNG screenshot of the current viewport.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`print`

string print(PrintOptions options = PrintOptions());

Prints the current page to a PDF document.

Parameters:

Name	Description
`PrintOptions options`	Print configuration, defaulting to portrait US Letter at 100% scale.

Returns: A base64-encoded PDF document.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. UnsupportedOperationException if the driver does not support printing. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`go`

void go(string url);

Navigates the session to a URL.

Parameters:

Name	Description
`string url`	The destination URL.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`back`

void back();

Navigates back one entry in history.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`forward`

void forward();

Navigates forward one entry in history.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`refresh`

void refresh();

Reloads the current document.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`Alert`

template Alert()

Alert commands, accessed through the alert alias.

`text`

string text();

The text displayed by the current alert or prompt.

Throws: NoSuchAlertException if no alert is open. UnexpectedAlertOpenException if an unexpected alert is open. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`accept`

void accept();

Accepts the current alert, confirmation, or prompt.

Throws: NoSuchAlertException if no alert is open. UnexpectedAlertOpenException if an unexpected alert is open. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`dismiss`

void dismiss();

Dismisses the current alert, confirmation, or prompt.

Throws: NoSuchAlertException if no alert is open. UnexpectedAlertOpenException if an unexpected alert is open. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`sendKeys`

void sendKeys(string[] keys...);

Types text into the current prompt.

The arguments are concatenated with no separator before being sent.

Parameters:

Name	Description
`string[] keys`	One or more strings to type in order.

Throws: NoSuchAlertException if no alert is open. UnexpectedAlertOpenException if an unexpected alert is open. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`alert`

alias alert = Alert!();

Alert command group, e.g. driver.alert.text or driver.alert.accept().

`activeElement`

Element activeElement();

The element that currently has focus.

Wraps Bridge.parseElementId; a null reference produces an Element with a null id.

Returns: A handle to the focused element.

Throws: InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`root`

Root root();

The primary document root.

The returned root currently has RootState.Complete regardless of the live document readiness.

Returns: A primary root handle.

`roots`

Root[] roots();

Discovers the primary document, top-level iframes, and open shadow roots.

Requires JavaScript execution. The primary document is always first. This does not traverse iframe documents, iframes inside shadow roots, or closed shadow roots. RootState.Loaded is never produced, and Closed is not discoverable through this method.

Returns: The discovered roots.

Throws: InvalidSessionIdException if the session is not active. JavaScriptException if the discovery script throws. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response shape is invalid.

`find`

Element find(By by);

Finds the first element matching the locator.

Parameters:

Name	Description
`By by`	The location strategy and selector.

Returns: A handle to the matched element.

Throws: NoSuchElementException if no element matches. InvalidSelectorException if the locator is rejected. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`findAll`

Element[] findAll(By by);

Finds every element matching the locator.

Parameters:

Name	Description
`By by`	The location strategy and selector.

Returns: Handles to all matched elements, or an empty array if none match.

Throws: InvalidSelectorException if the locator is rejected. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`execute`

T execute(T = string)(string script, JSONValue args = JSONValue.emptyArray);

Runs a synchronous script in the page and returns its typed result.

When T is Element or Element[] the returned references are wrapped into handles, otherwise the result is deserialized into T. args must be a JSON array; Element arguments must already be converted with toJSON.

Parameters:

Name	Description
`T`	The result type.
`string script`	The script body, which may return a value.
`JSONValue args`	The arguments exposed to the script as `arguments`.

Returns: The script result as T.

Throws: InvalidSessionIdException if the session is not active. JavaScriptException if the script throws during evaluation. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if a non-JSONValue T cannot be deserialized.

`executeAsync`

T executeAsync(T = JSONValue)(string script, JSONValue args = JSONValue.emptyArray, Duration timeout = Duration.init);

Runs an asynchronous script in the page and returns its typed callback result.

WebDriver injects the completion callback as the last element of arguments. The script must invoke it exactly once with the value to return.

Parameters:

Name	Description
`T`	The callback result type.
`string script`	The script body, which must invoke the injected completion callback.
`JSONValue args`	The arguments exposed before the callback in `arguments`.
Element arguments must already be converted with `toJSON`.
`Duration timeout`	A per-call script timeout override, or `Duration.init` to use the session timeout.
Timeouts apply only to this call.

Returns: The callback result as T.

Throws: ScriptTimeoutException if the callback does not run within the script timeout. JavaScriptException if the script throws during evaluation. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if a non-JSONValue T cannot be deserialized.

`Window`

template Window()

Window and tab commands, accessed through the window alias.

`handle`

string handle();

The handle of the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.

`handles`

string[] handles();

Handles of all open windows.

Throws: NoSuchWindowException if the current window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not an array of strings.

`size`

Size size();

The size of the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response shape is invalid.

`position`

@property Position position();

The position of the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response shape is invalid.

`rect`

@property Rect rect();

The full rectangle of the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response shape is invalid.

`close`

void close();

Closes the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`maximize`

void maximize();

Maximizes the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`fullscreen`

void fullscreen();

Makes the current window fullscreen.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`minimize`

void minimize();

Minimizes the current window.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`resize`

void resize(Size value);

Resizes the current window.

Parameters:

Name	Description
`Size value`	The new window size.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`position`

@property void position(Position value);

Moves the current window to the given position.

Parameters:

Name	Description
`Position value`	The new window position.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`rect`

@property void rect(Rect value);

Sets the full rectangle of the current window.

Parameters:

Name	Description
`Rect value`	The new window rectangle.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`switchTo`

void switchTo(string handle);

Switches focus to the window with the given handle.

Parameters:

Name	Description
`string handle`	The target window handle.

Throws: NoSuchWindowException if the window no longer exists. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`open`

string open(string type = "tab");

Opens a new window or tab and returns its handle.

Parameters:

Name	Description
`string type`	"tab" or "window", defaulting to "tab".

Returns: The new window handle.

Throws: NoSuchWindowException if the current window no longer exists. InvalidArgumentException if the driver rejects the window type. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response shape is invalid.

`window`

alias window = Window!();

Window command group, e.g. driver.window.handles.

`Frame`

template Frame()

Frame switching commands, accessed through the frame alias.

`switchTo`

void switchTo();

Switches focus to the top-level browsing context.

Throws: NoSuchFrameException if the current frame is no longer available. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`switchTo`

void switchTo(long id);

Switches focus to the frame at the given index.

Parameters:

Name	Description
`long id`	The frame index.

Throws: InvalidArgumentException if id is negative. NoSuchFrameException if no frame has that index. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`switchTo`

void switchTo(Element element);

Switches focus to the frame identified by the given element.

Parameters:

Name	Description
`Element element`	The frame element.

Throws: NoSuchFrameException if the element is not a frame. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`switchToParent`

void switchToParent();

Switches focus to the parent of the current frame.

Throws: NoSuchFrameException if there is no parent frame. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.

`frame`

alias frame = Frame!();

Frame command group, e.g. driver.frame.switchTo(0).