Storage Module

The Storage module provides functionality for managing cookies.

Overview

The Storage module allows you to:

• Get, set, and delete cookies

Accessing the Module

StorageModule storage = driver.Storage;

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.

Working with Cookies

Get All Cookies

GetCookiesCommandParameters parameters = new GetCookiesCommandParameters();
parameters.Partition = new BrowsingContextPartitionDescriptor(contextId);

GetCookiesCommandResult result = await driver.Storage.GetCookiesAsync(parameters);

foreach (Cookie cookie in result.Cookies)
{
    Console.WriteLine($"Name: {cookie.Name}");
    Console.WriteLine($"Value: {cookie.Value.Value}");
    Console.WriteLine($"Domain: {cookie.Domain}");
    Console.WriteLine($"Path: {cookie.Path}");
    Console.WriteLine($"Secure: {cookie.Secure}");
    Console.WriteLine($"HttpOnly: {cookie.HttpOnly}");
    Console.WriteLine($"SameSite: {cookie.SameSite}");
}

The GetCookiesCommandResult also reports the storage PartitionKey the cookies were retrieved from, and SetCookieAsync's result likewise carries the partition key the cookie was set in.

Get Cookies by Filter

GetCookiesCommandParameters parameters = new GetCookiesCommandParameters();
parameters.Partition = new BrowsingContextPartitionDescriptor(contextId);
parameters.Filter = new CookieFilter
{
    Name = "sessionId"
};

GetCookiesCommandResult result = await driver.Storage.GetCookiesAsync(parameters);

Set Cookie

PartialCookie cookie = new PartialCookie(
    "sessionId",
    BytesValue.FromString("abc123"),
    "example.com")
{
    Path = "/",
    Secure = true,
    HttpOnly = true,
    SameSite = CookieSameSiteValue.Strict
};

SetCookieCommandParameters parameters = new SetCookieCommandParameters(cookie);
await driver.Storage.SetCookieAsync(parameters);

Set Cookie with Expiry

PartialCookie cookie = new PartialCookie(
    "rememberMe",
    BytesValue.FromString("true"),
    "example.com")
{
    Path = "/",
    Expires = DateTimeOffset.Now.AddDays(30).UtcDateTime
};

SetCookieCommandParameters parameters = new SetCookieCommandParameters(cookie);
await driver.Storage.SetCookieAsync(parameters);

Delete Cookie

CookieFilter filter = new CookieFilter
{
    Name = "sessionId",
    Domain = "example.com"
};

DeleteCookiesCommandParameters parameters = new DeleteCookiesCommandParameters();
parameters.Filter = filter;

await driver.Storage.DeleteCookiesAsync(parameters);

Delete All Cookies

DeleteCookiesCommandParameters parameters = new DeleteCookiesCommandParameters();
parameters.Partition = new BrowsingContextPartitionDescriptor(contextId);

await driver.Storage.DeleteCookiesAsync(parameters);

Common Patterns

Save and Restore Session

// Save cookies
GetCookiesCommandResult savedCookies = await driver.Storage.GetCookiesAsync(
    new GetCookiesCommandParameters
    {
        Partition = new BrowsingContextPartitionDescriptor(contextId)
    });

// ... later, restore cookies
foreach (Cookie cookie in savedCookies.Cookies)
{
    PartialCookie newCookie = new PartialCookie(cookie.Name, cookie.Value, cookie.Domain)
    {
        Path = cookie.Path,
        Secure = cookie.Secure,
        HttpOnly = cookie.HttpOnly,
        SameSite = cookie.SameSite,
        Expires = cookie.Expires
    };

    await driver.Storage.SetCookieAsync(new SetCookieCommandParameters(newCookie));
}

Clean State Between Tests

// Clear all cookies
await driver.Storage.DeleteCookiesAsync(
    new DeleteCookiesCommandParameters
    {
        Partition = new BrowsingContextPartitionDescriptor(contextId)
    });

Set Authentication Cookie

PartialCookie authCookie = new PartialCookie(
    "authToken",
    BytesValue.FromString("your-auth-token"),
    "example.com")
{
    Path = "/",
    Secure = true,
    HttpOnly = true,
    SameSite = CookieSameSiteValue.Strict
};

SetCookieCommandParameters parameters = new SetCookieCommandParameters(authCookie);
await driver.Storage.SetCookieAsync(parameters);

// Now navigate - cookie will be sent
await driver.BrowsingContext.NavigateAsync(
    new NavigateCommandParameters(contextId, "https://example.com/dashboard"));

Best Practices

1. Set cookies before navigation: Set cookies before navigating to the domain
2. Match domains correctly: Give the cookie the domain you intend to read it back from; storage.setCookie does not require it to match the page currently loaded
3. Use appropriate SameSite: Choose Strict, Lax, or None based on needs; cookies the browser reports without an explicit policy have CookieSameSiteValue.Default
4. Clean up between tests: Clear cookies and storage for test isolation
5. Handle secure cookies: Set Secure flag for HTTPS-only cookies

Error Handling

Commands in this module throw WebDriverBiDiCommandException when the browser returns a protocol error response (for example, when cookie data is invalid or the target partition cannot be found), 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

• Browser Module: Managing user contexts
• Network Module: Monitoring cookie-related network traffic
• API Reference: Complete API documentation