自动化测试 / 系统课时
读取与设置 Cookie
读取与设置 Cookie
测试功能开关、会话提示或特定地域配置时,直接通过浏览器上下文管理 Cookie,比先打开页面再操作 DOM 更稳定。本篇使用 BrowserContext API 完成写入、读取、筛选清理,并说明域名和安全属性的关键边界。
学习目标
- 使用
addCookies()、cookies()和clearCookies()管理测试 Cookie - 正确选择
url与domain、path两种作用域写法 - 避免 Cookie 写入时机、域名和安全属性导致的测试误判
Cookie 属于浏览器上下文
Playwright 把 Cookie 管理放在 BrowserContext 上。同一上下文中的页面共享这些 Cookie,因此测试通常应在第一次访问目标页面前完成写入,让首个请求就携带正确状态。
读取时,context.cookies() 可以获取上下文中的全部 Cookie;传入一个或多个 URL 后,只返回会影响这些 URL 的 Cookie。相比页面里的 document.cookie,上下文 API 也能检查 HttpOnly Cookie,因此更适合做测试准备和断言。
写入、读取并清理 Cookie
下面的测试向 https://example.com 写入两个 Cookie,验证它们可以被上下文读取,再只清理其中一个。示例不依赖页面 DOM,因此可以直接聚焦 Cookie 行为。
import { test, expect } from '@playwright/test';
test('管理测试 Cookie', async ({ context, page }) => {
const origin = 'https://example.com';
// 在首次导航前注入 Cookie,让页面的第一个请求就携带测试状态。
await context.addCookies([
{
name: 'feature_flag',
value: 'checkout-v2',
url: origin,
secure: true,
sameSite: 'Lax',
},
{
name: 'session_hint',
value: 'qa-user',
domain: 'example.com',
path: '/',
httpOnly: true,
secure: true,
sameSite: 'Lax',
},
]);
// 只读取会影响目标站点的 Cookie,避免无关域名干扰断言。
const cookies = await context.cookies([origin]);
expect(cookies.find(c => c.name === 'feature_flag')?.value).toBe('checkout-v2');
expect(cookies.find(c => c.name === 'session_hint')?.httpOnly).toBe(true);
await page.goto(origin);
// 精确清理一个 Cookie,保留同一上下文中仍需使用的会话信息。
await context.clearCookies({
name: 'feature_flag',
domain: 'example.com',
});
const remaining = await context.cookies([origin]);
expect(remaining.some(c => c.name === 'feature_flag')).toBe(false);
expect(remaining.some(c => c.name === 'session_hint')).toBe(true);
});预期结果
测试通过:写入后可以读取 feature_flag=checkout-v2,并确认 session_hint 为 HttpOnly。
清理后 feature_flag 不再存在,session_hint 仍保留。如果希望清空当前上下文中的全部 Cookie,直接调用 await context.clearCookies() 即可。只删除特定 Cookie 时优先使用名称、域名或路径过滤,避免把同一测试还需要的其他会话状态一起清掉。
选择正确的作用域写法
addCookies() 中,每个 Cookie 需要提供 url,或者同时提供 domain 与 path。两种方式不要混着猜:目标只是让 Cookie 对一个明确站点生效时,使用 url 最省心;需要精确控制域和路径时,再使用 domain 与 path。
| 需求 | 推荐写法 | 关键点 |
|---|---|---|
| 仅对明确站点写入 | url: 'https://example.com' |
Playwright 根据 URL 推导作用域 |
| 控制路径范围 | domain + path |
两者必须同时提供 |
| 覆盖子域名 | 以点开头的 domain |
例如 .example.com |
域名不匹配是最常见的失败原因之一。例如页面访问 app.example.com,Cookie 却只写给另一个无关域名,即使 context.cookies() 能看到该 Cookie,请求也不会携带它。
安全属性与验证边界
httpOnly: true 表示页面脚本不能通过 document.cookie 读取该 Cookie,但测试仍可通过上下文 API 检查。secure: true 的 Cookie 应用于 HTTPS 场景;sameSite 则会影响跨站请求时浏览器是否携带 Cookie。
Cookie 存在也不等于登录一定有效。很多系统还会在服务端校验会话是否过期、是否撤销或是否与账号状态匹配。因此认证失败时,既要检查 Cookie 的作用域和属性,也要确认服务端会话仍然有效。