use-profiles

使用 Playwright 身份验证配置文件

用途

在开始浏览器自动化工作前，加载已保存的 Playwright storageState 身份验证配置文件。这样每次浏览器会话开始时都无需手动登录。

适用情形

仅当以下所有条件都满足时，此技能才适用：

1. 当前项目有 .playwright/profiles.json 文件
2. 即将开始浏览器自动化工作（通过 Bash 使用 Playwright CLI）
3. 目标页面需要身份验证

发现配置文件

检查项目根目录中是否有 .playwright/profiles.json。读取该文件以发现可用的配置文件。文件包含如下条目：

{
  "profiles": {
    "admin": {
      "loginUrl": "https://example.com/login",
      "description": "Full permissions",
      "createdAt": "2026-03-31T12:00:00Z"
    }
  }
}

每个配置文件在 .playwright/profiles/<role-name>.json 中都有对应的 storageState 文件。

选择配置文件

根据对话上下文确定要使用的配置文件：

• 如果用户提到了特定角色（例如“测试管理后台”“查看演讲者视图”），则将其与配置中的配置文件名称匹配。
• 如果用户未指定角色，且只有一个配置文件，则自动使用该配置文件。
• 如果用户未指定角色，且存在多个配置文件，则询问要使用哪一个。向用户展示可用配置文件及其描述。

加载配置文件

在导航到任何需要身份验证的页面之前，通过 Bash 工具使用 playwright-cli 加载配置文件。下面的 {session} 占位符指当前命名会话（例如 runner-desktop、qa-ux，由调用该技能或命令的内容设置）。

1. 确认 .playwright/profiles/<role-name>.json 中存在 storageState 文件。如果不存在，请告知用户，并建议运行 /setup-profiles 来创建该文件。

2. 将配置文件中的 Cookie 和 localStorage 加载到浏览器会话：

   playwright-cli -s={session} state-load ".playwright/profiles/<role-name>.json"
   

   这会从 storageState JSON 恢复所有 Cookie 和各来源的 localStorage，格式与 Playwright 的 storageState() 使用的格式相同。

3. 如果配置文件 JSON 中包含 sessionStorage 字段（该字段不属于标准 storageState，是由 /setup-profiles 添加的），则在导航到目标来源后单独恢复：

   playwright-cli -s={session} goto "<origin>"
   

   然后针对每个 sessionStorage 条目：

   playwright-cli -s={session} sessionstorage-set "<name>" "<value>"
   

4. 导航到需要身份验证的目标页面。请求会携带 Cookie，localStorage 已填充，且 sessionStorage 已恢复，因此服务端、客户端和 SPA 身份验证库（Supabase、Firebase、Auth0）都能识别该会话。

测试数据文件和验收标准

加载配置文件后，检查 profiles.json 中是否包含 files 数组和/或 acceptance 对象。这些字段是可选的，许多配置文件可能不包含它们。

显示可用文件

如果配置文件包含 files，请向调用方提供摘要：

此配置文件有 N 个可用的测试数据文件：

1. valid-deck.pptx — 干净的演示文稿，通过所有检查
2. profanity-deck.pptx — 备注中含有亵渎用语，应触发标记
3. (cloud) oversized-deck.pptx — 200MB 的演示文稿，用于测试大小限制

配置文件验收标准：上传成功，处理完成

为云托管文件（包含 url 而非 path 的文件）标注 (cloud)，以便区分。

此信息仅供展示，本技能不会据此采取操作——由使用方（工作流生成器、运行器、Agent）决定是否使用以及如何使用。

文件路径验证

对于每个包含 path 字段的文件条目，验证该文件是否存在于相对于项目根目录的给定路径下。如果文件缺失，请警告：

配置文件“speaker”引用的测试文件“test-fixtures/valid-deck.pptx”不存在。该文件可能已被移动或删除。

文件缺失时不要报错或阻止操作，只需发出警告。对于包含 url 的文件不进行验证（这些文件可能需要身份验证，或位于私有网络上）。

验收标准摘要

如果配置文件包含 acceptance，请提供已配置标准的易读摘要。字段映射如下：

字段	摘要文本
uploadAccepted: true	上传已接受
processingCompletes: true	处理已完成
resultDownloadable: true	结果可下载
errorExpected: true	预期会出现错误
expectedStatus: "clear"	预期状态："clear"

如果个别文件有 acceptance 覆盖项，请注明哪些文件覆盖了配置文件默认值：

文件 "corrupted.pptx" 覆盖配置文件验收标准：上传被拒绝，预期会出现错误

会话过期检测

加载配置文件并导航到目标页面后，按以下顺序使用这些启发式方法检查会话是否仍然有效：

1. URL 重定向： 如果浏览器被重定向到与配置文件中的 loginUrl 匹配的 URL，则会话可能已过期。检查快照输出中的 Page URL 行。
2. 身份验证提供方重定向： 如果最终 URL 位于不同域名（例如，accounts.google.com、auth0.com），则应用已重定向到 OAuth 提供方，会话已过期。
3. 页面内容检查： 通过 Bash 运行 playwright-cli -s={session} snapshot，并查找与登录相关的元素：登录表单、“Log in” / “Sign in” 按钮，或“session expired”文本。如果目标页面预期显示已通过身份验证的内容，但实际显示的是登录界面，则会话已过期。

如果检测到会话过期：

• 告知用户该配置文件的会话似乎已过期
• 建议运行 /setup-profiles 刷新会话
• 不要尝试自动登录

这些启发式方法仅供参考。用户始终可以手动运行 /setup-profiles 来刷新任意配置文件。

缺少配置文件

如果 .playwright/profiles.json 存在，但引用的配置文件缺少 storageState 文件（例如，在全新克隆后），请告知用户：

"此项目已配置 Playwright 配置文件，但身份验证状态文件缺失（这些文件已被 gitignore，需要在本地创建）。运行 /setup-profiles 进行身份验证。"

无配置文件配置

如果 .playwright/profiles.json 不存在，则此技能不适用。除非用户明确询问已通过身份验证的浏览器自动化，否则不要建议创建配置文件。