/cookie-debugging

name: cookie-debugging
description: Uses Chrome DevTools MCP for inspecting, debugging, and testing cookies, session state, authentication issues, and cookie consent compliance. Use when diagnosing 401/403 errors, authentication redirects, session expiration, Cookie/Set-Cookie header issues, cookie banner consent conformance, or third-party cookie/SameSite/Partitioned cookie warnings.

Core Concepts

**Page Targeting**: Page-scoped tools (`list_network_requests`, `get_network_request`, `list_console_messages`, `evaluate_script`, `navigate_page`, `take_snapshot`, `click`, `lighthouse_audit`, `close_page`, etc.) require a `pageId` parameter. Retrieve available page IDs using `list_pages` or from `new_page`.

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 on the user's existing page; get its `pageId` from `list_pages`. | | **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 `type: "reload"`, 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 `a