Table of Contents

Browser Module

The Browser module provides browser-level operations including managing user contexts and controlling browser windows.

Overview

The Browser module allows you to:

  • Manage user contexts (profiles/incognito)
  • Control browser window state
  • Set download behavior
  • Close the browser

Accessing the Module

BrowserModule browser = driver.Browser;

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.

User Contexts

User contexts represent isolated browsing sessions (similar to browser profiles or incognito windows).

Create User Context

CreateUserContextCommandParameters parameters = new CreateUserContextCommandParameters();
CreateUserContextCommandResult result = await driver.Browser.CreateUserContextAsync(parameters);

string userContextId = result.UserContextId;
Console.WriteLine($"Created user context: {userContextId}");

Get User Contexts

GetUserContextsCommandParameters parameters = new GetUserContextsCommandParameters();
GetUserContextsCommandResult result = await driver.Browser.GetUserContextsAsync(parameters);

foreach (UserContextInfo context in result.UserContexts)
{
    Console.WriteLine($"User context: {context.UserContextId}");
}

Remove User Context

RemoveUserContextCommandParameters @params =
    new RemoveUserContextCommandParameters(userContextId);

await driver.Browser.RemoveUserContextAsync(@params);

Create Tab in User Context

CreateUserContextCommandResult userContextResult =
    await driver.Browser.CreateUserContextAsync(new CreateUserContextCommandParameters());

// Create browsing context in that user context
CreateCommandParameters createTabParams = new CreateCommandParameters(CreateType.Tab)
{
    UserContextId = userContextResult.UserContextId
};

CreateCommandResult tabResult = await driver.BrowsingContext.CreateAsync(createTabParams);

Client Windows

Client windows represent the browser window frames.

Get Client Windows

GetClientWindowsCommandParameters parameters = new GetClientWindowsCommandParameters();
GetClientWindowsCommandResult result = await driver.Browser.GetClientWindowsAsync(parameters);

foreach (ClientWindowInfo window in result.ClientWindows)
{
    Console.WriteLine($"Window: {window.ClientWindowId}");
    Console.WriteLine($"  State: {window.State}");
    Console.WriteLine($"  Width: {window.Width}");
    Console.WriteLine($"  Height: {window.Height}");
}

Set Window State

// Get the client window
GetClientWindowsCommandResult windowsResult =
    await driver.Browser.GetClientWindowsAsync(new GetClientWindowsCommandParameters());

string clientWindowId = windowsResult.ClientWindows[0].ClientWindowId;

// Maximize window
SetClientWindowStateCommandParameters parameters =
    new SetClientWindowStateCommandParameters(clientWindowId)
    {
        State = ClientWindowState.Maximized,
    };

await driver.Browser.SetClientWindowStateAsync(parameters);

// Other states: Minimized, Fullscreen, Normal

Set Window Size

SetClientWindowStateCommandParameters parameters =
    new SetClientWindowStateCommandParameters(clientWindowId)
    {
        State = ClientWindowState.Normal,
        Width = 1280,
        Height = 720
    };

await driver.Browser.SetClientWindowStateAsync(parameters);

Download Behavior

Control how the browser handles downloads.

Allow Downloads

SetDownloadBehaviorCommandParameters parameters = new SetDownloadBehaviorCommandParameters();
parameters.DownloadBehavior = new DownloadBehaviorAllowed("/path/to/downloads");

await driver.Browser.SetDownloadBehaviorAsync(parameters);

Deny Downloads

SetDownloadBehaviorCommandParameters parameters = new SetDownloadBehaviorCommandParameters();
parameters.DownloadBehavior = new DownloadBehaviorDenied();

await driver.Browser.SetDownloadBehaviorAsync(parameters);

Reset Download Behavior

To remove a download behavior override and restore the browser's default handling, pass SetDownloadBehaviorCommandParameters.ResetDownloadBehavior. It returns a new instance on each access, so you can add entries to its UserContexts to reset the behavior for those user contexts only:

await driver.Browser.SetDownloadBehaviorAsync(SetDownloadBehaviorCommandParameters.ResetDownloadBehavior);

Closing Browser

Close Browser

CloseCommandParameters parameters = new CloseCommandParameters();
await driver.Browser.CloseAsync(parameters);

Note: This closes the entire browser, not just a tab. To close a tab, use BrowsingContext.CloseAsync, passing a CloseCommandParameters identifying the browsing context to close.

Common Patterns

Isolated Session Pattern

// Create isolated user context
CreateUserContextCommandResult userContext =
    await driver.Browser.CreateUserContextAsync(new CreateUserContextCommandParameters());

// Create tab in isolated context
CreateCommandParameters tabParams = new CreateCommandParameters(CreateType.Tab)
{
    UserContextId = userContext.UserContextId
};
CreateCommandResult tab = await driver.BrowsingContext.CreateAsync(tabParams);

// Use the tab...
await driver.BrowsingContext.NavigateAsync(
    new NavigateCommandParameters(tab.BrowsingContextId, "https://example.com"));

// Clean up: close tab and remove context
// WebDriverBiDi.BrowsingContext.CloseCommandParameters is aliased as BrowsingContextCloseCommandParameters.
await driver.BrowsingContext.CloseAsync(
    new BrowsingContextCloseCommandParameters(tab.BrowsingContextId));
await driver.Browser.RemoveUserContextAsync(
    new RemoveUserContextCommandParameters(userContext.UserContextId));

Multi-Window Testing

// Create multiple windows
List<string> windowIds = new List<string>();

for (int i = 0; i < 3; i++)
{
    CreateCommandResult window = await driver.BrowsingContext.CreateAsync(
        new CreateCommandParameters(CreateType.Window));
    windowIds.Add(window.BrowsingContextId);
}

// Get client windows and manipulate them
GetClientWindowsCommandResult clientWindows =
    await driver.Browser.GetClientWindowsAsync(new GetClientWindowsCommandParameters());

foreach (ClientWindowInfo window in clientWindows.ClientWindows)
{
    // Tile windows side by side
    await driver.Browser.SetClientWindowStateAsync(
        new SetClientWindowStateCommandParameters(window.ClientWindowId)
        {
            State = ClientWindowState.Normal,
            Width = 640,
            Height = 480
        });
}

Best Practices

  1. Clean up user contexts: Remove user contexts when done to free resources
  2. Use default context: The default user context exists automatically
  3. Test window states: Not all window states work on all platforms
  4. Handle downloads carefully: Set download behavior before triggering downloads

Error Handling

Commands in this module throw WebDriverBiDiCommandException when the browser returns a protocol error response, 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