chromedevtools/cookie-debugging

Core Concepts

HttpOnly vs Client-Side Storage

Cookies marked HttpOnly cannot be accessed or modified by client-side JavaScript (cookieStore or document.cookie). However, the browser automatically attaches active HttpOnly cookies to outgoing HTTP request headers (Cookie).

• To inspect current HttpOnly values: Look at the Cookie request header of any outgoing HTTP request via get_network_request.
• To inspect how cookies were created or configured: Look at the Set-Cookie response header of login/auth responses.
• To inspect non-HttpOnly cookies: Use evaluate_script with the modern cookieStore API (async () => await cookieStore.getAll()).

Session Strategy: Live Tab vs Isolated Context

Choose the right session environment to avoid state contamination (e.g., residual analytics or auth tokens):

Strategy	When to Use	Setup / Teardown
Live Tab (Active Page)	Diagnosing an active user session, live 401/403 error, or current state.	Operates directly on the currently selected page.
Clean-Slate (isolatedContext)	Testing cookie consent banners, first-time visits, or zero-cookie guarantees.	Call new_page with a unique isolatedContext (e.g. "consent-audit-1"). When finished, call close_page.

Client-Side Capabilities & Limitations

Action	Client JavaScript (cookieStore / document.cookie)	DevTools Network & Context Tools
Read Non-HttpOnly	✅ async () => await cookieStore.getAll()	✅ get_network_request (Request Cookie)
Read HttpOnly	❌ Blocked by browser security	✅ get_network_request (Request Cookie)
Inspect Attributes (Domain, Path, SameSite, Expires)	✅ async () => await cookieStore.getAll()	✅ get_network_request (Response Set-Cookie)
Modify / Delete Non-HttpOnly	✅ async () => await cookieStore.set(...)	N/A
Modify / Delete HttpOnly	❌ Silent failure in JavaScript	✅ Use new_page(isolatedContext: ...) for clean state

[!WARNING] Attempting to clear an HttpOnly cookie via JavaScript (cookieStore.delete or document.cookie = "...; max-age=0") will silently fail. To test in an unauthenticated or fresh state, always spawn a new isolated context using new_page with isolatedContext.

---

Workflow Patterns

1. Diagnosing Authentication Failures & Redirects (401 / 403)

When an authenticated page request fails, returns 401/403, or redirects to login:

1. List Recent Requests: Call list_network_requests with includePreservedRequests: true.
2. Find the Target Request: Locate the failing request (401/403) or redirect (302/307).
3. Inspect Outgoing Cookie Header: Call get_network_request with the reqid.
   • Verify if the Cookie header was attached and whether required tokens (e.g. SESSION_ID, auth_token) were sent.
4. Trigger Active Inspection (If no recent request exists):
   • If the cookie was set in a previous session and no network call is listed, trigger a request:
     • Use navigate_page with reload: true, OR
     • Call evaluate_script with () => fetch(window.location.href)
   • Then call get_network_request on the new request to inspect the active Cookie header.
5. Trace the Setting Request: If the cookie is missing or rejected:
   • Check earlier login/handshake responses for Set-Cookie directives:
     • Path mismatch: e.g., Path=/api when the request is to /.
     • Domain mismatch: e.g., Domain=api.example.com preventing cookies on sub.example.com.
     • Secure flag on HTTP: Secure cookies are never sent over unencrypted http://.
     • SameSite blocking: SameSite=Strict cookies are omitted on cross-site navigations.
     • Expiration: Check if Expires or Max-Age elapsed.

2. Cookie Banner & Consent Conformance Testing

To verify that no non-essential or tracking cookies are set before consent or when declining:

1. Start Clean: Open a fresh isolated context with a dedicated name:

   {"url": "<PAGE_URL>", "isolatedContext": "consent-test-1"}
   

2. Record Baseline Cookies: Before interacting with the banner, run evaluate_script with async () => await cookieStore.getAll().
3. Inspect Premature Network Requests & Issues:
   • Call list_network_requests to ensure no third-party tracking beacons fired before consent.
   • Call list_console_messages with types: ["issue"] to check for tracking warnings.
4. Interact with Consent Banner:
   • Capture snapshot with take_snapshot to locate the "Decline" or "Reject All" button uid.
   • Click the button with click.
5. Verify Cookie Difference:
   • Run evaluate_script with async () => await cookieStore.getAll() after clicking to assert that only strictly necessary or consent-state cookies exist.
6. Test Consent Revocation (Lifecycle Audit):
   • When auditing consent withdrawal or preference changes:
     • Locate and click the "Cookie Settings", "Manage Preferences", or footer privacy trigger (take_snapshot $\rightarrow$ click).
     • Deselect non-essential categories or click "Revoke All" / "Save Preferences".
     • Re-query cookieStore.getAll() to verify previously accepted non-essential cookies were cleared or expired.
     • Call list_network_requests on subsequent actions to ensure tracking beacons are no longer fired.
7. Teardown Context: Call close_page when the audit is complete to prevent leftover cookies from affecting subsequent tasks.

3. Auditing Cookie Security, SameSite & CHIPS (Partitioned Cookies)

1. Fast-Track: Native DevTools Issues (Recommended):
   • Call list_console_messages with:

     {
       "types": ["issue"],
       "includePreservedMessages": true
     }
     

   • Check for CookieIssue entries, such as:
     • SameSiteNoneInsecure: SameSite=None without Secure.
     • ThirdPartyCookiePhaseout: Third-party cookie blocked or restricted.
     • SchemefulSameSite: Cross-scheme cookie issues.
     • PartitionedCookies: Invalid CHIPS partitioning attributes.
2. Deep Audit: Lighthouse Third-Party Cookies:
   • Run lighthouse_audit with mode: "navigation" and outputDirPath: "/tmp/lh-report".
   • Extract the specific cookie audit without loading the full report into context:

     node -e "const r=require('/tmp/lh-report/report.json'); const a=r.audits['third-party-cookies']; console.log(JSON.stringify({score: a?.score, display