Table of Contents

Session Module

The Session module manages the WebDriver BiDi session and event subscriptions.

Overview

The Session module provides:

  • Creating new BiDi sessions
  • Session status checking
  • Event subscription management
  • Session capability negotiation

Accessing the Module

SessionModule session = driver.Session;

Timeout and Cancellation

All commands in this module accept optional timeoutOverride and CancellationToken parameters. Use timeoutOverride to set a per-command timeout (defaults to BiDiDriver.DefaultCommandTimeout when omitted). Use CancellationToken for cooperative cancellation. See the API Design Guide for details and examples.

Creating a New Session

Use NewSessionAsync to create a WebDriver BiDi session when the endpoint you connected to has none yet: Firefox launched with --remote-debugging-port (ws://localhost:PORT/session), geckodriver's BiDi-only /session endpoint, or a BiDi-over-CDP mapper. Do not call it on the webSocketUrl returned by a classic new-session request to chromedriver, msedgedriver, geckodriver or Selenium — that session already exists, and the call fails. See Browser Setup.

Create New Session

Call NewSessionAsync after StartAsync when the browser requires explicit session creation:

NewCommandParameters parameters = new NewCommandParameters();

NewCommandResult result = await driver.Session.NewSessionAsync(parameters);

string sessionId = result.SessionId;
Console.WriteLine($"Session ID: {result.SessionId}");
Console.WriteLine($"Browser: {result.Capabilities.BrowserName} {result.Capabilities.BrowserVersion}");

The result provides SessionId and Capabilities (browser name, version, platform, and other negotiated capabilities).

Create Session with Capability Requests

Use NewCommandParameters.Capabilities to request specific session capabilities. Set AlwaysMatch for required capabilities or add capabilities to FirstMatch for a list of capability sets (the first matching set is used):

CapabilityRequest capabilities = new CapabilityRequest
{
    BrowserName = "chrome",
    AcceptInsecureCerts = true,
};

NewCommandParameters parameters = new NewCommandParameters
{
    Capabilities = new CapabilitiesRequest
    {
        AlwaysMatch = capabilities,
    },
};

NewCommandResult result = await driver.Session.NewSessionAsync(parameters);

Supported capability requests include BrowserName, BrowserVersion, PlatformName, AcceptInsecureCerts, Proxy, and UnhandledPromptBehavior. See CapabilityRequest and CapabilitiesRequest in the API reference for the full set.

Session Status

Check Session Status

StatusCommandParameters parameters = new StatusCommandParameters();
StatusCommandResult result = await driver.Session.StatusAsync(parameters);

Console.WriteLine($"Is ready: {result.IsReady}");
Console.WriteLine($"Message: {result.Message}");

Event Subscription

Subscribe to Events

Prefer the EventName property from observable events to avoid typos:

SubscribeCommandParameters subscribe =
    new SubscribeCommandParameters(driver.Log.OnEntryAdded.EventName);
subscribe.Events.Add(driver.Network.OnResponseCompleted.EventName);
subscribe.Events.Add(driver.BrowsingContext.OnLoad.EventName);

SubscribeCommandResult result = await driver.Session.SubscribeAsync(subscribe);

Subscribe with Context Filter

SubscribeCommandParameters subscribe =
    new SubscribeCommandParameters(driver.Network.OnBeforeRequestSent.EventName);

// Only receive events for this specific context
subscribe.Contexts.Add(contextId);

await driver.Session.SubscribeAsync(subscribe);

Unsubscribe by ID

// Unsubscribe by subscription ID
UnsubscribeByIdsCommandParameters unsubscribe =
    new UnsubscribeByIdsCommandParameters(subscriptionId);
await driver.Session.UnsubscribeAsync(unsubscribe);

Unsubscribe by Event Names

// Or unsubscribe by event names
UnsubscribeByAttributesCommandParameters unsubscribe =
    new UnsubscribeByAttributesCommandParameters(
        [driver.Log.OnEntryAdded.EventName, driver.Network.OnResponseCompleted.EventName]);
await driver.Session.UnsubscribeAsync(unsubscribe);

Ending a Session

EndAsync ends the current session. The remote end removes the session, replies, and then cleans up session-scoped state: it closes the WebSocket connections, discards per-user-context overrides and blocked-request state, removes network data collectors, and stops screencasts. Whether the browser or its windows close as well is implementation-specific; use Browser.CloseAsync to terminate the browser. The EndCommandParameters argument is optional; call EndAsync() with no arguments to end the session with default parameters. Ending the session is distinct from calling BiDiDriver.StopAsync, which closes the local transport connection without issuing a session.end command.

Best Practices

  1. Subscribe early: Subscribe to events before triggering actions that produce them
  2. Track subscription IDs: Store IDs if you need to unsubscribe later
  3. Use context filtering: Limit events to specific contexts when possible
  4. Clean up subscriptions: Unsubscribe when events are no longer needed

Error Handling

Commands in this module throw WebDriverBiDiCommandException when the browser returns a protocol error response (for example, when SubscribeAsync is called with an unrecognized event name), and WebDriverBiDiTimeoutException when a command exceeds its timeout. See the Error Handling guide for full details on exception types, TransportErrorBehavior options, and recommended catch patterns.

Next Steps

Edit this page