自动化测试 / 系统课时

保存认证状态

保存认证状态

频繁登录会拖慢端到端测试,也会把登录页故障放大到所有用例。本节把登录后的浏览器上下文保存为可复用的 storageState 文件,并明确保存时机、可保存的数据与安全边界。

学习目标

  • 使用 BrowserContext.storageState() 保存 Cookie 与本地存储
  • 判断何时应该写入状态文件,避免保存半登录状态
  • 安全存放认证状态,并识别过期与 sessionStorage 边界

storageState 保存了什么

Playwright 的认证状态属于 BrowserContext,不是某个 Page。调用 context.storageState() 时,会读取当前上下文中的 Cookie 和各来源的 localStorage;如果应用把令牌放在 IndexedDB,可通过 indexedDB: true 一并保存。sessionStorage 不属于这套持久化状态,需要单独处理。

认证状态保存链路

状态文件通常保存到 playwright/.auth/。它可能包含可直接代表用户身份的 Cookie 或令牌,因此不能把它当普通测试夹具提交到仓库。

在状态稳定后写入文件

下面的可运行示例不依赖真实登录页,而是在 example.com 上创建一个演示 Cookie 和 localStorage 值,再保存并读取状态文件。真实项目中应把“写入演示状态”替换为实际登录流程,而不是手工伪造生产认证信息。

ts
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)`);
});

运行测试:

bash
npx playwright test tests/save-auth-state.spec.ts

预期输出:

text
saved 1 cookie(s) and 1 origin(s)
1 passed (<TIME>)

<TIME> 会随机器和网络速度变化。若真实登录经历多次重定向,应先等待最终 URL 或一个仅登录后可见的元素,再调用 storageState();否则可能把尚未收到最终 Cookie 的中间状态保存下来。

处理 IndexedDB 与保存边界

如果认证令牌位于 IndexedDB,例如某些前端认证 SDK,可在保存时显式启用它:

ts
await page.context().storageState({
  path: 'playwright/.auth/user.json',
  indexedDB: true,
});

这是配置片段,依赖已经完成登录的 page 上下文。生效后,状态文件除 Cookie 和 localStorage 外还会包含可恢复的 IndexedDB 数据;验证方法是在新的浏览器上下文加载该文件后访问受保护页面。

不要把 sessionStorage 误认为会自动保存。它与单个页面会话绑定,Playwright 的 storageState 不会持久化它;若应用只靠 sessionStorage 维持登录,需要另行导出并在新上下文启动时注入。

保护并刷新状态文件

至少把认证目录加入 .gitignore:

text
playwright/.auth/

认证状态常带有会话 Cookie、访问令牌或其他敏感值,即使仓库是私有的,也不应把它们长期提交。CI 中更适合在受控环境运行登录 setup,临时生成状态文件。

状态文件还会过期。出现“文件存在但仍被重定向到登录页”时,先检查 Cookie 或令牌有效期,再重新执行认证流程生成新状态,而不是继续复用旧文件。保存认证状态的关键不是“有一个 JSON 文件”,而是确保它来自已经完成且仍然有效的登录上下文。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

保存认证状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通