自动化测试 / 系统课时
保存认证状态
保存认证状态
频繁登录会拖慢端到端测试,也会把登录页故障放大到所有用例。本节把登录后的浏览器上下文保存为可复用的 storageState 文件,并明确保存时机、可保存的数据与安全边界。
学习目标
- 使用
BrowserContext.storageState()保存 Cookie 与本地存储 - 判断何时应该写入状态文件,避免保存半登录状态
- 安全存放认证状态,并识别过期与
sessionStorage边界
storageState 保存了什么
Playwright 的认证状态属于 BrowserContext,不是某个 Page。调用 context.storageState() 时,会读取当前上下文中的 Cookie 和各来源的 localStorage;如果应用把令牌放在 IndexedDB,可通过 indexedDB: true 一并保存。sessionStorage 不属于这套持久化状态,需要单独处理。

状态文件通常保存到 playwright/.auth/。它可能包含可直接代表用户身份的 Cookie 或令牌,因此不能把它当普通测试夹具提交到仓库。
在状态稳定后写入文件
下面的可运行示例不依赖真实登录页,而是在 example.com 上创建一个演示 Cookie 和 localStorage 值,再保存并读取状态文件。真实项目中应把“写入演示状态”替换为实际登录流程,而不是手工伪造生产认证信息。
import { test, expect } from '@playwright/test';
import fs from 'node:fs/promises';
import path from 'node:path';
test('save browser authentication state', async ({ page }) => {
await page.goto('https://example.com/');
// 用演示值模拟登录后由站点写入的认证 Cookie。
await page.context().addCookies([{
name: 'session',
value: 'demo-token',
domain: 'example.com',
path: '/',
httpOnly: true,
secure: true,
sameSite: 'Lax',
}]);
// localStorage 按来源保存,因此先进入目标来源再写入。
await page.evaluate(() => {
localStorage.setItem('access_token', 'demo-token');
});
const authFile = path.resolve('playwright/.auth/user.json');
await fs.mkdir(path.dirname(authFile), { recursive: true });
// 真实项目应在确认登录完成后执行这一行。
await page.context().storageState({ path: authFile });
const state = JSON.parse(await fs.readFile(authFile, 'utf8'));
const origin = state.origins.find(
(item: { origin: string }) => item.origin === 'https://example.com',
);
expect(state.cookies.some((cookie: { name: string }) => cookie.name === 'session')).toBe(true);
expect(origin?.localStorage.some((item: { name: string }) => item.name === 'access_token')).toBe(true);
console.log(`saved ${state.cookies.length} cookie(s) and ${state.origins.length} origin(s)`);
});运行测试:
npx playwright test tests/save-auth-state.spec.ts预期输出:
saved 1 cookie(s) and 1 origin(s)
1 passed (<TIME>)<TIME> 会随机器和网络速度变化。若真实登录经历多次重定向,应先等待最终 URL 或一个仅登录后可见的元素,再调用 storageState();否则可能把尚未收到最终 Cookie 的中间状态保存下来。
处理 IndexedDB 与保存边界
如果认证令牌位于 IndexedDB,例如某些前端认证 SDK,可在保存时显式启用它:
await page.context().storageState({
path: 'playwright/.auth/user.json',
indexedDB: true,
});这是配置片段,依赖已经完成登录的 page 上下文。生效后,状态文件除 Cookie 和 localStorage 外还会包含可恢复的 IndexedDB 数据;验证方法是在新的浏览器上下文加载该文件后访问受保护页面。
不要把 sessionStorage 误认为会自动保存。它与单个页面会话绑定,Playwright 的 storageState 不会持久化它;若应用只靠 sessionStorage 维持登录,需要另行导出并在新上下文启动时注入。
保护并刷新状态文件
至少把认证目录加入 .gitignore:
playwright/.auth/认证状态常带有会话 Cookie、访问令牌或其他敏感值,即使仓库是私有的,也不应把它们长期提交。CI 中更适合在受控环境运行登录 setup,临时生成状态文件。
状态文件还会过期。出现“文件存在但仍被重定向到登录页”时,先检查 Cookie 或令牌有效期,再重新执行认证流程生成新状态,而不是继续复用旧文件。保存认证状态的关键不是“有一个 JSON 文件”,而是确保它来自已经完成且仍然有效的登录上下文。