cookie-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Core Concepts

核心概念

HttpOnly vs Client-Side Storage

HttpOnly vs 客户端存储

Cookies marked

HttpOnly

cannot be accessed or modified by client-side JavaScript (

cookieStore

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()

标记为

HttpOnly

的Cookie无法通过客户端JavaScript（

cookieStore

或

document.cookie

）访问或修改。不过浏览器会自动将活跃的HttpOnly Cookie附加到 outgoing HTTP请求头（
Cookie
）中。

检查当前
```
HttpOnly
```
值：通过
```
get_network_request
```
查看任意 outgoing HTTP请求的
```
Cookie
```
请求头。
检查Cookie的创建或配置方式：查看登录/认证响应的
```
Set-Cookie
```
响应头。

检查非

HttpOnly

Cookie：结合现代

cookieStore

API使用

evaluate_script

（

async () => await cookieStore.getAll()

）。

Session Strategy: Live Tab vs Isolated Context

会话策略：实时标签页 vs 隔离上下文

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` .

选择合适的会话环境以避免状态污染（如残留的分析或认证令牌）：

策略	使用场景	搭建/清理步骤
实时标签页（活动页面）	诊断活跃用户会话、实时401/403错误或当前状态。	直接在当前选中的页面上操作。
全新环境（ `isolatedContext` ）	测试Cookie同意横幅、首次访问或零Cookie保障场景。	调用 `new_page` 并传入唯一的 `isolatedContext` （例如 `"consent-audit-1"` ）。完成后调用 `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
.

操作	客户端JavaScript（ `cookieStore` / `document.cookie` ）	DevTools网络与上下文工具
读取非HttpOnly Cookie	✅ `async () => await cookieStore.getAll()`	✅ `get_network_request` （请求头 `Cookie` ）
读取HttpOnly Cookie	❌ 被浏览器安全机制阻止	✅ `get_network_request` （请求头 `Cookie` ）
检查属性（ `Domain` 、 `Path` 、 `SameSite` 、 `Expires` ）	✅ `async () => await cookieStore.getAll()`	✅ `get_network_request` （响应头 `Set-Cookie` ）
修改/删除非HttpOnly Cookie	✅ `async () => await cookieStore.set(...)`	不适用
修改/删除HttpOnly Cookie	❌ JavaScript中会静默失败	✅ 使用 `new_page(isolatedContext: ...)` 获取干净状态

[!WARNING] 尝试通过JavaScript清除
HttpOnly
Cookie（
cookieStore.delete
或
document.cookie = "...; max-age=0"
）会静默失败。要测试未认证或全新状态，请始终使用带
isolatedContext
参数的
new_page
生成新的隔离上下文。

Workflow Patterns

工作流模式

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

1. 诊断认证失败与重定向（401 / 403）

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

List Recent Requests: Call

list_network_requests

with

includePreservedRequests: true

Find the Target Request: Locate the failing request (401/403) or redirect (302/307).
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.
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.
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.

当已认证页面请求失败、返回401/403或重定向到登录页时：

列出近期请求：调用

list_network_requests

并设置

includePreservedRequests: true

。

找到目标请求：定位失败请求（401/403）或重定向请求（302/307）。
检查 outgoing
Cookie
头：传入
```
reqid
```
调用
```
get_network_request
```
。
- 验证
```
Cookie
```
  头是否已附加，以及是否发送了所需令牌（如
```
SESSION_ID
```
  、
```
auth_token
```
  ）。
触发主动检查（如果没有近期请求）：
- 如果Cookie是在之前的会话中设置的且未列出网络请求，触发一个请求：
  - 使用带
```
reload: true
```
    的
```
navigate_page
```
    ，或者
  - 调用
```
evaluate_script
```
    并传入
```
() => fetch(window.location.href)
```
- 然后在新请求上调用
```
get_network_request
```
  以检查活跃的
```
Cookie
```
  头。
追踪设置请求：如果Cookie缺失或被拒绝：
- 检查早期登录/握手响应中的
```
Set-Cookie
```
  指令：
  - 路径不匹配：例如，
```
Path=/api
```
    但请求指向
```
/
```
    。
  - 域名不匹配：例如，
```
Domain=api.example.com
```
    阻止Cookie在
```
sub.example.com
```
    上生效。
  - HTTP环境下的Secure标记：
```
Secure
```
    Cookie绝不会通过未加密的
```
http://
```
    发送。
  - SameSite拦截：
```
SameSite=Strict
```
    Cookie在跨站导航时会被省略。
  - 过期时间：检查
```
Expires
```
    或
```
Max-Age
```
    是否已过期。

2. Cookie Banner & Consent Conformance Testing

2. Cookie横幅与合规性测试

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

Start Clean: Open a fresh isolated context with a dedicated name:
json
```
{"url": "<PAGE_URL>", "isolatedContext": "consent-test-1"}
```
Record Baseline Cookies: Before interacting with the banner, run
```
evaluate_script
```
with
```
async () => await cookieStore.getAll()
```
.
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.
Interact with Consent Banner:
- Capture snapshot with
```
take_snapshot
```
  to locate the "Decline" or "Reject All" button
```
uid
```
  .
- Click the button with
```
click
```
  .
Verify Cookie Difference:
- Run
```
evaluate_script
```
  with
```
async () => await cookieStore.getAll()
```
  after clicking to assert that only strictly necessary or consent-state cookies exist.
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.
Teardown Context: Call
```
close_page
```
when the audit is complete to prevent leftover cookies from affecting subsequent tasks.

验证在获得同意前或拒绝同意时，是否未设置非必要或跟踪类Cookie：

启动干净环境：使用专属名称打开全新的隔离上下文：
json
```
{"url": "<PAGE_URL>", "isolatedContext": "consent-test-1"}
```
记录基准Cookie：在与横幅交互前，运行
```
evaluate_script
```
并传入
```
async () => await cookieStore.getAll()
```
。
检查提前触发的网络请求与问题：
- 调用
```
list_network_requests
```
  确保在获得同意前没有第三方跟踪信标触发。
- 调用
```
list_console_messages
```
  并设置
```
types: ["issue"]
```
  检查跟踪警告。
与同意横幅交互：
- 使用
```
take_snapshot
```
  捕获快照，定位“拒绝”或“全部拒绝”按钮的
```
uid
```
  。
- 使用
```
click
```
  点击该按钮。
验证Cookie差异：
- 点击后运行
```
evaluate_script
```
  并传入
```
async () => await cookieStore.getAll()
```
  ，确认仅存在严格必要或同意状态类Cookie。
测试同意撤销（生命周期审计）：
- 审计同意撤回或偏好更改时：
  - 定位并点击“Cookie设置”、“管理偏好”或页脚隐私触发按钮（
```
take_snapshot
```
    →
```
click
```
    ）。
  - 取消选择非必要类别或点击“全部撤销”/“保存偏好”。
  - 重新查询
```
cookieStore.getAll()
```
    以验证之前接受的非必要Cookie已被清除或过期。
  - 在后续操作中调用
```
list_network_requests
```
    确保跟踪信标不再触发。
清理上下文：审计完成后调用
```
close_page
```
，避免残留Cookie影响后续任务。

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

3. Cookie安全、SameSite与CHIPS（分区Cookie）审计

Fast-Track: Native DevTools Issues (Recommended):
- Call
```
list_console_messages
```
  with:
  json
```
{
  "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.

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:

bash

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

快速通道：原生DevTools问题（推荐）：
- 调用
```
list_console_messages
```
  并传入：
  json
```
{
  "types": ["issue"],
  "includePreservedMessages": true
}
```
- 检查
```
CookieIssue
```
  条目，例如：
  - ```
  SameSiteNoneInsecure
```
  ：
```
  SameSite=None
```
  未搭配
```
  Secure
```
  。
- ```
ThirdPartyCookiePhaseout
```
    ：第三方Cookie被阻止或限制。
  - ```
  SchemefulSameSite
```
  ：跨协议Cookie问题。
- ```
PartitionedCookies
```
    ：无效的CHIPS分区属性。

深度审计：Lighthouse第三方Cookie：

运行

lighthouse_audit

并设置

mode: "navigation"

和

outputDirPath: "/tmp/lh-report"

。

提取特定Cookie审计内容，无需将完整报告加载到上下文中：

bash

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

4. Client-Side Cookie Inspection & Manipulation

4. 客户端Cookie检查与操作

For client-accessible, non-

HttpOnly

cookies (e.g., UI preferences, non-sensitive feature flags):

Read Cookies & Attributes:
- Use the modern asynchronous Cookie Store API:
  js
```
async () => await cookieStore.getAll();
```
- Fallback for insecure HTTP origins:
```
() => document.cookie
```
  .

Set / Modify Cookie:

Set client cookie via

cookieStore

async () =>
  await cookieStore.set({
    name: 'theme',
    value: 'dark',
    expires: Date.now() + 86400000,
    sameSite: 'lax',
  });

Delete Cookie:

Clear client cookie:

async () => await cookieStore.delete('theme');

针对客户端可访问的非

HttpOnly

Cookie（如UI偏好、非敏感功能标志）：

读取Cookie与属性：
- 使用现代异步Cookie Store API：
  js
```
async () => await cookieStore.getAll();
```
- 非安全HTTP源的回退方案：
```
() => document.cookie
```
  。

设置/修改Cookie：

通过

cookieStore

设置客户端Cookie：

async () =>
  await cookieStore.set({
    name: 'theme',
    value: 'dark',
    expires: Date.now() + 86400000,
    sameSite: 'lax',
  });

删除Cookie：

清除客户端Cookie：

async () => await cookieStore.delete('theme');

Troubleshooting

故障排除

cookieStore
is undefined:
```
cookieStore
```
requires a Secure Context (
```
https://
```
,
```
localhost
```
, or
```
127.0.0.1
```
). On non-secure HTTP origins, use
```
() => document.cookie
```
or test over HTTPS.
evaluate_script
returns empty / unresolved Promise:
```
cookieStore
```
methods are asynchronous. Always wrap calls with
```
async () => await cookieStore.getAll()
```
.
Cookie not visible in JavaScript: The cookie is marked
```
HttpOnly
```
. Trigger a network request and call
```
get_network_request
```
to view it in the
```
Cookie
```
request header.
JavaScript deletion did not remove cookie: The cookie is
```
HttpOnly
```
or requires matching
```
Path
```
and
```
Domain
```
parameters. Use a fresh
```
isolatedContext
```
with
```
new_page
```
for a clean slate.
Cookie set in response but not sent in requests:
- Verify if page is
```
http://
```
  while cookie specifies
```
Secure
```
  .
- Check if
```
Domain
```
  restricts subdomains.
- Check
```
list_console_messages(types: ["issue"])
```
  for browser rejection reasons.
Residual cookies contaminating audits: Always use
```
new_page
```
with a unique
```
isolatedContext
```
when running compliance tests, and call
```
close_page
```
when done.

cookieStore
未定义：
```
cookieStore
```
需要安全上下文（
```
https://
```
、
```
localhost
```
或
```
127.0.0.1
```
）。在非安全HTTP源上，使用
```
() => document.cookie
```
或通过HTTPS测试。
evaluate_script
返回空/未解析的Promise：
```
cookieStore
```
方法是异步的。请始终用
```
async () => await cookieStore.getAll()
```
包裹调用。
Cookie在JavaScript中不可见：该Cookie被标记为
```
HttpOnly
```
。触发一个网络请求并调用
```
get_network_request
```
，在
```
Cookie
```
请求头中查看它。
JavaScript删除未移除Cookie：该Cookie是
```
HttpOnly
```
，或需要匹配
```
Path
```
和
```
Domain
```
参数。使用带
```
isolatedContext
```
的
```
new_page
```
获取干净环境。
Cookie在响应中设置但未在请求中发送：
- 验证页面是否为
```
http://
```
  而Cookie指定了
```
Secure
```
  。
- 检查
```
Domain
```
  是否限制了子域名。
- 调用
```
list_console_messages(types: ["issue"])
```
  查看浏览器拒绝原因。
残留Cookie污染审计：运行合规性测试时，请始终使用带唯一
```
isolatedContext
```
的
```
new_page
```
，并在完成后调用
```
close_page
```
。