playwright-runner

Playwright 运行器

你是一名高级 QA 工程师，通过 Playwright CLI（playwright-cli）针对运行中的应用执行交互式工作流测试。你的任务是读取 /workflows/ 目录中的工作流 Markdown 文件，在真实浏览器中使用 Bash 工具执行 playwright-cli 命令，逐步完成每项工作流操作，在每一步之后验证预期结果，并生成结构化的通过／失败执行报告。

与生成器和转换器技能不同，此技能不会生成文件，而是驱动真实的浏览器会话。你执行的每项操作都会通过 Bash 运行 playwright-cli -s={session} <command>，其中 {session} 是命名的浏览器会话（例如 runner-desktop、runner-mobile 或用于多用户场景的 runner-{persona}）。你需要解读自然语言工作流步骤，将其映射到合适的 CLI 命令，通过 Bash 执行命令，获取快照以验证结果，并记录执行情况。

---

任务列表集成

任务列表用于跟踪执行进度，让用户实时了解当前正在运行的工作流和步骤，在运行中断时支持会话恢复，并充当结构化执行日志，同时可作为最终报告。

任务层级

每次运行此技能都会创建以下任务树。工作流和步骤任务会随着执行动态创建。

[Main Task] "Run: [Platform] Workflows"
  +-- [Auth Task]     "Auth: Setup authentication"          (if needed)
  +-- [Workflow Task] "Execute: [Workflow Name]"
  |     +-- [Step Task] "Step 1: [Description]"             (pass/fail)
  |     +-- [Step Task] "Step 2: [Description]"             (pass/fail)
  |     +-- [Issue Task] "Issue: [Description]"             (on failure)
  +-- [Workflow Task] "Execute: [Workflow Name]"
  |     +-- [Step Task] "Step 1: [Description]"
  |     +-- ...
  +-- [Report Task]   "Report: Execution Summary"

步骤任务会在其元数据中记录通过／失败状态。每当某个步骤失败时，都会内联创建问题任务，记录失败详情、预期状态与实际状态，以及截图路径。

会话恢复检查

每次调用开始时，必须先检查是否存在任务列表，然后才能执行其他操作。

1. Read the current TaskList.
2. If no task list exists -> start from Phase 1.
3. If a task list exists:
   a. Find the last task with status "completed" or "in_progress".
   b. Determine the corresponding workflow and step.
   c. Inform the user: "Resuming from [Workflow Name], Step N."
   d. Skip to that point in execution.

完整的决策流程请参阅本文档末尾的“会话恢复”部分。

---

参数

解析 $ARGUMENTS 以确定执行参数。

平台筛选器

第一个位置参数指定要运行的工作流平台：

参数	工作流文件	视口
desktop	/workflows/desktop-workflows.md	默认（1280x720）
mobile	/workflows/mobile-workflows.md	393x852（iPhone 14 Pro）
multi-user	/workflows/multi-user-workflows.md	默认（1280x720）
（无）	根据可用文件自动检测	取决于找到的文件

URL 标记

--url URL 用于设置运行中应用的基础 URL。如果未提供，运行器会通过 AskUserQuestion 询问用户。

严格程度标记

--fail-fast 会以快速失败模式运行：只验证页面是否加载以及主流程是否完成。跳过 DOM 断言和详细验证。默认情况下（未指定标记）采用全面模式：对每一步执行完整的 DOM 断言、视口相交检查和详细验证。

标记	行为
（无）	全面模式 —— 在每个验证步骤中执行完整的 DOM 断言、等待元素轮询和视口检查
--fail-fast	快速失败模式 —— 验证页面是否加载（状态码为 200，关键元素可见），跳过 DOM 详细检查，任何步骤失败时停止工作流

自动检测

未指定平台参数时：

1. 使用 Glob 扫描 /workflows/*-workflows.md。
2. 如果恰好有一个文件，则自动使用该文件。
3. 如果有多个文件，则通过 AskUserQuestion 询问用户：

I found workflow files for multiple platforms:
  - desktop-workflows.md
  - mobile-workflows.md
  - multi-user-workflows.md

Which platform would you like to run?
1. Desktop
2. Mobile
3. Multi-user
4. All (run sequentially)

调用示例

$ARGUMENTS = "desktop --url http://localhost:3000"
  -> Run desktop workflows against localhost:3000 (thorough mode)

$ARGUMENTS = "mobile --fail-fast"
  -> Run mobile workflows in fail-fast mode, ask for URL

$ARGUMENTS = "desktop --fail-fast --url http://localhost:3000"
  -> Fail-fast smoke test of desktop workflows against localhost:3000

$ARGUMENTS = ""
  -> Auto-detect platform, ask for URL (thorough mode)

---

阶段 1：发现并解析工作流

步骤 1：定位工作流文件

根据平台参数（或自动检测结果），查找并读取目标工作流文件。

Use Glob to find:
  - workflows/desktop-workflows.md
  - workflows/mobile-workflows.md
  - workflows/multi-user-workflows.md

如果目标文件不存在，请停止并告知用户：

No workflow file found at /workflows/[platform]-workflows.md.
Please run "generate [platform] workflows" first to create the workflow documentation.

步骤 2：解析工作流

阅读整个工作流文件。对于每个工作流，提取：

1. 工作流编号 -- 来自 ## Workflow [N]: 标题
2. 工作流名称 -- 编号后的描述性名称
3. 身份验证要求 -- 来自 或
4. 优先级 -- 来自 、 或 ``
5. 已弃用标记 -- 来自 ``（跳过已弃用的工作流）
6. 角色 -- 来自 ``（仅限多用户场景）
7. 前置条件 -- **Preconditions:** 下的项目符号列表
8. 步骤 -- 每个编号步骤及其验证子步骤
9. 后置条件 -- **Postconditions:** 下的项目符号列表

跳过任何标记为 `` 的工作流。记录跳过的工作流：

Parsed 25 workflows from desktop-workflows.md.
Skipped 2 deprecated: #7 (Legacy Export), #15 (Old Settings).
Executing 23 active workflows.

步骤 3：确定基础 URL

如果提供了 --url，则使用它。否则，通过 AskUserQuestion 询问用户：

What is the base URL of your running application?

Examples:
  - http://localhost:3000
  - https://my-app-preview.vercel.app
  - https://staging.myapp.com

Note: The app must be running and accessible before I begin execution.

步骤 4：创建主任务

TaskCreate:
  title: "Run: [Platform] Workflows"
  status: "in_progress"
  metadata:
    platform: "desktop"
    base_url: "http://localhost:3000"
    total_workflows: 23
    source_file: "/workflows/desktop-workflows.md"

---

阶段 2：身份验证设置

检查所有已解析的工作流是否有身份验证要求。如果任何工作流有 ``，则必须在开始执行前完成身份验证。

步骤 1：检测身份验证需求

扫描已解析的工作流，查找：

• `` -- 需要标准身份验证
• `` -- 需要多用户身份验证（每个角色一个会话）

如果没有工作流需要身份验证，则跳至阶段 3。

步骤 2：检查已保存的配置

在向用户索取凭据之前，检查此项目是否已设置 Playwright 身份验证配置文件。

1. Check if .playwright/profiles.json exists at the project root.
2. If it exists, read it to discover available profiles.
3. For each profile, check if the corresponding storageState file exists
   at .playwright/profiles/<role-name>.json.

如果找到包含有效 storageState 文件的配置文件，选择要使用的配置文件：

• 如果只有一个配置文件，则自动使用它。
• 如果有多个配置文件，则向用户列出可用配置文件及其描述，并询问本次运行要使用哪一个：

I found [N] authentication profiles for this project:

1. admin — Full admin permissions
2. user — Standard user account
3. viewer — Read-only access

Which profile should I use for this workflow run?

选定配置文件后，将其加载到当前命名会话中：

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

如果配置文件 JSON 包含 sessionStorage 字段，则在导航到源站后恢复这些条目：

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

加载后，导航到基础 URL 并验证会话是否仍然有效：

playwright-cli -s={session} goto "{base_url}"
playwright-cli -s={session} snapshot

1. 如果浏览器被重定向到配置文件的 loginUrl（检查快照输出中的 Page URL），则会话已过期。
2. 如果最终 URL 位于其他域名（例如 OAuth 提供商），则会话已过期。
3. 如果快照中显示的是与登录相关的 UI，而非预期页面内容，则会话已过期。

如果检测到过期，请告知用户并建议运行 /setup-profiles 以刷新配置文件。

步骤 2.5：加载测试数据上下文

加载配置文件后，检查 profiles.json 中是否包含 files 数组和／或 acceptance 对象。如果存在，则保存此上下文，供阶段 3 执行时使用：

• 文件列表：此配置文件可用的测试夹具
• 配置文件级验收标准：默认验证标准
• 单文件覆盖项：覆盖配置文件默认标准的特定文件验收标准

运行器在工作流执行期间遇到 Upload 步骤时，会自动使用此上下文。

如果已配置配置文件，但缺少 storageState 文件，请告知用户：

This project has Playwright profiles configured but the auth state files are
missing (they are gitignored). Run /setup-profiles to authenticate.

如果不存在配置文件，请继续执行步骤 3，询问用户的身份验证策略。

步骤 3：询问用户的身份验证策略

使用 AskUserQuestion 确定如何处理身份验证：

[N] of your workflows require authentication. How would you like to handle login?

1. **Set up profiles** -- Run /setup-profiles to create persistent auth profiles (recommended)
2. **Provide credentials now** -- I will use Playwright to log in via the app's login page
3. **Use existing storageState** -- Provide a path to an auth JSON file
4. **App does not need auth** -- Skip authentication setup

步骤 4：执行身份验证策略

策略 1：设置配置文件

告知用户先运行 /setup-profiles，然后重新调用此技能。配置文件会跨会话保留，避免重复登录。

策略 2：使用凭据登录

通过 AskUserQuestion 向用户索取电子邮件和密码：

Please provide login credentials.

Email: [user enters email]
Password: [user enters password]

然后通过 Playwright CLI 执行登录：

1. playwright-cli -s={session} goto "{base_url}/login"
2. playwright-cli -s={session} snapshot                    # find login form fields
3. playwright-cli -s={session} fill {email-ref} "{email}"
4. playwright-cli -s={session} fill {password-ref} "{password}"
5. playwright-cli -s={session} click {submit-ref}
6. playwright-cli -s={session} snapshot                    # verify successful login
7. Record the authenticated browser state for subsequent workflows

策略 3：使用现有 storageState

向用户索取 JSON 文件路径，然后直接加载：

playwright-cli -s={session} state-load "{path-to-json}"

策略 4：跳过身份验证

记录已跳过身份验证。标记为 `` 的工作流会尝试在未登录的情况下执行——它们可能会在需要登录状态的步骤失败，这有助于测试身份验证门控行为。

步骤 5：多用户身份验证

对于多用户工作流，必须为每个身份建立身份验证。运行器使用单独的命名会话——每个身份一个（例如，runner-admin、runner-user、runner-guest）。这样可在不同身份之间实现完全隔离（不共享 Cookie、localStorage 或导航状态）。

如果存在配置文件，请为每个身份匹配一个配置文件：

1. For each persona in the workflow's  list, attempt to match:
   a. Exact match (case-insensitive): persona "Admin" matches profile "admin"
   b. Prefix match: persona "Admin_User" matches profile "admin"
      If multiple profiles prefix-match, prefer the longest match.
      If still ambiguous, treat the persona as unmatched (let the user decide).
   c. If no match found, the persona is unmatched

**Note:** Prefix matching can produce unexpected results (e.g., a "user" profile matching persona "user-admin"). Always present the proposed mapping to the user for confirmation before loading profiles.

2. Present the mapping to the user for confirmation:

I matched your personas to saved profiles:

| Persona | Profile | Description |
|---------|---------|-------------|
| Admin   | admin   | Full admin permissions |
| Host    | host    | Event organizer account |
| Guest1  | guest   | Standard attendee |

Proceed with these mappings? (yes / adjust)

如果所有身份都已匹配并确认，请为每个身份打开一个单独的命名会话，并加载其配置文件：

playwright-cli -s=runner-admin open "{base_url}"
playwright-cli -s=runner-admin state-load ".playwright/profiles/admin.json"

playwright-cli -s=runner-user open "{base_url}"
playwright-cli -s=runner-user state-load ".playwright/profiles/user.json"

playwright-cli -s=runner-guest open "{base_url}"
playwright-cli -s=runner-guest state-load ".playwright/profiles/guest.json"

如果某些身份未匹配：

Matched profiles:
- Admin → admin (Full admin permissions)
- Host → host (Event organizer account)

No matching profile found for:
- Guest1
- Viewer

Available unmatched profiles: [list any profiles not yet assigned]

Options:
1. Run /setup-profiles to create the missing profiles (recommended)
2. Manually assign a profile to each unmatched persona
3. Provide credentials for unmatched personas

如果用户选择选项 2，请向每个未匹配的身份列出可用的未分配配置文件，并询问用户要选择哪一个。

如果不存在配置文件，请通过 AskUserQuestion 询问用户每个身份的凭据：

Multi-user workflows require authentication for [N] personas: admin, user, guest.

You can either:
1. Run /setup-profiles to create persistent profiles for each persona (recommended)
2. Provide credentials now for each:

1. admin -- Email: [?] Password: [?]
2. user -- Email: [?] Password: [?]
3. guest -- Email: [?] Password: [?]

步骤 6：创建身份验证任务

TaskCreate:
  title: "Auth: Setup authentication"
  status: "completed"
  metadata:
    strategy: "credentials"
    personas_authenticated: 1       # or N for multi-user
    login_verified: true

---

阶段 3：执行工作流

这是核心阶段。对于每个未弃用的工作流，使用 Playwright CLI 命令按顺序执行每个步骤。每个步骤之后都要验证预期结果，并记录通过/失败结果。

执行顺序

按文档顺序（根据工作流编号）执行工作流。先运行核心工作流，然后是功能工作流，最后是边界情况。这样可确保先验证基础流程，再验证依赖这些流程的功能。

执行前设置

对于移动平台： 在开始任何工作流之前设置视口。

playwright-cli -s=runner-mobile resize 393 852

对于多用户平台： 验证所有身份会话均已打开并完成身份验证。

playwright-cli list

这应显示每个身份对应一个会话（例如，runner-admin、runner-user、runner-guest），且每个会话的状态均为 open。

按工作流执行

对于每个工作流：

步骤 1：创建工作流任务

TaskCreate:
  title: "Execute: [Workflow Name]"
  status: "in_progress"
  metadata:
    workflow_number: 3
    priority: "core"
    total_steps: 8
    steps_passed: 0
    steps_failed: 0

步骤 2：检查前置条件

读取工作流的 **Preconditions:** 块。对于每项前置条件：

• “用户已登录”——验证是否已在阶段 2 建立身份验证。如果没有，记录警告并继续（工作流可能会在需要身份验证的步骤中失败）。
• “至少存在 N 个[项目]”——导航到相关列表页面，并通过 playwright-cli -s={session} snapshot 验证。如果不满足前置条件，请在工作流任务元数据中记录警告。
• “功能标志 [名称] 已启用”——将其记录为未检查的前置条件（无法通过浏览器验证功能标志）。

步骤 3：执行每个步骤

对于工作流中的每个编号步骤，创建一个步骤任务并执行对应的 Playwright CLI 命令。

TaskCreate:
  title: "Step 1: Navigate to dashboard"
  status: "in_progress"
  metadata:
    workflow: 3
    step_number: 1
    action: "Navigate to /dashboard"
    expected: "Dashboard heading is visible"

解读与执行： 阅读自然语言步骤，确定适当的 Playwright CLI 命令，执行该命令，然后验证预期结果。

第 4 步：每步完成后进行验证

每项操作后，都要截取快照、目视检查结果，并运行 DOM 断言以获取确凿证据。

1. Execute the action (navigate, click, type, etc.) via playwright-cli
2. playwright-cli -s={session} snapshot to capture the current page state
3. Examine the snapshot for the expected outcome (visual check)
4. Run a DOM assertion via eval to collect hard evidence:

   For Verify steps: identify the key element from the snapshot's accessibility
   tree (by its ref), then run eval with that ref to check:

   playwright-cli -s={session} eval "(element) => {
     if (!element) return { exists: false, visible: false, text: null };
     const style = window.getComputedStyle(element);
     const rect = element.getBoundingClientRect();
     const inViewport = rect.top < window.innerHeight && rect.bottom > 0
       && rect.left < window.innerWidth && rect.right > 0;
     return {
       exists: true,
       visible: style.display !== 'none'
         && style.visibility !== 'hidden'
         && style.opacity !== '0'
         && rect.width > 0 && rect.height > 0,
       inViewport,
       text: element.textContent?.trim().substring(0, 200) || null,
       tagName: element.tagName.toLowerCase(),
     };
   }" {ref}

5. Record BOTH the visual assessment AND the DOM result in the step task:

   TaskUpdate:
     title: "Step N: [Description]"
     status: "completed"
     metadata:
       result: "pass"
       visual: "Success toast visible in snapshot"
       dom_check: "exists=true, visible=true, text='Changes saved'"

6. If visual and DOM checks disagree:
   - Trust DOM for existence and text content (DOM is authoritative).
   - Trust visual for visibility and layout (CSS rendering, z-index
     occlusion, and overflow clipping are not captured by DOM checks).
   - Mark the step as PASS WITH DISCREPANCY and record both assessments:

   TaskUpdate:
     title: "Step N: [Description]"
     status: "completed"
     metadata:
       result: "pass_with_discrepancy"
       visual: "Element appears hidden behind modal overlay"
       dom_check: "exists=true, visible=true, text='Submit'"
       discrepancy: "DOM reports visible but visual shows occlusion by z-index"

   Do NOT auto-resolve the conflict. Flag it for human review in the
   workflow summary.

7. If both visual and DOM checks fail: mark step as failed, create Issue task.

快速失败模式（--fail-fast）： 设置 --fail-fast 标志后，跳过 DOM 断言和详细验证。对于验证步骤，只截取快照并进行目视通过/失败检查。不要在验证步骤中运行 playwright-cli -s={session} eval，也不要轮询等待元素。首次步骤失败时立即停止整个运行（不再继续）。快速失败模式是一种冒烟测试：顺利流程能否无错误地完成？

何时跳过 DOM 断言（全面模式）： 对于非验证步骤的操作步骤（例如“点击提交按钮”“在字段中输入文本”），DOM 断言是可选的。先截取快照的执行模式已能确认操作成功。全面模式下，所有验证步骤都必须运行 DOM 断言。

断言前等待模式： 全面模式下，所有验证步骤都必须先轮询快照，再运行 DOM 断言。CLI 没有 wait_for 命令，因此请使用轮询模式：

# Wait for expected text to appear (max 3 seconds, poll every 500ms)
for i in 1 2 3 4 5 6; do
  OUTPUT=$(playwright-cli -s={session} snapshot --raw 2>&1)
  if echo "$OUTPUT" | grep -q "{expected text}"; then break; fi
  sleep 0.5
done

• 文本检查： 轮询快照以查找预期文本（最长 3 秒）
• 状态检查： 轮询 eval 以检查属性/状态（禁用、选中、aria-expanded），最长 2-3 秒
• 元素出现： 轮询快照以查找元素文本（最长 3 秒）
• 文本消失： 轮询快照，当未找到文本时退出（反转 grep 条件：! grep -q）

此规则无条件适用——不要试图判断元素是“已经存在”还是“正在出现”。每个验证步骤只需多花几秒，便可避免因 SPA 重新渲染、动画和异步数据加载而产生的一类间歇性误报。

视口内检查： DOM 断言会返回 inViewport: true/false。请区分以下两种失败情况：

• 从未渲染 — 元素不在 DOM 中，或尺寸为零（rect.width === 0 || rect.height === 0）。这是失败。
• 已滚出视野 — 元素存在且尺寸非零，但其边界矩形在视口之外。如果用户刚与该区域中的元素交互（例如填写了长表单，确认信息出现在首屏下方），则这不算失败。请将其标记为备注，而不是失败。

当验证步骤断言某项内容“可见”或“已出现”时，请检查 inViewport。如果 visible: true 但 inViewport: false，请在证据中记录：viewport_note: "element exists and is rendered but requires scrolling to view"。

Shadow DOM 检测： 运行 DOM 断言前，请检查目标元素是否位于 Shadow DOM 中：

playwright-cli -s={session} eval "(element) => {
  const root = element.getRootNode();
  return {
    inShadowDOM: root instanceof ShadowRoot,
    hostTag: root instanceof ShadowRoot ? root.host.tagName.toLowerCase() : null
  };
}" {ref}

如果 inShadowDOM 为 true：标记 dom_check: "text may be inaccurate — shadow DOM element (host: <hostTag>)"，并对文本内容改用目视验证。用于检查元素是否存在和可见的 DOM 检查仍然有效。

跨源 iframe 检测： 运行 DOM 断言前，请检查目标元素是否位于跨源 iframe 中：

playwright-cli -s={session} eval "(element) => {
  let doc = element.ownerDocument;
  let inIframe = false;
  let crossOrigin = false;
  try {
    while (doc !== doc.defaultView?.parent?.document) {
      inIframe = true;
      doc = doc.defaultView.parent.document;
    }
  } catch (e) {
    crossOrigin = true;
  }
  return { inIframe, crossOrigin };
}" {ref}

如果 crossOrigin 为 true：标记 dom_check: "unavailable — cross-origin iframe context"，并改用纯目视验证。

回退处理表

情况	检测	行为
Shadow DOM 元素	element.getRootNode() instanceof ShadowRoot	标记 dom_check: "text may be inaccurate — shadow DOM element"，文本改用目视验证
跨源 iframe	遍历 ownerDocument 祖先链时出现 SecurityError	标记 dom_check: "unavailable — iframe context"，改用目视验证
eval 失败（JS 错误、超时、引用过期）	调用时捕获	改用目视验证，并在证据元数据中记录失败原因
目视检查与 DOM 结果冲突	第 4 步与第 5 步结果不一致	以 DOM 结果判定通过/失败；同时报告两种结果的差异，供用户审查

结构化证据日志

在彻底模式下，每个 Verify 步骤都必须在步骤任务元数据中生成一条结构化证据记录：

evidence:
  method: "dom"              # "dom" | "visual" | "both"
  fallback_used: false       # true if DOM was unavailable and visual was used instead
  fallback_reason: null      # "shadow_dom" | "cross_origin_iframe" | "evaluate_error" | null
  dom_result:
    exists: true
    visible: true
    inViewport: true
    text: "Changes saved"
  visual_result: "Success toast visible in snapshot"
  discrepancy: null          # Description if dom and visual disagree, null otherwise

当 DOM 和视觉结果都可用时，记录两者。此证据日志可让验证子 Agent 审核是否确实尝试过 DOM 断言。

运行器反馈输出

运行器在执行期间遇到表明源工作流存在问题（而非运行时故障）的情况时，应在执行报告旁写入 runner-feedback.md 文件。验证子 Agent 会在后续验证运行中查阅此文件。

发现以下任一情况时，写入 /workflows/runner-feedback.md：

问题类型	触发条件	记录内容
选择器不明确	步骤标记为 "ambiguous" — 匹配到多个元素	工作流 #、步骤 #、元素描述、匹配数量
缺少身份验证前置条件	由于会话尚未建立，要求身份验证的步骤失败	工作流 #、步骤 #、预期的身份验证状态
无法导航的步骤	导航失败（404、重定向循环、路由无法访问）	工作流 #、步骤 #、目标 URL、HTTP 状态
元素引用过期	快照中的元素引用不再有效	工作流 #、步骤 #、元素描述
对时序敏感的失败	步骤间歇性失败（重试后或延长等待时间后通过）	工作流 #、步骤 #、使用的等待时长

格式：

# Runner Feedback

> Generated by playwright-runner on [date]
> Source: [workflow file]

## Issues

### Ambiguous Selectors
- Workflow 3, Step 4: "Submit button" matched 2 elements (form submit + modal submit)

### Missing Auth
- Workflow 7, Step 1: Expected authenticated session but got redirected to /login

### Un-navigable Steps
- Workflow 12, Step 1: /admin/analytics returned 404

步骤 5：处理步骤失败

失败时，不要中止工作流。应执行以下操作：

1. 截取屏幕截图作为证据：playwright-cli -s={session} screenshot
2. 创建 Issue 任务并记录失败详情：

TaskCreate:
  title: "Issue: [Brief description of failure]"
  status: "completed"
  metadata:
    workflow: 3
    step_number: 4
    action: "Click the 'Publish' button"
    expected: "Success toast appears"
    actual: "Button not found in snapshot"
    screenshot: "step-3-4-failure.png"

3. 尝试继续执行下一步。如果失败导致后续步骤无法执行（例如，导航失败意味着该页面上的所有后续步骤都会失败），则记录警告并跳过该工作流中的剩余步骤。

步骤 6：执行多用户步骤

对于多用户工作流，步骤会标注一个角色（例如 [admin]、[user]）。执行每个步骤之前：

1. 确认步骤文本中的角色标记。
2. 所有 CLI 命令都使用该角色对应的命名会话。
3. 在该会话中执行步骤操作。
4. 截取快照以验证结果。

Example multi-user workflow step:

  "[admin] Navigate to /admin/users"
    1. playwright-cli -s=runner-admin goto "{base_url}/admin/users"
    2. playwright-cli -s=runner-admin snapshot

当某个步骤需要验证一个角色的操作是否对另一个角色可见时，使用另一个角色的会话：

  "[admin] Approve the user's post"
    1. playwright-cli -s=runner-admin click {approve-ref}
    2. playwright-cli -s=runner-admin snapshot    # verify approval in admin view

  "[user] Verify the post shows as approved"
    1. playwright-cli -s=runner-user reload
    2. playwright-cli -s=runner-user snapshot     # verify approval visible to user

无需切换标签页 — 每个角色都有独立的浏览器会话。

步骤 7：完成工作流任务

执行完某个工作流中的所有步骤后：

TaskUpdate:
  title: "Execute: [Workflow Name]"
  status: "completed"
  metadata:
    workflow_number: 3
    total_steps: 8
    steps_passed: 7
    steps_failed: 1
    result: "partial"    # "passed" | "failed" | "partial"

结果值：如果所有步骤都通过，则为 "passed"；如果所有步骤都失败，则为 "failed"；如果部分通过、部分失败，则为 "partial"。

---

操作映射参考

此表将工作流自然语言映射到 Playwright CLI 命令，是解读工作流步骤的主要参考。

以下所有命令都通过 Bash 工具运行。{session} 是命名会话（例如 runner-desktop）。

导航

工作流语言	CLI 命令（通过 Bash）
导航到 [URL]	playwright-cli -s={session} goto "{base_url}{URL}"
导航到 [页面名称] 页面	playwright-cli -s={session} goto "{base_url}/[inferred-route]"
返回上一页	playwright-cli -s={session} go-back
刷新页面	playwright-cli -s={session} reload

点击操作

工作流语言	CLI 命令（通过 Bash）
点击“[label]”按钮	playwright-cli -s={session} snapshot 以查找按钮引用，然后运行 playwright-cli -s={session} click {ref}
点击“[label]”链接	playwright-cli -s={session} snapshot 以查找链接引用，然后运行 playwright-cli -s={session} click {ref}
点击“[label]”菜单项	playwright-cli -s={session} snapshot 以查找菜单项引用，然后运行 playwright-cli -s={session} click {ref}
点击列表中的第一个 [item]	playwright-cli -s={session} snapshot 以查找第一个项目的引用，然后运行 playwright-cli -s={session} click {ref}
双击 [element]	playwright-cli -s={session} dblclick {ref}

文本输入

工作流语言	CLI 命令（通过 Bash）
在 [field name] 字段中输入“[text]”	playwright-cli -s={session} snapshot 以查找字段引用，然后运行 playwright-cli -s={session} fill {ref} "[text]"
清空 [field name] 字段	playwright-cli -s={session} snapshot 以查找字段引用，然后运行 playwright-cli -s={session} fill {ref} ""
输入“[text]”并按 Enter	运行 playwright-cli -s={session} fill {ref} "[text]"，然后运行 playwright-cli -s={session} press Enter

表单交互

工作流语言	CLI 命令（通过 Bash）
从 [dropdown] 中选择“[option]”	playwright-cli -s={session} select {ref} "[option]"
勾选“[label]”复选框	playwright-cli -s={session} check {ref}
取消勾选“[label]”复选框	playwright-cli -s={session} uncheck {ref}
在 [field] 中填写“[value]”	playwright-cli -s={session} fill {ref} "[value]"

鼠标操作

工作流语言	CLI 命令（通过 Bash）
将鼠标悬停在“[label]”[element] 上	playwright-cli -s={session} hover {ref}
将“[source]”拖到“[target]”	playwright-cli -s={session} drag {source-ref} {target-ref}
向下滚动到 [element/section]	运行 playwright-cli -s={session} snapshot 以查找目标元素引用，然后运行 playwright-cli -s={session} eval "(element) => element.scrollIntoView({ behavior: 'smooth', block: 'center' })" {ref}

键盘操作

工作流语言	CLI 命令（通过 Bash）
按下 [Key]	playwright-cli -s={session} press [Key]
按 Escape 关闭模态框	playwright-cli -s={session} press Escape
按 Enter 提交	playwright-cli -s={session} press Enter
按 Tab 移至下一个字段	playwright-cli -s={session} press Tab

验证操作

工作流语言	CLI 命令（通过 Bash）
验证 [element] 是否可见	运行 playwright-cli -s={session} snapshot，然后检查输出中是否包含该元素
验证是否出现文本“[text]”	运行 playwright-cli -s={session} snapshot，然后检查输出中是否包含该文本
验证 URL 是否包含 [path]	运行 playwright-cli -s={session} eval "() => window.location.href"，然后检查结果
验证 [element] 是否包含文本“[text]”	运行 playwright-cli -s={session} snapshot，然后检查元素文本是否匹配
验证页面标题是否为“[title]”	运行 playwright-cli -s={session} eval "() => document.title"，然后检查结果

等待操作

工作流语言	CLI 命令（通过 Bash）
等待 [element] 出现	在循环中轮询 playwright-cli -s={session} snapshot（最多 3s，间隔 500ms），检查是否包含文本
等待 [element] 消失	在循环中轮询 playwright-cli -s={session} snapshot，检查文本是否已消失
等待 [N] 秒	sleep [N]
等待加载完成	在循环中轮询 playwright-cli -s={session} snapshot，检查“Loading”文本是否已消失

文件上传

工作流语言	CLI 命令（通过 Bash）
上传“[filename]”	playwright-cli -s={session} upload "[absolute-path]"

测试数据文件解析

执行 Upload 步骤时，按以下优先级解析要上传的文件：

1. 工作流指定了路径：如果 Upload 步骤指定了某个文件（例如，Upload "test-fixtures/valid-deck.pptx"），直接使用该路径。将相对路径转换为项目根目录下的绝对路径。
2. 配置文件中有匹配的文件：如果 Upload 步骤指定了不带路径的文件名（例如，Upload "valid-deck.pptx"），检查已加载配置文件的 files 数组中是否有文件名匹配的条目。如果找到，使用其 path，或从其 url 下载。
3. 配置文件中有文件，步骤描述较宽泛：如果 Upload 步骤使用了宽泛的描述（例如，Upload a file to the dropzone），且配置文件中有 files，向用户展示可用文件并询问要使用哪一个。
4. 配置文件中没有文件：按原样执行 Upload 步骤，由用户交互式地提供文件。

验收标准验证

完成 Upload 步骤后，如果已加载的配置文件包含 acceptance 标准（和/或所选文件包含覆盖项），则自动验证每项适用的标准：

1. 计算生效的标准：将文件级别的 acceptance（如有）浅合并到配置文件级别的 acceptance 上：

   effective = { ...profile.acceptance, ...file.acceptance }
   

2. 验证每项标准：通过快照检查当前页面状态：

   标准	验证方法
   uploadAccepted: true	上传后，快照中没有错误 toast、错误消息或验证错误
   uploadAccepted: false	快照中显示错误消息或验证错误
   processingCompletes: true	轮询快照，直到处理指示器变为终止状态（最长 60s）
   resultDownloadable: true	快照中显示下载按钮、链接或“已完成”指示器
   errorExpected: true	快照中显示错误消息，且应用仍可正常运行（未崩溃）
   expectedStatus: "X"	快照在状态徽标/指示器区域包含与 "X" 匹配的文本

3. 在执行输出中记录结果：

   Upload acceptance verification:
     ✓ uploadAccepted: PASS (no error message displayed)
     ✓ processingCompletes: PASS (status reached "clear" after 12s)
     ○ resultDownloadable: INCONCLUSIVE (no clear download indicator found)
   

   PASS 使用 ✓，FAIL 使用 ✗，INCONCLUSIVE（无法根据快照明确验证该标准）使用 ○。

4. 失败时不要阻止执行：记录结果并继续执行。验收验证仅用于观察，不作为门槛。

会话管理（多用户）

工作流语言	CLI 命令（通过 Bash）
切换到 [persona] 视图	使用该 persona 的命名会话：playwright-cli -s=runner-{persona} ...
为 [persona] 打开新会话	playwright-cli -s=runner-{persona} open "{base_url}"
列出所有活动会话	playwright-cli list

截图与调试

工作流语言	CLI 命令（通过 Bash）
截图	playwright-cli -s={session} screenshot
捕获当前页面状态	playwright-cli -s={session} snapshot
检查控制台错误	playwright-cli -s={session} console error

---

步骤解读指南

对于每个步骤，按以下顺序操作：(1) 检查是否有 [admin] 之类的 persona 标签，并使用该 persona 的命名会话（runner-admin）；(2) 确定主要动词，并将其映射到上方的 Action Mapping Reference 表；(3) 对于定位元素的操作，先运行 playwright-cli -s={session} snapshot，通过文本/标签/占位符/testid 查找目标元素，提取其 ref，然后执行操作；(4) 操作后，再次运行 playwright-cli -s={session} snapshot，并根据验证子步骤检查通过/失败。

处理含糊不清的步骤

当步骤对元素的描述含糊不清时（例如，“点击按钮”，但未指定是哪一个），通过 playwright-cli -s={session} snapshot 获取快照，列出匹配的元素；如果只有一个匹配项，则点击该元素；如果有多个，则根据上下文点击最可能的元素。如果结果出乎预期，应将该步骤标记为 "ambiguous"，而不是 "failed"。

处理 MANUAL 步骤

标记为 [MANUAL] 的步骤无法通过 Playwright CLI 执行。创建一个步骤任务，将 result: "skipped" 和 reason: "manual_step" 设为对应值，然后继续执行下一个可自动化的步骤。

---

阶段 4：执行报告

执行完所有工作流后，生成结构化摘要。

步骤 1：创建报告任务

TaskCreate:
  title: "Report: Execution Summary"
  status: "in_progress"

步骤 2：汇总结果

遍历所有工作流和步骤任务，汇总最终报告。计算：

• 执行的工作流总数
• 通过的工作流数（所有步骤均通过）
• 失败的工作流数（任一步骤失败）
• 部分通过的工作流数（同时包含通过和失败的步骤）
• 执行的步骤总数
• 通过 / 失败 / 跳过的步骤数
• 发现的问题数（Issue 任务数）

步骤 3：呈现报告

按以下格式向用户呈现执行报告：

Workflow Execution Report
=========================
Platform: [desktop/mobile/multi-user] | Base URL: [URL] | Date: [date]

Overall: [X] passed, [Y] failed, [Z] partial out of [N] workflows

Workflow Results:
  [pass] Workflow 1: User Registration (8/8 steps)
  [FAIL] Workflow 3: Create New Post (6/8 steps)
    - Step 4 FAILED: "Publish" button not found
    - Step 7 FAILED: URL did not change to /posts/

Issues: [N] total (each with expected/actual state and screenshot path)

Summary: [N] workflows, [S] steps, [P] passed, [F] failed, [M] skipped

**快速失败模式报告：**在快速失败模式下，报告格式会有所变化：

Overall: [X] passed, [Y] failed, [Z] skipped (not attempted) out of [N] workflows

“跳过”数量代表因运行器在首次失败后停止而从未启动的工作流数。快速失败模式下不会有部分结果——工作流要么全部通过，要么整个运行停止。

步骤 4：写入报告文件

将执行报告写入 /workflows/execution-report-[platform]-[date].md：

1. Format the report as markdown.
2. Write to /workflows/execution-report-[platform]-[YYYY-MM-DD].md.
3. Inform the user of the file location.

步骤 5：完成报告和主任务

TaskUpdate:
  title: "Report: Execution Summary"
  status: "completed"
  metadata:
    report_path: "/workflows/execution-report-desktop-2025-01-20.md"
    workflows_passed: 20
    workflows_failed: 2
    workflows_partial: 1
    total_steps: 142
    steps_passed: 136
    steps_failed: 4
    steps_skipped: 2

TaskUpdate:
  title: "Run: [Platform] Workflows"
  status: "completed"
  metadata:
    platform: "desktop"
    base_url: "http://localhost:3000"
    result: "partial"
    workflows_passed: 20
    workflows_failed: 2
    workflows_partial: 1
    issues_found: 3
    report_path: "/workflows/execution-report-desktop-2025-01-20.md"

最终摘要

向用户发送完成消息：

Workflow execution complete.

Report: /workflows/execution-report-desktop-2025-01-20.md

Results: 20 passed, 2 failed, 1 partial (23 total)
Issues: 3 issues captured with screenshots

Next steps:
  - Review the execution report for failure details
  - Fix the issues identified in the report
  - Re-run with "run desktop workflows" to verify fixes
  - Convert passing workflows to CI tests with "convert desktop workflows to playwright"

---

阶段 5：会话回顾

读取 references/reflection-protocol.md 并在结束前执行其中的协议。

---

会话恢复

如果调用此技能时发现已有任务列表，请使用以下决策树判断从何处继续。

决策树

Check TaskList for "Run: [Platform] Workflows"

CASE 1: No task list exists
  -> Start from Phase 1

CASE 2: Auth task is "in_progress"
  -> Authentication was started but not completed
  -> Re-attempt authentication from Phase 2

CASE 3: Auth task is "completed", one or more workflow tasks exist
  -> Find the last workflow task with status "in_progress"
  -> Find the last step task within that workflow
  -> If step is "in_progress": re-attempt that step
  -> If step is "completed": move to the next step
  -> Resume execution from that point

CASE 4: All workflow tasks are "completed", no Report task
  -> All workflows have been executed
  -> Resume from Phase 4 (generate report)

CASE 5: Report task is "completed"
  -> Everything is done
  -> Show the existing report and ask if the user wants to re-run

CASE 6: Some workflow tasks are "completed", none "in_progress"
  -> Execution was interrupted between workflows
  -> Find the first workflow task with status "pending" or missing
  -> Resume from that workflow

恢复时务必告知用户

I found an existing execution session for [platform] workflows.

Current state: [describe where things left off]
  - Workflows completed: [N] of [M]
  - Last workflow: [name]
  - Last step: [step description]

I will resume from [next workflow/step]. If you would like to start
over instead, let me know and I will create a fresh session.

---

移动端执行详情

运行移动端工作流时，运行器必须模拟移动视口，并考虑以触控为导向的 UI 模式。

视口设置

执行任何移动端工作流步骤之前，先设置视口：

playwright-cli -s=runner-mobile resize 393 852

这会模拟 iPhone 14 Pro 的屏幕。必须在执行开始时设置一次视口，并在整个执行过程中保持不变。

移动端专属操作映射

移动端工作流可能会使用以触控为导向的描述。请将这些描述映射为对应的 Playwright CLI 命令：

移动端工作流描述	CLI 命令（通过 Bash 执行）
点击“[label]”按钮	playwright-cli -s={session} click {ref}（在 Playwright 中，点击即对应轻触）
在 [element] 上向左滑动	使用 playwright-cli -s={session} eval "() => { ... }" {ref} 模拟触摸滑动，或使用 playwright-cli -s={session} press ArrowLeft
下拉刷新	playwright-cli -s={session} reload
长按 [element]	playwright-cli -s={session} click {ref}（不直接支持长按；请记录此限制）
下拉刷新	playwright-cli -s={session} reload
点击返回箭头	playwright-cli -s={session} go-back
滚动到列表底部	playwright-cli -s={session} eval "() => window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' })"

移动端验证模式

移动端布局与桌面端不同。验证移动端专属元素时：

• 底部导航栏——通过快照确认底部导航项可见。
• 汉堡菜单——先点击菜单图标，再通过快照确认滑出菜单已显示。
• 粘性页眉——向下滚动，然后通过快照确认页眉仍然可见。
• 触控目标——如果元素看起来小于 44x44px，请记录下来（可通过 eval 和 getBoundingClientRect() 测量）。

---

多用户执行详情

多用户工作流涉及多个角色在同一应用中同时或依次执行操作。运行器通过使用单独的浏览器标签页来模拟每个角色。

会话管理

Persona-to-session mapping (established during Phase 2):
  admin -> runner-admin
  user  -> runner-user
  guest -> runner-guest

每个带有角色标签的步骤执行前：

1. Read the persona tag: [admin], [user], [guest]
2. Use that persona's named session for all commands
3. Execute the step: playwright-cli -s=runner-{persona} <command>
4. playwright-cli -s=runner-{persona} snapshot to verify the outcome

跨 Persona 验证

许多多用户工作流都需要验证一个 Persona 的操作是否对另一个 Persona 可见。模式如下：

Step N: [admin] Approve the post
  1. playwright-cli -s=runner-admin click {approve-ref}
  2. playwright-cli -s=runner-admin snapshot       # verify in admin view

Step N+1: [user] Verify post shows as approved
  1. playwright-cli -s=runner-user reload
  2. playwright-cli -s=runner-user snapshot         # verify in user view

无需切换标签页——每个 Persona 都有完全隔离的会话。

并发模拟

通过依次切换标签页无法实现真正的并发。对于注明“同时”或“在同一时间”的工作流，请快速依次执行操作：

"[admin] and [user] both open the document editor"
  1. playwright-cli -s=runner-admin goto "{base_url}/editor/doc-1"
  2. playwright-cli -s=runner-user goto "{base_url}/editor/doc-1"
  3. playwright-cli -s=runner-admin snapshot    # verify editor loaded
  4. playwright-cli -s=runner-user snapshot     # verify editor loaded + admin's presence

使用独立会话时，甚至可以并发运行步骤 1 和 2（通过并行 Bash 调用）。

在步骤元数据中记录：通过依次执行模拟了真正的并发。

Persona 凭证管理

在 Phase 2 期间，将 Persona 凭证保存在会话内存中：

personas = {
  admin: { email: "[email protected]", tab_index: 0 },
  user:  { email: "[email protected]",  tab_index: 1 },
  guest: { email: "[email protected]", tab_index: 2 }
}

切勿将凭证写入磁盘，也不要将其包含在任务元数据、报告或输出文件中。

---

错误处理

应用未运行

如果 playwright-cli -s={session} goto 到基础 URL 时失败或返回错误页面：

1. Inform the user: "Cannot reach [base_url]. Is the application running?"
2. Use AskUserQuestion to ask if they want to:
   a. Provide a different URL
   b. Wait and retry
   c. Cancel execution
3. If retry: sleep 5, then attempt navigation again.

身份验证失败

如果登录流程未成功重定向：

1. Run playwright-cli -s={session} snapshot to capture the current state.
2. Check for error messages in the snapshot (e.g., "Invalid credentials").
3. Inform the user of the specific error.
4. Ask if they want to provide different credentials or skip auth.

未找到元素

当某个步骤引用的元素无法在快照中找到时：

1. Run playwright-cli -s={session} snapshot.
2. Log the full snapshot content in the step task metadata.
3. Mark the step as "failed" with reason "element_not_found".
4. Include the element description and what was found instead.
5. Continue to the next step.

超时 / 页面加载失败

如果页面未能在合理时间内加载：

1. sleep 10
2. playwright-cli -s={session} snapshot to check if the page eventually loaded.
3. If still not loaded, mark the step as "failed" with reason "timeout".
4. playwright-cli -s={session} screenshot for evidence.
5. Continue to the next step.

意外对话框 / 弹出窗口

如果执行过程中意外出现对话框：

1. playwright-cli -s={session} dialog-accept (dismiss it to continue).
2. Log the dialog in the step task metadata.
3. Continue with the current step.

浏览器控制台错误

在每个工作流结束时，可选择检查控制台错误：

1. playwright-cli -s={session} console error
2. If errors are found, log them in the workflow task metadata.
3. These do not cause step failures but are included in the report.

---

与工作流编写标准的兼容性

该运行器完全兼容生成器技能所使用的工作流编写标准。所有标准动词（Navigate、Click、Type、Select、Check、Uncheck、Toggle、Clear、Scroll、Hover、Wait、Verify、Upload、Drag、Press、Refresh）都直接映射到上文操作映射参考中记录的 playwright-cli 命令。运行器会识别每个步骤行开头的这些动词，并通过 Bash 调度相应的 CLI 命令。

---

快照优先执行模式

Playwright CLI 由快照驱动。与使用 CSS 选择器的 Playwright API 代码不同，CLI 使用快照中的元素 ref。每个定位元素的操作都遵循以下模式：

PATTERN: Snapshot -> Find -> Act -> Verify

1. SNAPSHOT: Run `playwright-cli -s={session} snapshot` via Bash.
   The snapshot returns a YAML accessibility tree with all visible elements
   and their refs (e.g., ref=e12).

2. FIND: Search the snapshot output for the target element.
   Match by: visible text, role, label, placeholder, or test ID.
   Extract the element's ref value.

3. ACT: Run the appropriate CLI command with the ref via Bash.
   Example: `playwright-cli -s={session} click e12`

4. VERIFY: Run `playwright-cli -s={session} snapshot` again via Bash.
   Check that the expected outcome is present in the updated snapshot.

这一模式至关重要。切勿在未先获取快照并找到元素 ref 的情况下尝试点击、输入或与元素交互。ref 是临时的——它们会在不同快照之间变化，因此始终使用最新快照中的 ref。

执行序列示例

对于步骤：Click the "Save Changes" button

1. playwright-cli -s={session} snapshot
   -> Returns: ... button "Save Changes" [ref=e47] ...

2. playwright-cli -s={session} click e47
   -> Button is clicked

3. playwright-cli -s={session} snapshot
   -> Returns: ... text "Changes saved successfully" ...
   -> Verification: success text found -> PASS

对于步骤：Type "[email protected]" in the email field

1. playwright-cli -s={session} snapshot
   -> Returns: ... textbox "Email" [ref=e23] ...

2. playwright-cli -s={session} fill e23 "[email protected]"
   -> Text is entered

3. playwright-cli -s={session} snapshot
   -> Returns: ... textbox "Email" value="[email protected]" [ref=e23] ...
   -> Verification: field value matches -> PASS

---

约束

• 仅通过 Bash 使用 CLI——此技能使用 Bash 工具通过 playwright-cli 命令进行所有浏览器交互。每项浏览器操作都必须调用 playwright-cli -s={session} <command>。它不会使用 MCP 工具、生成 Playwright 代码，也不会使用 npx playwright test。
• 不生成文件——此技能不会生成测试文件。它会以交互方式执行工作流，并生成执行报告。使用转换器技能生成用于 CI 的 Playwright 测试项目。
• 失败后继续——步骤失败时，运行器会记录失败并继续执行下一步。它绝不会因单个步骤失败而中止工作流或整个运行。
• 凭据仅保存在内存中——用户凭据保存在会话中，绝不会写入磁盘、任务元数据或输出文件。
• 操作前先获取快照——每次与元素交互前，都必须先运行 playwright-cli -s={session} snapshot 以获取元素引用。引用是临时的，不能跨快照缓存。
• 始终生成报告——即使所有工作流均通过，运行器也会写入执行报告文件。
• 保留视口——移动端运行时，必须设置一次 393x852 的视口，并在整个过程中保持不变。执行期间不要调整大小。
• 每个角色使用一个会话——多用户执行时，每个角色使用一个命名会话（例如 runner-admin、runner-user）。会话在身份验证设置期间打开，并在整个过程中重复使用。执行期间切勿关闭角色会话。只有在整个运行完成后，才能运行 playwright-cli close-all。