How to Manage Cookies for Session Persistence in Zendriver: A Complete Guide

Zendriver provides a CookieJar class that wraps Chrome DevTools Protocol (CDP) storage commands to save, load, and clear cookies, enabling persistent sessions across browser restarts via the save() and load() methods.

Managing cookies for session persistence in Zendriver is essential for automating workflows that require authentication or maintaining state across script executions. The library leverages the Chrome DevTools Protocol to interact with the browser's storage layer directly. This guide explains how to use Zendriver's CookieJar API to persist sessions using practical code examples from the source.

Understanding Zendriver's Cookie Architecture

The CookieJar Class

The CookieJar class, defined in zendriver/core/browser.py, serves as the primary interface for cookie management. It is lazily instantiated when you access browser.cookies on a Browser instance. This wrapper abstracts the complexity of CDP commands into simple Python methods including get_all(), save(), load(), and clear().

CDP Storage Domain Integration

Under the hood, CookieJar communicates with the browser using the CDP Storage domain commands located in zendriver/cdp/storage.py. It utilizes Storage.get_cookies to retrieve cookies, Storage.set_cookies to restore them, and Storage.clear_cookies to wipe them. The class automatically resolves a connection to the first active tab or falls back to the browser connection if no tabs are open.

Saving and Loading Cookies for Session Persistence

Basic Session Persistence Workflow

To maintain a session across script runs, save cookies after authentication and load them when restarting the browser. The default storage file is .session.dat, but you can specify any path.

import asyncio
from zendriver import Browser

async def main():
    # Start browser and authenticate

    browser = await Browser.create(headless=True)
    page = await browser.get("https://example.com/login")
    await page.type("#username", "user")
    await page.type("#password", "pass")
    await page.click("#submit")
    await page.wait_for_navigation()
    
    # Save cookies for persistence

    await browser.cookies.save(file=".my_session.dat")
    print("Cookies saved")
    
    # Shut down the browser

    await browser.stop()
    
    # Later: restore session

    browser2 = await Browser.create(headless=True)
    await browser2.cookies.load(file=".my_session.dat")
    print("Cookies loaded")
    
    # Access protected page without logging in again

    page2 = await browser2.get("https://example.com/dashboard")
    print("Page title:", await page2.title())
    
    await browser2.stop()

asyncio.run(main())

Selective Cookie Persistence with Patterns

For security or efficiency, you may want to persist only specific cookies. The save() and load() methods accept a pattern parameter that accepts regular expressions to filter cookies by name or domain.

# Save only Cloudflare and .com domain cookies

await browser.cookies.save(
    file=".filtered.dat", 
    pattern="(cf|\\.com)"
)

# Load only those specific cookies later

await browser2.cookies.load(
    file=".filtered.dat", 
    pattern="(cf|\\.com)"
)

Advanced Cookie Operations

Retrieving All Cookies

The get_all() method fetches all cookies from the browser. By default, it returns CDP cookie objects, but setting requests_cookie_format=True converts them into http.cookiejar.Cookie instances compatible with Python's requests library.

# Get cookies in requests format

cookie_jar = await browser.cookies.get_all(requests_cookie_format=True)

# Use with requests library

import requests
session = requests.Session()
session.cookies.update(cookie_jar)
response = session.get("https://example.com/api")
print(response.status_code)

Clearing Cookies

To wipe all cookies across every open tab and window, use the clear() method. This invokes Storage.clear_cookies via CDP and affects the entire browser context, not just the current page.

# Clear all cookies before starting a fresh session

await browser.cookies.clear()
print("All cookies cleared")

Summary

• Zendriver's CookieJar provides a Pythonic interface to CDP storage commands for managing browser cookies.
• Session persistence is achieved through save() and load() methods, with optional regex pattern filtering for selective storage.
• Cross-library compatibility is supported via get_all(requests_cookie_format=True), enabling integration with Python's requests library.
• Complete cleanup is available through the clear() method, which wipes cookies across all browser tabs.

Frequently Asked Questions

Where does Zendriver store cookies temporarily?

Zendriver does not persist cookies to disk automatically; they remain in the browser's memory until explicitly saved using browser.cookies.save(). The default filename is .session.dat if no path is specified, but you can define any custom location.

Can I filter cookies by domain when saving?

Yes, both save() and load() methods accept a pattern parameter that takes a regular expression string. You can use this to filter cookies by domain, name, or other attributes. For example, use pattern="\\.example\\.com$" to save only cookies from that specific domain.

How do I transfer cookies from Zendriver to Python requests?

Use the get_all() method with requests_cookie_format=True to retrieve cookies as http.cookiejar.Cookie objects. Then update a requests.Session object's cookie jar with these cookies. This allows you to use the same session state in both the browser and HTTP requests.

Does clearing cookies affect all browser tabs?

Yes, the clear() method invokes the CDP Storage.clear_cookies command, which wipes cookies for the entire browser context. This affects all open tabs and windows, not just the currently active page, ensuring a complete session reset.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}