How can I manage cookies in Puppeteer-Sharp?

Cookie management is essential for maintaining authentication sessions and tracking user preferences in web automation with Puppeteer-Sharp. This .NET port of Puppeteer provides comprehensive cookie management through the Page class's built-in methods.

Setting Cookies

Use the SetCookieAsync method to set cookies. Create CookieParam objects with required properties:

using PuppeteerSharp;

var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
var page = await browser.NewPageAsync();

var cookieParam = new CookieParam
{
    Name = "sessionId",
    Value = "abc123xyz",
    Domain = "example.com",
    Path = "/",
    HttpOnly = true,
    Secure = true
};

await page.SetCookieAsync(cookieParam);

Setting Multiple Cookies

You can set multiple cookies at once by passing an array:

var cookies = new[]
{
    new CookieParam { Name = "userId", Value = "12345", Domain = "example.com" },
    new CookieParam { Name = "theme", Value = "dark", Domain = "example.com" },
    new CookieParam { Name = "language", Value = "en", Domain = "example.com" }
};

await page.SetCookieAsync(cookies);

Getting Cookies

Retrieve cookies using the GetCookiesAsync method. You can get all cookies or filter by URL:

// Get all cookies for the current page
var allCookies = await page.GetCookiesAsync();

// Get cookies for specific URLs
var specificCookies = await page.GetCookiesAsync("https://example.com", "https://api.example.com");

foreach (var cookie in allCookies)
{
    Console.WriteLine($"Name: {cookie.Name}, Value: {cookie.Value}, Domain: {cookie.Domain}");
}

Filtering and Processing Cookies

var cookies = await page.GetCookiesAsync();

// Find specific cookies
var authCookie = cookies.FirstOrDefault(c => c.Name == "authToken");
var sessionCookies = cookies.Where(c => c.Name.Contains("session")).ToArray();

// Check cookie properties
foreach (var cookie in cookies)
{
    Console.WriteLine($"Cookie: {cookie.Name}");
    Console.WriteLine($"  Secure: {cookie.Secure}");
    Console.WriteLine($"  HttpOnly: {cookie.HttpOnly}");
    Console.WriteLine($"  Expires: {cookie.Expires}");
}

Deleting Cookies

Remove specific cookies using the DeleteCookieAsync method:

// Delete a single cookie
var cookieToDelete = new CookieParam
{
    Name = "sessionId",
    Domain = "example.com"
};
await page.DeleteCookieAsync(cookieToDelete);

// Delete multiple cookies
var cookiesToDelete = new[]
{
    new CookieParam { Name = "tempData", Domain = "example.com" },
    new CookieParam { Name = "cache", Domain = "example.com" }
};
await page.DeleteCookieAsync(cookiesToDelete);

Clearing All Cookies

Clear all cookies for the current browser context:

// Clear all cookies in the current context
await page.BrowserContext.ClearCookiesAsync();

// Or create a new incognito context for clean slate
var context = await browser.CreateIncognitoBrowserContextAsync();
var cleanPage = await context.NewPageAsync();

Cookie Properties and Options

When setting cookies, you can specify various properties:

var comprehensiveCookie = new CookieParam
{
    Name = "userPrefs",
    Value = "advanced",
    Domain = ".example.com",        // Domain scope
    Path = "/dashboard",            // Path scope
    Expires = DateTimeOffset.Now.AddDays(30).ToUnixTimeSeconds(), // Expiration
    HttpOnly = true,               // Prevent JS access
    Secure = true,                 // HTTPS only
    SameSite = SameSite.Strict     // CSRF protection
};

await page.SetCookieAsync(comprehensiveCookie);

Practical Example: Login Session Management

Here's a complete example demonstrating cookie management for login sessions:

using System;
using System.Linq;
using System.Threading.Tasks;
using PuppeteerSharp;

class CookieManager
{
    public static async Task Main(string[] args)
    {
        await new BrowserFetcher().DownloadAsync();
        var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = false });
        var page = await browser.NewPageAsync();

        try
        {
            // Navigate to login page
            await page.GoToAsync("https://example.com/login");

            // Check if already logged in by looking for auth cookies
            var existingCookies = await page.GetCookiesAsync();
            var authToken = existingCookies.FirstOrDefault(c => c.Name == "authToken");

            if (authToken == null)
            {
                Console.WriteLine("No existing session found. Setting login cookies...");

                // Simulate setting login cookies (normally you'd perform actual login)
                await page.SetCookieAsync(new CookieParam
                {
                    Name = "authToken",
                    Value = "jwt_token_here",
                    Domain = "example.com",
                    HttpOnly = true,
                    Secure = true
                });

                await page.SetCookieAsync(new CookieParam
                {
                    Name = "sessionId",
                    Value = Guid.NewGuid().ToString(),
                    Domain = "example.com",
                    Expires = DateTimeOffset.Now.AddHours(8).ToUnixTimeSeconds()
                });
            }
            else
            {
                Console.WriteLine($"Existing session found: {authToken.Value}");
            }

            // Refresh page to use new cookies
            await page.ReloadAsync();

            // Verify cookies are working
            var currentCookies = await page.GetCookiesAsync();
            Console.WriteLine($"Active cookies: {currentCookies.Length}");

            // Clean up when done
            Console.WriteLine("Logging out - clearing session cookies...");
            var sessionCookies = currentCookies
                .Where(c => c.Name.Contains("session") || c.Name.Contains("auth"))
                .Select(c => new CookieParam { Name = c.Name, Domain = c.Domain })
                .ToArray();

            if (sessionCookies.Length > 0)
            {
                await page.DeleteCookieAsync(sessionCookies);
                Console.WriteLine("Session cookies cleared.");
            }
        }
        finally
        {
            await browser.CloseAsync();
        }
    }
}

Best Practices

1. Always specify the domain when setting cookies to ensure they're sent to the correct server
2. Use HttpOnly and Secure flags for sensitive cookies like authentication tokens
3. Set appropriate expiration times to balance security and user experience
4. Clean up cookies after testing to avoid interference between test runs
5. Handle cookie errors gracefully as some websites may block cookie manipulation

Error Handling

try
{
    await page.SetCookieAsync(new CookieParam
    {
        Name = "testCookie",
        Value = "testValue",
        Domain = "example.com"
    });
}
catch (PuppeteerException ex)
{
    Console.WriteLine($"Failed to set cookie: {ex.Message}");
    // Handle the error appropriately
}

Cookie management in Puppeteer-Sharp is straightforward once you understand the CookieParam object and the available async methods. This enables you to maintain sessions, handle authentication, and manage user preferences effectively in your web automation scripts.