
playwright-cli 浏览器存储状态管理实战指南Cookies、localStorage、sessionStorage 与认证状态复用【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity导读本文围绕 Sanity 仓库中 .agents/skills/playwright-cli 技能所封装的playwright-cli命令行工具系统讲解其浏览器存储状态Storage State管理能力——涵盖 cookies、localStorage、sessionStorage、IndexedDB 的读写删清以及保存 → 恢复完整浏览器状态的认证复用工作流。读完本文你将掌握如何用state-save/state-load在多次自动化会话间复用登录态、用cookie-*/localstorage-*/sessionstorage-*系列命令细粒度操纵存储数据并理解存储状态 JSON 文件格式及其背后的安全边界。文章末尾还结合本仓库 e2e 测试体系如 e2e/playwright.config.ts 中的storageState注入实践展示该能力的真实工程用法。Storage State一键保存与恢复完整浏览器状态playwright-cli的存储状态Storage State能力可以把浏览器当前的全部存储数据——包括 cookies、localStorage、sessionStorage——序列化到磁盘文件之后在任意新会话中原样还原是跨会话复用登录态、预置测试数据的核心手段。保存存储状态使用state-save命令将当前浏览器上下文中的存储状态落盘# 保存到自动生成的文件名storage-state-{timestamp}.json playwright-cli state-save # 保存到指定文件名 playwright-cli state-save my-auth-state.json不传文件名时工具会自动生成带时间戳的 JSON 文件形如storage-state-2026-09-16T09-00-00-000Z.json适合临时快照显式命名则适合作为工作流产物便于后续state-load精确引用。恢复存储状态# 从文件加载存储状态 playwright-cli state-load my-auth-state.json # 重新打开页面以应用 cookiescookie 需要一次页面加载才会真正生效 playwright-cli open https://example.com注意state-load把状态写入当前浏览器上下文后需要重新导航页面才能看到 cookies 生效例如已登录站点会直接呈现登录后的界面。存储状态文件格式state-save产出的 JSON 文件结构与 Playwright 官方的storageState完全一致包含cookies与origins两个顶层字段{ cookies: [ { name: session_id, value: abc123, domain: example.com, path: /, expires: 1735689600, httpOnly: true, secure: true, sameSite: Lax } ], origins: [ { origin: https://example.com, localStorage: [ {name: theme, value: dark}, {name: user_id, value: 12345} ] } ] }字段语义说明cookies[]Cookie 列表name/value为键值对domain与path决定其作用域expires为 Unix 时间戳秒httpOnly/secure/sameSite对应浏览器安全属性origins[]按源origin即协议域名端口分组的 Web Storage 数据目前主要承载该源下的localStorage键值列表。由于该格式与 Playwright 官方配置互通你甚至可以手动编写这样一个 JSON 文件再通过state-load注入任意浏览上下文——这也正是 e2e/playwright.config.ts 中直接以storageState配置项向测试注入认证 localStorage 的原理详见文末仓库实战一节。Cookies 管理Cookies 是 Web 会话认证的载体playwright-cli提供了从列出、查询到设置、删除的完整命令面。列出与过滤# 列出当前上下文中的所有 cookies playwright-cli cookie-list # 按域名过滤 playwright-cli cookie-list --domainexample.com # 按路径过滤 playwright-cli cookie-list --path/api--domain与--path可组合使用例如只查看example.com下/api路径的会话类 Cookie。查询单个 Cookieplaywright-cli cookie-get session_id按名称精确读取某个 Cookie 的完整属性value、domain、expires、httpOnly、secure、sameSite 等。设置 Cookie# 基础用法名称 值 playwright-cli cookie-set session abc123 # 带选项的完整用法 playwright-cli cookie-set session abc123 --domainexample.com --path/ --httpOnly --secure --sameSiteLax # 带过期时间Unix 时间戳秒 playwright-cli cookie-set remember_me token123 --expires1735689600cookie-set支持的选项与 JSON 文件格式中的字段一一对应--domain指定生效域名--path指定路径作用域--httpOnly/--secure为布尔开关出现即开启--sameSite取值通常为Lax、Strict或None--expires使用 Unix 时间戳控制持久化时长。删除与清空# 删除指定 Cookie playwright-cli cookie-delete session_id # 清空当前上下文的所有 cookies playwright-cli cookie-clear进阶批量设置或自定义复杂 Cookie当需要一次性添加多个 Cookie或需要构造cookie-set命令行参数难以表达的属性组合时使用run-code直接调用 Playwright 上下文 APIplaywright-cli run-code的完整能力参见 .agents/skills/playwright-cli/references/running-code.mdplaywright-cli run-code async page { await page.context().addCookies([ { name: session_id, value: sess_abc123, domain: example.com, path: /, httpOnly: true }, { name: preferences, value: JSON.stringify({ theme: dark }), domain: example.com, path: / } ]); }page.context()返回当前浏览器上下文BrowserContextaddCookies()一次可注入任意数量的 Cookie适合模拟完整登录态或测试多 Cookie 场景。Local Storage 管理localStorage 属于持久化的源级存储常用于存放主题偏好、用户 ID、token 缓存等跨页面、跨会话数据。# 列出当前页面源下的所有 localStorage 条目 playwright-cli localstorage-list # 读取单个键的值 playwright-cli localstorage-get token # 设置普通字符串值 playwright-cli localstorage-set theme dark # 设置 JSON 字符串值自动序列化 playwright-cli localstorage-set user_settings {theme:dark,language:en} # 删除单个键 playwright-cli localstorage-delete token # 清空当前源的全部 localStorage playwright-cli localstorage-clear注意localstorage-set的第二个参数是字符串写入对象时需自行传入 JSON 序列化后的字符串如上面的user_settings示例读取时再反序列化使用。进阶批量写入多个条目一次设置多个值时同样通过run-code在页面上下文中执行localStorage.setItemplaywright-cli run-code async page { await page.evaluate(() { localStorage.setItem(token, jwt_abc123); localStorage.setItem(user_id, 12345); localStorage.setItem(expires_at, Date.now() 3600000); }); }page.evaluate在页面 JS 环境中执行因此可直接访问浏览器的localStorage全局对象适合构造已登录 已配置的完整初始状态。Session Storage 管理sessionStorage 的生命周期限定在单个标签页会话内标签页关闭即清除适合存放多步表单草稿、分步向导的当前进度等一次性数据。# 列出所有 sessionStorage 条目 playwright-cli sessionstorage-list # 读取单个值 playwright-cli sessionstorage-get form_data # 设置值 playwright-cli sessionstorage-set step 3 # 删除单个键 playwright-cli sessionstorage-delete step # 清空 sessionStorage playwright-cli sessionstorage-clear与 localStorage 命令一一对应用法完全对称区别仅在于数据的作用域与存活周期。值得一提的是state-save保存的存储状态文件不包含 sessionStorage它属于页面会话而非上下文状态因此跨会话恢复依赖的是 cookies 与 localStorage。IndexedDB数据库级操作IndexedDB 是浏览器内置的 NoSQL 数据库存储容量远大于 Web Storage常被大型 Web 应用离线优先、缓存型应用使用。playwright-cli没有为它提供专门的子命令统一通过run-codepage.evaluate在页面环境中操作。列出所有数据库playwright-cli run-code async page { return await page.evaluate(async () { const databases await indexedDB.databases(); return databases; }); }删除指定数据库playwright-cli run-code async page { await page.evaluate(() { indexedDB.deleteDatabase(myDatabase); }); }indexedDB.databases()返回当前源下的数据库元信息数组indexedDB.deleteDatabase(myDatabase)按名称删除数据库存在未关闭连接时会触发blocked事件脚本中按需处理。这两段代码可作为操作 IndexedDB 的基础模板更复杂的对象仓库object store读写同样可以在page.evaluate中完成。常见模式认证状态复用与保存/恢复往返模式一登录一次处处复用Authentication State Reuse这是存储状态管理最典型、价值最高的场景——先手动完成一次登录把认证态固化到文件之后的自动化任务直接恢复状态跳过登录步骤# Step 1打开登录页并完成登录 playwright-cli open https://app.example.com/login playwright-cli snapshot playwright-cli fill e1 userexample.com playwright-cli fill e2 password123 playwright-cli click e3 # 保存认证状态 playwright-cli state-save auth.json # Step 2之后任意时刻恢复状态直接访问受保护页面 playwright-cli state-load auth.json playwright-cli open https://app.example.com/dashboard # 已经是登录状态无需再次登录snapshot用于获取页面元素的可访问性引用如e1、e2、e3随后fill/click依据这些引用完成交互——这是 SKILL.md 中规定的标准交互流程。模式二保存与恢复往返Save and Restore Roundtrip不依赖完整登录流程也可以直接构造状态再固化# 设置认证状态 playwright-cli open https://example.com playwright-cli eval () { document.cookie sessionabc123; localStorage.setItem(user, john); } # 保存状态到文件 playwright-cli state-save my-session.json # …… 稍后在新的会话中 …… # 恢复状态 playwright-cli state-load my-session.json playwright-cli open https://example.com # Cookies 和 localStorage 都已恢复eval允许直接在页面上下文中执行 JS 表达式如设置document.cookie与localStorage与state-save配合可快速生成可复用的状态快照。结合 session-management.md 中的-s命名会话机制你还可以为不同账号分别保存auth-admin.json、auth-editor.json在互相隔离的浏览器会话中并行执行不同角色场景。安全注意事项存储状态文件本质上是凭证的序列化副本泄露即等于交出登录态务必遵守以下安全约定绝不提交包含认证令牌的存储状态文件到版本控制将*.auth-state.json加入.gitignore本仓库根目录的 .gitignore 相关约定 之外任何涉及认证状态的文件都应显式忽略自动化任务完成后及时删除状态文件避免长期滞留磁盘敏感数据如真实 token优先通过环境变量注入而非写死在状态文件或命令中默认情况下会话以内存模式运行不落盘 profile详见 session-management.md 中的持久化 profile 说明这对敏感操作更安全仅在确实需要跨会话持久化时才显式使用state-save或--persistent。仓库实战storageState 在 Sanity E2E 中的工程应用本仓库的端到端测试体系恰好印证了存储状态思想的工程化落地——虽然 Sanity e2e 直接使用 Playwright 测试框架而非playwright-cli命令但两者共享完全相同的 storageState 数据格式。在 e2e/playwright.config.ts 中Playwright 的use.storageState配置直接内联了一段存储状态 JSON向每个测试上下文注入 Sanity Studio 的认证 tokenstorageState: { cookies: [], origins: [ { origin: BASE_URL, localStorage: [ { name: __studio_auth_token_${PROJECT_ID}, value: JSON.stringify({ token: TOKEN, time: new Date().toISOString(), }), }, ], }, ], },其中TOKEN来自SANITY_E2E_SESSION_TOKEN环境变量见 e2e/helpers/envVars.ts通过localStorage键__studio_auth_token_{projectId}预置登录态——这正是 Sanity Studio 前端读取会话 token 的存储位置。可以看到用 JSON 描述 cookies localStorage再整体注入浏览器上下文的模式与playwright-cli state-load背后是完全一致的机制只不过 Playwright 测试配置里是声明式的而 CLI 中是从文件加载。与之配套认证类测试单独使用 e2e/playwright.auth.config.ts针对 dev/auth-test-studio 的 cookie/token 双工作区并在 e2e/tests/auth/helpers.ts 中通过路由 mock 模拟登录 API 响应。这展示了存储状态管理的两种策略真实登录 保存/恢复适合复用真实认证态playwright-cli场景直接注入构造的状态适合测试环境无需真实凭证即可预置任意登录态Sanity e2e 场景。理解了 storageState 文件格式与注入机制后你可以自由地在两条路线之间切换——既可以用playwright-cli state-save从手工登录会话导出状态文件也可以手工编写 JSON 后用state-load注入甚至像本仓库一样在测试配置中声明式内联。小结playwright-cli的存储管理命令构成了一个查看 → 修改 → 固化 → 复用的完整闭环cookie-*、localstorage-*、sessionstorage-*负责细粒度读写state-save/state-load负责整体快照的保存与恢复run-code补足 IndexedDB 与批量操作的进阶场景而 session-management.md 中的命名会话与持久化 profile 则定义了这些存储数据的隔离与存活边界。配合文末的安全清单这套能力足以支撑认证复用、多角色并行测试、状态预置等绝大多数浏览器自动化需求。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考