selenium.bridge
The WebDriver server connection that owns one or more sessions.
Bridge
class Bridge;
A connection to a single WebDriver server, whether spawned locally or remote.
W3C describes commands per session, which makes a driver and a session look
like a 1:1 pairing. A Bridge does not follow that assumption. It models the
server process itself and can host many concurrent sessions through sessions,
bounded only by the optional capacity. Each Driver is a handle to one of
those sessions, so several drivers may share a single Bridge.
pid
Pid pid;
Process id of a locally spawned driver, or Pid.init for a remote bridge.
capacity
const int capacity;
Maximum concurrent sessions, fixed at construction. Zero or negative for unlimited.
sessions
Browser[string] sessions;
Active sessions keyed by session id, mapped to their negotiated browser.
this
this(int capacity = 0);
Creates a bridge with the given session capacity.
capacity is fixed at construction and cannot be changed afterwards. A
remote bridge created through Driver.connect uses a capacity of 1 so
that only the connecting session may use it.
Parameters:
| Name | Description |
|---|---|
int capacity |
Maximum concurrent sessions. Zero or negative for unlimited. |
start
static Bridge start(string binary, string[] args = null, int capacity = 0, File childStdin = stdin, File childStdout = stderr, File childStderr = stderr);
Spawns a WebDriver binary on a free port and waits up to five seconds for it to accept requests.
The free port is released before the process starts, so another process can claim it between discovery and the driver's bind. Callers should retry a failed start when operating in an environment with heavy port contention. If the readiness wait fails, the spawned process is not killed.
Parameters:
| Name | Description |
|---|---|
string binary |
Path to the driver executable. |
string[] args |
Extra command-line arguments appended after --port. |
int capacity |
Maximum concurrent sessions. Zero or negative for unlimited. |
File childStdin |
Standard input for the child process. |
File childStdout |
Standard output for the child process, defaulting to caller stderr. |
File childStderr |
Standard error for the child process. |
Returns: A Bridge owning the spawned process.
Throws: InvalidArgumentException if binary is null. ProcessException if the process cannot be spawned. WebDriverConnectionException if the server does not become ready within five seconds.
createSession
string createSession(JSONValue payload, Duration timeout = 60.seconds);
Creates a new session and records its negotiated browser capabilities.
The session is added to sessions only after the response is validated.
Parameters:
| Name | Description |
|---|---|
JSONValue payload |
The new-session capabilities request body. |
Duration timeout |
Maximum time to wait for the session response, defaulting to 60 seconds. |
Returns: The id of the created session.
Throws: WebDriverConnectionException if capacity is reached, the server cannot
be reached, or the new-session response is invalid.
WebDriverException subtypes mapped from a server error response.
closeSession
void closeSession(string id);
Ends a single session and removes it from sessions.
An unknown local id is a no-op. Other failures leave the session in
sessions for retry, except InvalidSessionIdException, which is
swallowed and the session is dropped locally.
Parameters:
| Name | Description |
|---|---|
string id |
The session id to close. |
Throws: WebDriverConnectionException if the delete request fails. WebDriverException subtypes mapped from a server error response.
stop
void stop();
Kills a locally spawned process and clears all session state.
This only affects the local process and sessions; it does not close
remote sessions or send session-delete commands. Calling it more than once
is safe.
status
JSONValue status();
The server status from GET /status, as the raw parsed JSON.
Any WebDriver server answers /status with a {"value": ...} envelope.
For a grid hub the value contains node and slot information; for a standalone
driver it contains readiness and a message. The raw JSON is returned so the
caller can parse it into grid.server.model.GridStatus or inspect it
directly, keeping Bridge decoupled from grid types.
Returns: The parsed GET /status response.
Throws: WebDriverConnectionException if the server cannot be reached or returns an invalid response. UnknownCommandException if the server reports an unknown command or returns a non-JSON 404 or 405 response. WebDriverException subtypes mapped from a non-success response.
get
T get(T = JSONValue)(string id, string path);
Issues a GET against a session and parses the result.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
post
T post(T = JSONValue)(string id, string path);
Issues a parameterless POST against a session, sending an empty JSON object.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
post
T post(T = JSONValue)(string id, string path, JSONValue data);
Issues a POST with a JSONValue body against a session and parses the result.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
JSONValue data |
The JSON request body. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
post
T post(T = JSONValue)(string id, string path, string data);
Issues a POST with a raw string body against a session, without forcing a content type.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
string data |
The raw request body. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
post
T post(T = JSONValue)(string id, string path, string data, string contentType);
Issues a POST with a raw string body and optional content type, using Content-Length.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
string data |
The raw request body. |
string contentType |
The Content-Type header, or null to omit it. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
put
T put(T = JSONValue)(string id, string path, JSONValue data);
Issues a PUT with a JSONValue body against a session and parses the result.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
JSONValue data |
The JSON request body. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
patch
T patch(T = JSONValue)(string id, string path, JSONValue data);
Issues a PATCH with a JSONValue body against a session and parses the result.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
JSONValue data |
The JSON request body. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
del
T del(T = JSONValue)(string id, string path);
Issues a DELETE against a session and parses the result.
Parameters:
| Name | Description |
|---|---|
T |
The response type. JSONValue returns the raw envelope. |
void discards the result. Other types unwrap value and deserialize. |
|
string id |
The active session id. |
string path |
The command path appended after /session/<id>. Must begin with /. |
Returns: The parsed response, or nothing when T is void.
Throws: InvalidSessionIdException if id is not active.
WebDriverConnectionException if the request fails or the response is invalid.
WebDriverException subtypes mapped from server errors.
JSONException if a non-JSONValue T cannot be deserialized.
parseElementId
static string parseElementId(JSONValue json);
Extracts a single element reference from a response.
Accepts both the W3C key and the legacy "ELEMENT" key so responses from older drivers still resolve.
Parameters:
| Name | Description |
|---|---|
JSONValue json |
The response value or envelope. |
Returns: The element reference, or null if none is present.
parseElementIds
static string[] parseElementIds(JSONValue json);
Extracts every element reference from an array response.
Parameters:
| Name | Description |
|---|---|
JSONValue json |
The response value or envelope wrapping an array. |
Returns: The element references in order, or an empty array if none are present.
Malformed array items are returned as null entries.
parseShadowId
static string parseShadowId(JSONValue json);
Extracts a single shadow root reference from a response.
Parameters:
| Name | Description |
|---|---|
JSONValue json |
The response value or envelope. |
Returns: The shadow root reference, or null if none is present.
parseShadowIds
static string[] parseShadowIds(JSONValue json);
Extracts every shadow root reference from an array response.
Parameters:
| Name | Description |
|---|---|
JSONValue json |
The response value or envelope wrapping an array. |
Returns: The shadow root references in order, or an empty array if none are present.
Malformed array items are returned as null entries.
unwrapAndParse
T unwrapAndParse(T)(JSONValue json);
Deserializes T from a response, unwrapping a value envelope if present.
Any object containing a value key is treated as an envelope. T ==
JSONValue returns the unwrapped value, dynamic arrays other than string
are parsed item by item, and other types are converted with get!T.
Parameters:
| Name | Description |
|---|---|
T |
The target type. |
JSONValue json |
The response value or envelope. |
Returns: The unwrapped and deserialized value.
Throws: JSONException if json cannot be converted to T.
parseSession
static Browser parseSession(JSONValue json, out string id);
Parses a W3C new-session response into browser capabilities.
Parameters:
| Name | Description |
|---|---|
JSONValue json |
The new-session response envelope. |
string id |
Receives the non-empty session id from value.sessionId. |
Returns: The browser capabilities parsed from value.capabilities.
Throws: WebDriverConnectionException if json is not an object, value is
missing or not an object, value.sessionId is missing, empty, or not a
string, or value.capabilities is missing or not an object.