mcpField
A
aif-qa-check

aif-qa-check

github.com/lee-to测试与质量1.1k44 次安装今天更新
代码仓库

关于 aif-qa-check

aif-qa-check 是不绑定技术栈或 Agent 运行环境的测试执行技能，支持人工引导和自动化模式，并记录测试结果。Agent 模式还会复用执行记录和浏览器回放脚本进行回归检查。

主要功能

  1. 01人工引导与自动化 QA
  2. 02将结果记录到 qa-check.md
  3. 03复用跨轮次 QA 上下文
  4. 04回放浏览器测试以检查回归
  5. 05使用多种执行方式

适用场景

  1. 01由人工确认测试用例结果
  2. 02通过可用工具执行测试用例
  3. 03修复后重测浏览器行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lee-to/ai-factory --skill aif-qa-check

安装后在 Claude Code 中输入/aif-qa-check确认已加载。

附带文件templates/QA-CHECK.md

详细介绍

QA 检查 — 执行测试用例

运行 /aif-qa 生成的 test-cases.md 工件，并在 qa-check.md 中记录执行状态。 在 Agent 模式下，还会在 QA 根目录下维护可跨 QA 复用的执行记忆：

  • agent-context.md — 为后续自动化 QA 运行整理并持续更新的非敏感设置事实
  • agent-history.md — 从先前运行中提取的可复用经验，只追加内容，不作为单次运行的审计日志

对于浏览器/UI 用例，Agent 模式会在特定分支的 browser-replay/ 目录下保存可执行的回放脚本。后续运行会先执行这些脚本，包括先前已通过用例的脚本，以便重新测试修复内容，并在无需重新生成浏览器自动化的情况下覆盖先前行为，进行回归测试。

此技能不依赖特定技术栈或 Agent：它不假设使用任何框架、包管理器、浏览器工具名称或 Agent 运行时。在 Agent 模式下，它会针对每个用例使用最合适的可用执行方式：实时浏览器自动化、CLI 命令、项目测试运行器、HTTP/API 调用、数据库安全只读检查、文件/文档检查，或其他非破坏性自动验证。

模式

参数模式操作
human人工引导 QA每次只展示一个测试用例，询问用户是否正常运行，并记录其回答
agent自动化 Agent QA使用最合适的可用功能执行测试用例，并记录观察到的结果

如果未提供模式，请询问用户要运行哪种模式。

工作流

步骤 0：加载配置

首先： 如果 .ai-factory/config.yaml 存在，请读取它以解析：

  • 路径： paths.description、paths.architecture、paths.qa（默认值：.ai-factory/qa）
  • 语言：
    • language.ui 用于 AskUserQuestion 提示、进度消息、摘要和下一步指导
    • language.artifacts 用于持久化的 qa-check.md 工件
    • language.technical_terms 用于工件中面向用户的技术术语风格
    • 如果缺少 language.artifacts，则使用 language.ui
    • 如果两者都缺少，则使用 en
  • Git： git.enabled 用于分支解析

如果 config.yaml 不存在，则使用默认值：

  • DESCRIPTION.md：.ai-factory/DESCRIPTION.md
  • ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
  • QA 工件：.ai-factory/qa/
  • ui_language：en
  • artifact_language：en
  • technical_terms_policy：keep
  • Git 已启用：true

保存：

  • ui_language = language.ui || "en"
  • artifact_language = language.artifacts || language.ui || "en"
  • technical_terms_policy = language.technical_terms || "keep"
  • 如果存在 git.enabled，则 git_enabled = git.enabled；否则为 true
  • qa_root = resolved paths.qa || ".ai-factory/qa/"
  • qa_agent_context_path = <qa_root>/agent-context.md
  • qa_agent_history_path = <qa_root>/agent-history.md

所有 AskUserQuestion 提示、面向用户的说明、每个用例的摘要和最终摘要都必须使用 ui_language 编写。

持久化的 qa-check.md 工件必须使用 artifact_language 编写。

模板定义结构，而非语言。请使用 templates/QA-CHECK.md 中的规范英文模板。如果 artifact_language 不是 en，保存前请将标题、标签、状态文本、你编写的注释和说明性文本翻译为 artifact_language。保留复选框语法、测试用例 ID（TC-001）、命令、路径、配置键、URL、选择器、包名、API 名称、分支名称和原始错误消息。

当 artifact_language = ru 时，请使用俄语编写面向用户的正文、标题、状态、摘要和由 Agent 编写的注释。除写入前必须对敏感值进行脱敏外，保留用户原话。

编写工件时应用 technical_terms_policy：

  • keep — 在更清晰时保留常见技术术语，例如 browser、selector、viewport、endpoint、payload、regression 和 fixture
  • translate — 存在自然的目标语言译法时，翻译面向用户的技术术语
  • mixed — 翻译普通文本术语，同时保持代码、基础设施和生态系统术语不变
步骤 0.1：加载项目上下文

如果已解析的描述路径存在，则读取该路径。

如果已解析的架构路径存在，则读取该路径。

读取 .ai-factory/skill-context/aif-qa-check/SKILL.md ——如果该文件存在，则此操作为强制要求。将其视为此技能的项目级覆盖规则。

如果 <paths.qa>/agent-context.md 存在，则读取该文件。将其视为可复用于未来自动化运行、且经用户批准的 QA 执行上下文：稳定的环境类别、规范的本地/暂存环境 URL、登录路由、测试账号角色、允许使用的非敏感用户名、必要的种子数据模式、稳定的选择器、字段标识符、已知重定向、启动前提、安全的命令模式、可复用的测试筛选约定、环境说明以及服务启动说明。

如果 <paths.qa>/agent-history.md 存在，则读取该文件。将其视为以追加方式记录的跨 QA 记忆，内容来自之前的 /aif-qa-check 运行。在询问用户或尝试自动化执行之前，先搜索其中是否有对同一阻碍的可复用答案，避免重复犯可避免的错误。

agent-context.md 和 agent-history.md 是 paths.qa 下所有 QA 集共用的文件。它们不得成为特定 QA 计划的日志。不要写入分支名称、分支 slug、QA 目标路径、当前 artifact_dir、TC-* 映射、单次运行的摘要计数、详尽的命令执行记录、单次运行的断言计数、一次性文件检查，或诸如编号 QA 文件夹名称等计划专属标签。此类详情只能写入 <paths.qa>/<branch-slug>/qa-check.md。

只有在信息可能对未来无关的 QA 运行有所帮助时，才将其纳入 agent-context.md 或 agent-history.md。优先记录稳定模式，而非具体的一次性运行事实。例如：Laravel backend checks use php artisan test --filter=<TestClass> 是可复用信息；05-profile-formula-recommendations ran ProfileReaderTest with 4 tests / 13 assertions 则是特定运行信息，只应记录在 qa-check.md 中。

除非对整个项目都成立，否则绝不要写入全局性的能力或范围否定声明。若某一结论来自单个 QA 计划，不要在 agent-context.md 或 agent-history.md 中写入诸如 browser automation is not required、browser URL is not used、all QA is backend/CLI 或 these cases are backend-test/cli/file-docs 等陈述。应将这些信息限定在分支对应的 qa-check.md 中，或改写为可复用的条件规则，例如 For backend-only QA cases, browser automation is not required; browser/UI cases still require Browser or Playwright MCP。

绝不要将这两个文件中的任何一个视为机密信息的来源。如果其中包含疑似密码、令牌、Cookie、授权标头、一次性验证码或其他机密信息，则执行时忽略该值，并在下次重写或追加文件时将其删去或遮盖。

步骤 0.2：解析参数并解析分支

解析 $ARGUMENTS：

  1. 检测模式：查找与 human 或 agent 匹配的第一个词，并从参数中移除。
  2. 检测分支：剩余文本（如有）即为分支标签。
  3. 如果未提供模式，则用 ui_language 询问要运行哪种模式：
    • 人工引导的 QA
    • 自动化 Agent QA

解析工作分支：

If git_enabled = false or the repository is not a git work tree:
  If branch was provided in arguments → use it as the resolved branch label
  Otherwise → set resolved_branch = "manual"
If git_enabled = true and the repository is a git work tree:
  If branch was provided in arguments → use it as the resolved branch
  Otherwise → run: git branch --show-current

存储：

  • resolved_branch
  • artifact_dir = <resolved paths.qa>/<branch-slug>
  • test_cases_path = <artifact_dir>/test-cases.md
  • qa_check_path = <artifact_dir>/qa-check.md
  • browser_replay_dir = <artifact_dir>/browser-replay

使用与 /aif-qa 完全相同的算法计算 branch-slug：

  1. 将所有不在 [A-Za-z0-9._-] 中的字符替换为 -，合并连续的 -，去除首尾的 -，如果结果为空则使用 branch。随后必须将 safe_slug 截断为前 40 个 ASCII 字符。由于规范化后的 safe_slug 字符集为 [A-Za-z0-9._-]，因此字节长度与字符长度相同。
  2. 运行 git hash-object --stdin <<< "<resolved_branch>"，并取前 8 个十六进制字符作为 hash8。
  3. 组合：branch-slug = "<safe_slug>-<hash8>"。
步骤 1：验证 QA 输入

检查 <artifact_dir>/test-cases.md 是否存在。 如果文件不存在，则停止，并用 ui_language 询问是否：

  1. 先运行 /aif-qa test-cases <resolved_branch>
  2. 取消

读取 test-cases.md。按 ID（TC-001、TC-002 等）、标题、优先级、类型、执行界面（如有）、前置条件、步骤、预期结果和测试数据提取测试用例。保留其顺序。

创建或修改 qa-check.md 前，先计算源绑定元数据：

  • source_digest — 使用 git hash-object --no-filters <test_cases_path>（若可用），或对文件的确切内容运行 git hash-object --stdin，计算完整 test-cases.md 内容的确定性摘要。
  • case_digests — 为每个提取出的 TC-NNN 计算确定性用例摘要，摘要基于该用例包含标题、优先级、类型、前置条件、步骤、预期结果和测试数据的规范块。
  • tested_revision — 当 git_enabled = true 且仓库是 git 工作树时，运行 git rev-parse HEAD 并记录解析出的提交 SHA。
  • worktree_digest — 当 git_enabled = true 且仓库是 git 工作树时，记录当前工作树状态的确定性摘要，以确保提交后本地改动不会使脏工作树的 QA 结果被复用。
  • manual_build_id — 当 git_enabled = false 或仓库不是 git 工作树时，在创建或恢复结果前，要求用户提供明确的构建／版本标识符。不得接受空标识符。
  • replay_script_digests — 对每个现有的规范 <browser_replay_dir>/TC-NNN.js，使用 git hash-object --no-filters <path>（若可用）或其他稳定的 SHA-1／SHA-256 摘要计算其确切文件内容的摘要。这样，即使 QA 管理的回放文件已从 worktree_digest 中排除，仍可将证据绑定到实际运行的自动化脚本。

按以下方式规范化每个用例摘要的输入：

  1. 提取原始 Markdown 块：从包含用例 TC-NNN 标识符的行开始，到下一个 TC-NNN 块之前或文件末尾结束。
  2. 将 CRLF 或 CR 换行符规范化为 LF。
  3. 删除每行末尾的空格和制表符。
  4. 删除提取块开头和结尾的空行。
  5. 保留原始字段顺序、项目符号标记、缩进、内部空行、Markdown 标点和其余所有空白。不要对字段排序、合并空白或改写项目符号。
  6. 在哈希前，为规范化后的块添加原始块边界：BEGIN TC-NNN\n<normalized block>\nEND TC-NNN\n。
  7. 使用 git hash-object --stdin（若可用），或在 git 不可用时使用其他稳定的 SHA-1／SHA-256 摘要，对添加边界后的块进行哈希。

当 git 已启用且存在 git 工作树时，严格按以下方式计算 worktree_digest：

  1. 获取 git status --porcelain=v1 --untracked-files=all 的输出。
  2. 获取 git diff --binary HEAD -- 的输出。
  3. 从状态、差异和未跟踪文件摘要输入中排除 qa_check_path 和 browser_replay_dir 下的所有文件，以免 QA 管理的结果／回放产物使自身结果过期。不要排除 test_cases_path；源文件变更也由 source_digest 跟踪。
  4. 对 porcelain 状态中剩余的每个未跟踪文件，追加 UNTRACKED <path> <content-digest>，其中 <content-digest> 为使用 git hash-object --no-filters <path>（若文件可读）计算的摘要。
  5. 将组合输入中的换行符规范化为 LF，并使用 git hash-object --stdin 对其进行哈希。
  6. 如果经过过滤的工作树输入为空，则记录规范字符串 clean\n 的摘要。

如果 mode = agent，则在创建或修改 qa-check.md 前执行步骤 1.1。此门控期间可只读检查现有的 qa-check.md。 如果 qa-check.md 存在，请读取它，并且只有在将已存储的绑定元数据与当前绑定元数据进行比较后，才从现有状态继续：

  • 如果 tested_revision 已更改，将所有先前结果标记为 Stale 并取消勾选，保留先前评论/证据作为历史上下文，并要求重新测试。不要将过期的通过/失败/阻塞状态计为当前状态。
  • 如果 worktree_digest 已更改，将所有先前结果标记为 Stale 并取消勾选，保留先前评论/证据作为历史上下文，并要求重新测试。不要将过期的通过/失败/阻塞状态计为当前状态。
  • 如果 manual_build_id 已更改，按 tested_revision 更改的情况处理。
  • 如果 source_digest 已更改，请比较 case_digests。仅当某个用例的摘要未更改，且其 tested_revision/manual_build_id 和 worktree_digest 均未更改时，才保留该用例的当前状态。
  • 如果现有用例的摘要已更改，将该用例标记为 Stale 并取消勾选，要求重新测试。
  • 如果出现新用例，将其添加为未勾选的 Pending。
  • 如果 test-cases.md 中不再包含某个先前用例，请保留其历史条目并标记为 Stale，或将其移至制品语言对应的“Stale / Removed Cases”部分；绝不要将其计为当前用例。
  • 除非用户明确选择重新测试该用例，否则不要覆盖先前的通过/失败评论。
  • 如果规范回放文件的实际内容摘要与该用例记录的 Script digest 不同，将该用例标记为 Stale，保留先前的回放元数据/证据，并要求对更改后的脚本进行证明运行。缺少旧版脚本摘要或目标指纹元数据意味着脚本未经证明，而非匹配。
  • 单独因修订版本、工作树或手动构建过期，并不会使浏览器回放脚本失效。只有当其嵌入的用例摘要、嵌入的目标指纹和实际脚本摘要分别与当前用例、已批准目标及先前记录的脚本摘要匹配时，该脚本才可继续复用。

如果 qa-check.md 不存在，请使用提取的测试用例和源绑定元数据，根据 templates/QA-CHECK.md 创建该文件。每个用例初始状态均为未勾选的 Pending。

步骤 1.1：Agent 模式能力与安全预检

Agent 模式仅供用户使用（disable-model-invocation: true），因为它可能执行实时浏览器操作、Shell 命令、本地服务调用及其他具有显著副作用的检查。 在 Agent 模式下执行任何测试用例或编写 qa-check.md 之前：

  1. 从当前运行时工具中检测可用的执行能力：
    • shell/CLI 命令执行
    • 可通过 shell 使用的项目测试运行器和构建工具
    • 通过应用内 Browser 或 Playwright MCP 进行实时浏览器自动化
    • 通过现有项目工具或安全的 shell 命令进行 HTTP/API 检查
    • 通过 Read/Grep/Glob 检查文件、文档和代码仓库
  2. 根据每个测试用例所需的证据类型进行分类：browser-ui、cli、backend-test、api、file-docs、database-read、hybrid、human 或 unknown。如果用例包含明确的 Execution surface: 字段，则采用该字段，除非用例文本明确与之矛盾；如有覆盖，须记录在 agent-history.md 中。
  3. 选择能够为该用例提供具体证据且侵入性最低的能力。对于浏览器/UI 可观察的用例，以及预期结果取决于网页渲染行为的混合用例，必须使用浏览器自动化。不得用 CLI 命令、单元测试、静态检查或后端检查代替浏览器/UI 用例；这些方式只能作为补充证据记录。
  4. 如果用例需要浏览器自动化，优先使用应用内 Browser 能力。如果应用内 Browser 不可用，则使用 Playwright MCP（如可用）。
    • 如果存在回放脚本，优先选择能够执行已保存的、兼容 Playwright 的 page 脚本的浏览器能力。
  5. 如果浏览器/UI 用例需要实时浏览器自动化，但应用内 Browser 和 Playwright MCP 均不可用，则仅将该用例保留为未勾选，将状态设为 Blocked，并用 ui_language 请用户启用实时浏览器能力，同时将此阻塞事项追加到 <paths.qa>/agent-history.md。继续处理可通过 CLI、测试、API 或文件/文档检查验证的其他用例。
  6. 使用 <paths.qa>/agent-context.md、<paths.qa>/agent-history.md、test-cases.md、change-summary.md、项目文档、当前浏览器状态和代码仓库脚本，确定目标 URL、服务启动命令、测试命令和环境。
  7. 对需要身份验证或特定用户状态的浏览器/UI 用例，在将用例标记为受阻前，先确定浏览器测试身份：
    • 首先在 agent-context.md、agent-history.md、测试数据、seeders/factories/fixtures、文档、安全读取的本地数据库以及现有测试用户中，查找匹配的非敏感测试身份。
    • 如果环境明确属于 local、test 或可丢弃的 development，且代码仓库工具提供了创建或填充合成测试用户/状态的安全方式，则创建该用例所需的最小可丢弃 fixture。将 fixture 标识符和设置命令/证据记录在 qa-check.md 中。
    • 如果创建 fixture 需要密码、角色、租户、工作区、功能标记、seed 命令，或其他设置决定不明确，请先询问用户，再将用例标记为受阻。询问用户是提供现有测试账户，还是授权创建可丢弃的 fixture。
    • 如果用户提供或授权使用 local 或 test 环境的可丢弃测试凭据，则在本次运行中使用这些凭据。只有用户明确表示这些凭据可重复用于测试且可以安全持久化时，才将其存入 agent-context.md。否则仅记录用户名/角色以及获取密钥的位置。
    • 切勿将生产凭据、个人凭据、Cookie、会话令牌、一次性验证码或共享密钥存入 agent-context.md 或 agent-history.md。
  8. 如果缺少可由用户提供的前置条件，请在将用例标记为受阻前先询问用户：
    • 应用 URL 或登录 URL
    • 测试账户角色或非敏感用户名
    • 如何获取凭据，且无需在文档中暴露凭据
    • 是否授权创建可丢弃的本地/测试浏览器 fixture，以及所需的初始状态
    • 必需的启动状态、种子数据、功能标记、租户、组织或工作区
    • 不明确的登录方式或身份验证提供方
    • 继续操作所需的稳定选择器、字段标识符或页面路由
    • 继续操作所需的准确项目命令、测试筛选条件、服务启动命令或安全 API 端点
  9. 只有当可复用的非敏感答复足够通用、能帮助未来的 QA 测试集时，才应立即将其保存到 <paths.qa>/agent-context.md。仅当答复包含可复用经验时，才将脱敏后的摘要追加到 <paths.qa>/agent-history.md；否则将其保留在当前分支的 qa-check.md 证据/注释中。
  10. 确定并显示目标环境，包括适用时的 URL 和推断出的环境类别：local、development、staging、test、production 或 unknown。对于浏览器目标：
  • 从已确定的目标 URL 派生 normalized_base_url：移除用户信息、查询参数和片段；保留 scheme、host、port 和部署基础路径；移除末尾斜杠，但源站根路径除外。
  • 使用可用时的 git hash-object --stdin，或其他稳定的 SHA-1/SHA-256 摘要，基于准确的规范输入 AIF TARGET\n<environment_class>\n<normalized_base_url>\n 计算 target_fingerprint。
  • 在 qa-check.md 中记录环境类别和 target_fingerprint。绝不得将针对其他目标指纹创建的回放视为匹配。
  1. 未在执行前立即获得用户明确授权时，不得对 production 或 unknown 目标执行浏览器操作、API 写入、有副作用的 CLI 命令、数据库写入、破坏性命令、支付、权限变更、电子邮件、通知、数据导出或其他外部副作用步骤。在 qa-check.md 中记录授权决定和目标类别。只有当记录能形成可复用的跨 QA 策略或反复适用的授权经验时，才将其追加到 agent-history.md；不得为未来运行持久化宽泛的生产环境授权。
  2. 检查每个用例和拟执行的命令是否存在破坏性、不可逆、支付、权限变更、电子邮件、通知、数据导出、数据库变更、服务重启、部署、文件系统删除或其他外部副作用风险。执行任何此类用例前，必须获得该用例的明确授权。
  3. 优先使用只读且仅针对测试范围的命令。除非用户明确授权具体操作，否则不得运行具有破坏性的 shell 命令，例如 rm、git reset、git checkout --、数据库重置、针对共享环境的迁移、部署命令，或会删除用户数据的清理命令。
  4. 如果授权被拒绝或不明确，则将用例保留为未勾选，将状态设为 Blocked，并在 qa-check.md 中写明阻塞原因，不得执行有风险的操作。只有当该决定构成可复用的跨 QA 经验时，才将其追加到 agent-history.md，不要仅为特定用例的拒绝记录历史。 对 Agent 评论／证据以及所有人工输入的评论／证据，必须进行脱敏处理：
  • 对凭据、Cookie、授权值、会话令牌、API 密钥、Bearer 令牌、Basic Auth 值、一次性验证码和个人秘密进行脱敏。
  • 对敏感 URL 参数进行脱敏，例如 token、access_token、refresh_token、id_token、code、secret、password、passwd、pwd、auth、key、api_key、session、sid 和 jwt。
  • 将脱敏后的值替换为 [REDACTED]，然后再将评论或证据写入 qa-check.md。
  • 不要将原始浏览器存储数据、Cookie、请求标头、授权标头或包含令牌的 URL 粘贴到文档中。
步骤 2：人工模式

每次恰好运行一个待处理或已选定的测试用例。

对于每个用例：

  1. 只显示该测试用例的标题、优先级、前置条件、步骤、测试数据和预期结果。
  2. 使用 ui_language 撰写简短的单用例摘要。
  3. 摘要中的提问必须表达：“测试此项并回答它是否有效。”当 ui_language = ru 时，必须使用以下原文：Протестируйте и ответьте работает или нет。
  4. 询问用户测试结果：
    • 有效／已完成
    • 无效／失败
    • 暂停
  5. 如果用户表示有效，则在 qa-check.md 中将该用例标记为已检查（[x]），将状态设为 Passed，并将当前模式设为 human。
  6. 如果用户表示失败，则保持复选框未选中（[ ]），将状态设为 Failed，询问失败原因，并将用户的说明写为评论；除必须对敏感值进行脱敏外，保留用户原话。
  7. 每完成一个用例就保存 qa-check.md，确保进度能在上下文重置后保留。

在当前用例有结果或用户暂停之前，不要显示下一个测试用例。

步骤 3：Agent 模式

Agent 模式必须提供具体且适合相应用例的证据。如果浏览器执行、CLI 输出、自动化测试输出、API 响应、后端命令结果、数据库安全读取结果或文件／文档检查能够直接覆盖用例步骤和预期结果，任一项都足以将该用例标记为通过。

内部确定性不变量必须作为自动化检查处理，而非人工 QA。涉及服务方法调用、缓存状态、物化行、精确数组、原始数据库值、公式输出、CLI 内部行为或类似非人工可观察行为的用例，应根据情况归类为 backend-test、cli、api 或 database-read。首先查找是否已有覆盖该不变量的测试或命令。如果找到现有测试且测试通过，则将对应的 TC-* 用例标记为 Passed，并将测试类／名称、命令／筛选条件、退出状态和断言／结果摘要作为证据。如果一次测试运行覆盖多个 TC-* 用例，则在每个被覆盖的用例中复用该证据，并可选择在“Supporting Automated Checks”下总结该次共享运行。如果没有合适的自动化覆盖，则将用例保持为 Blocked，并注明类似 Missing automated test coverage for backend invariant 的阻塞原因；不要要求用户手动验证内部数组或原始数据库值。

确定测试目标：

  • 如果 agent-context.md、agent-history.md、test-cases.md、change-summary.md、项目文档或当前浏览器状态明确指出 URL，则使用该 URL。
  • 如果仓库脚本、测试文件、包清单、Makefile、框架命令或文档明确指出适用于 CLI／后端／API／文档用例的安全命令或测试筛选条件，则使用该命令或筛选条件。
  • 如果未明确 URL、命令、启动状态、凭据位置、测试筛选条件或所需夹具，则向用户询问缺失信息，然后仅将可复用的非敏感事实保存到 agent-context.md。
  • 不要编造凭据、URL、命令、夹具或环境假设。
  • 使用步骤 1.1 中收集的目标环境和授权。如果导航重定向到不同主机或更敏感的环境，请重新确认。
浏览器回放约定

对于每个 browser-ui 用例，以及每个包含浏览器步骤的 hybrid 用例：

  1. 使用 <browser_replay_dir>/TC-NNN.js 作为规范回放工件。每个文件只放一个用例，以便失败的用例可以单独重跑。
  2. 编写最精简的 Playwright 兼容 async (page) => { ... } 表达式。这是 browser run-code 功能接受的格式。不要添加导入、测试框架、fixture、生成的包装代码或项目依赖。包含导航、稳定的选择器、输入/操作，以及不匹配时会抛出异常的显式断言。
  3. 每个规范脚本必须严格以以下元数据行开头，后接异步表达式：
    • // aif-case-digest: <case_digest>
    • // aif-target-fingerprint: <target_fingerprint> 导航时使用带引号的占位符 "AIF_BASE_URL"，不要持久化绝对目标 URL。执行前立即在内存中将带引号的占位符替换为经过正确 JSON 编码的 normalized_base_url；不要修改已保存的文件。切勿将密码、令牌、Cookie、授权值、一次性验证码、个人机密或包含令牌的 URL 写入脚本。复用已认证的浏览器会话，或通过获授权的运行时机制获取机密信息。
  4. 只有以下三项绑定全部一致时，回放才属于 matching：内嵌的 case_digest、内嵌的 target_fingerprint，以及实际的 script_digest 与 qa-check.md 中记录的最新证明一致。每次回放前都要核验这三项。目标不匹配时，必须停止执行，直到当前显示且获授权的目标经过核验，并明确重新绑定脚本；重新绑定会改变脚本摘要，因此需要重新运行并取得新证明。
  5. 只要用例在机制上足够明确，就应在首次执行前创建缺失或过期的脚本。计算其 script_digest，执行一次，并将首次执行用作证明运行；不要自动再次执行新脚本或更新后的脚本。
    • 如果需要通过交互式浏览器操作来明确机制，且已保存的脚本在观察到的运行之后发生更改，则将新脚本标记为 Unproven。不要立即重新运行。
    • 未证明或已更改的脚本，只有在明确恢复或核验其声明的前置条件后才能运行。如果用例可能创建、提交、发送、删除、修改权限/设置，或导致其他外部副作用，则必须获取针对该用例的新授权，并明确说明这是重复执行。清理/重置操作同样受这些安全规则和授权要求约束。
    • 只有在该精确文件内容已经执行后，才能将 Script digest 记录为当前证据绑定。对于未证明的文件，将 Script digest 保持为 n/a，设置 Proof status: Unproven，并在注释/证据中记录计算出的候选摘要，直至完成证明运行。
  6. 在为修复、重新绑定或澄清机制而修改任何现有规范脚本之前，先计算其旧脚本摘要，并将原文件逐字保存在 <browser_replay_dir>/history/TC-NNN-<old_script_digest>.js。在 qa-check.md 中记录存档路径、旧摘要和初始错误。切勿自动执行历史文件。
  7. 对回放失败进行分类，不要掩盖产品回归问题：
    • 语法错误或浏览器运行器失败 → 自动化缺陷；存档、修复、重新计算 script_digest，并根据上述前置条件/副作用规则要求重新运行以取得新证明。
    • 缺少选择器 → 首先保留原始脚本及初始浏览器错误/状态。只有在具体浏览器证据证明同一语义元素和预期行为仍然存在、仅选择器机制发生变化时，才能修复定位器。记录该证明。否则将用例标记为 Failed；绝不要选择仅仅相似的元素，也不要绕过缺失步骤。
    • 脚本执行到断言，但观察到的行为与断言不符 → 将用例标记为 Failed；这是回归/修复证据，不是重新生成脚本的理由。
  8. 在修订、工作树或手动构建发生更改后进行的任何一次运行中，都要回放所有当前匹配的浏览器脚本，包括之前通过和失败的用例。每次回放仍须进行能力/安全预检，并取得针对每个用例的副作用授权。在安全且受支持的情况下，将无状态脚本放在同一浏览器会话或批次中执行，以减少准备工作和工具调用。
  9. 在 qa-check.md 的用例 Browser replay 和 Evidence 字段中记录规范路径、用例摘要、脚本摘要、目标指纹、证明状态、执行能力和结果。Proven 表示已执行该精确脚本内容；这并不意味着产品结果通过。
  10. 如果可用的应用内 Browser 仅支持离散操作，则将已保存脚本作为精确的操作/断言程序，并通过这些操作回放。如果 Playwright MCP 能直接执行文件正文，则优先直接执行。不要仅因执行界面改变就重新生成已知步骤。
  11. 将回放视为回归基线，而不是唯一的浏览器检查。回放后，根据具体的变更风险，判断是否有理由进行一次范围受限的探索：
  • 如果变更影响共享 UI、布局、导航、身份验证、权限、状态转换或其他跨流程行为；如果缺陷成因或修复效果仍不确定；如果匹配回放因应用行为变化而需要修复；或者回放暴露了意外的相邻行为，则运行探索。
  • 如果修复范围狭窄且独立，匹配回放直接覆盖了变更行为，不影响其他相邻高风险路径，且回放通过，则跳过探索。
  • 运行探索时，仅检查直接受影响的相邻路由、状态或边界输入。不要开始无范围限制的浏览，也不要重新生成可正常工作的回放步骤。
  • 在 qa-check.md 中记录 Browser exploration: Ran 或 Browser exploration: Skipped、原因、范围及简明的脱敏发现。
  • 新发现不会自动成为源测试用例。在 qa-check.md 中记录该发现，并建议通过 /aif-qa test-cases 添加；只有在获得 TC-NNN 用例编号后，才为其创建回放脚本。 对于每个待处理或已选定的用例：
  1. 根据用例分类选择执行方式：
    • browser-ui：先执行匹配的已保存浏览器回放；仅当回放缺失，或与用例、目标或脚本摘要不匹配时，才创建或验证回放；然后通过 Browser 或 Playwright MCP 导航并执行 UI 步骤。
    • cli：运行相关项目命令并检查退出代码和输出。
    • backend-test：优先查找并运行范围最窄的现有相关测试命令或测试筛选器；仅在需要提高可信度时扩大范围。通过自动化测试覆盖可作为该用例的通过证据。
    • api：根据具体情况，通过现有项目工具、安全的本地命令或浏览器／网络能力调用端点。
    • file-docs：使用 Read/Grep/Glob 检查生成的文件、文档、配置或仓库内容，并在有帮助时运行项目验证命令。
    • database-read：仅执行安全的只读检查，除非用户明确授权在测试范围内的环境中进行修改。
    • hybrid：结合所需的执行方式，并记录每种证据类型。
  2. 按照原样执行测试步骤，仅在所选执行方式的操作细节显而易见时进行调整。
  3. 如果执行因缺少凭据、缺少浏览器夹具、服务不可用、设置不明确、导航受阻、缺少选择器信息、字段映射含糊、路由未知、命令未知、缺少夹具或测试筛选器不明确而停滞，先搜索 agent-context.md 和 agent-history.md。对于浏览器／UI 身份验证或用户状态缺失的问题，在阻塞前，按照步骤 1.1 中的说明尝试安全地发现或创建本地／测试夹具。如果其中没有现成答案或夹具，必须准确询问用户所缺的信息或授权，然后才能将用例标记为阻塞。
  4. 如果用户提供了可用的非敏感信息，在同一轮中继续执行用例。将可长期复用的跨 QA 事实更新到 agent-context.md；只有当已解决的阻碍可能在未来的 QA 集中再次出现时，才将其追加到 agent-history.md。具体用例详情保留在 qa-check.md 中。
  5. 如果用户无法提供缺失信息、服务仍不可用、授权被拒绝、所需能力不可用，或副作用风险仍未解决，则保持复选框未勾选（[ ]），将状态设为 Blocked，并写明阻碍。
  6. 将观察到的结果与预期结果进行比较。
  7. 如果观察结果符合预期，将用例标记为已勾选（[x]），将状态设为 Passed，并添加简洁的脱敏证据。证据可以是浏览器观察结果、命令及其退出状态、测试名称和结果、API 响应摘要、文件路径及匹配条件，或其他具体观察结果。
  8. 如果观察结果与预期不符，保持复选框未勾选（[ ]），将状态设为 Failed，并填写具体的脱敏问题说明，指出观察结果与预期结果的差异。
  9. 每完成一个用例后保存 qa-check.md。

在最终摘要之前，将每轮运行的详细证据写入 qa-check.md，而非根目录级记忆。这包括当前分支／QA 目标、执行的命令、退出代码、断言数量、支持性文件检查、用例映射、摘要计数以及一次性阻碍。

写入 qa-check.md 后，仅提取可复用的跨 QA 经验：

  • 当发现的事实具有长期价值且可能对未来的 QA 集有用时，更新 <paths.qa>/agent-context.md。
  • 仅当阻碍、选择器、命令模式、测试筛选惯例、API 端点模式、路由、设置说明或授权决定可能在当前 QA 集之外再次出现时，才追加到 <paths.qa>/agent-history.md。
  • 如果运行成功且没有产生新的可复用经验，则可以不向 agent-history.md 追加内容。
  • 绝不要向 agent-history.md 追加完整运行记录、分支／QA 目标、单轮摘要计数、确切断言总数或当前 QA 计划标签。 保持 <paths.qa>/agent-context.md 简洁且内容为最新；优先记录稳定事实，而非一次性观察结果。不要写入明文密码、令牌、Cookie、授权标头、一次性验证码、私人个人数据、包含令牌的 URL、分支名称、QA 目标路径或运行摘要。

当当前运行环境支持时，使用屏幕截图或浏览器状态观察结果，但不要将屏幕截图设为通过测试的必要条件。

第 4 步：最终摘要

停止或完成后，使用 ui_language 报告：

  • 测试用例总数
  • 通过数
  • 失败数
  • 受阻数
  • 待处理数
  • qa-check.md 的路径
  • 创建或执行了浏览器脚本时，browser-replay/ 的路径
  • 运行了 Agent 模式或请求了缺失的执行上下文时，agent-context.md 和 agent-history.md 的路径
  • 下一步建议

如果 mode = agent 且有一个或多个当前用例处于 Blocked 状态，请在结束前将其分为人工可验证的受阻用例和仅自动化的受阻用例。

  • 仅当受阻用例的执行界面为 human、browser-ui、包含人工可观察步骤的 hybrid，或 unknown 时，才提供人工引导继续执行的选项。
  • 对于因缺少自动化覆盖、缺少命令或测试筛选器、服务不可用，或其他技术性自动化前提条件而受阻的 backend-test、cli、api、file-docs 或 database-read 用例，不要提供人工引导继续执行的选项。对于这些用例，应建议添加或运行相应的自动化检查，或提供缺少的命令、测试夹具或上下文。
  • 如果至少有一个人工可验证的受阻用例，请使用 ui_language 询问用户是否要现在以人工引导模式运行这些符合条件的受阻用例。
  • 如果用户同意，请在同一次调用中按照第 2 步继续，但只处理符合条件的受阻用例。保留现有 Agent 阻塞说明作为上下文，并在同一个用例下追加人工执行结果或说明。
  • 如果用户拒绝或停止，请保持这些用例未勾选并标记为 Blocked。
  • 将交接决定和任何已解决的受阻用例写入 qa-check.md。只有当交接揭示了可复用的跨 QA 经验时，才追加到 agent-history.md。

如果有任何用例失败，下一步建议应为修复问题并重新运行 /aif-qa-check <mode> <resolved_branch>。

如果 Agent 模式运行后仍有人工可验证的受阻用例，且用户未以人工模式继续执行，下一步建议应为针对这些用例运行 /aif-qa-check human <resolved_branch>，或提供缺失的执行上下文。如果仍有仅自动化的受阻用例，则应建议添加或运行所需的自动化测试、命令、测试夹具、服务或上下文。除非有具体观察证据，否则不要暗示受阻用例属于产品缺陷。

产物归属与配置策略

  • 主要归属：<paths.qa>/<branch-slug>/qa-check.md、规范路径 <paths.qa>/<branch-slug>/browser-replay/TC-NNN.js、保留的 <paths.qa>/<branch-slug>/browser-replay/history/*.js、<paths.qa>/agent-context.md 和 <paths.qa>/agent-history.md。
  • 读取策略：可将 <paths.qa>/<branch-slug>/change-summary.md、test-plan.md、test-cases.md、<paths.qa>/agent-context.md 和 <paths.qa>/agent-history.md 作为 QA 上下文读取。
  • 写入策略：持久化写入仅限 qa-check.md、分支专属的 browser-replay/TC-NNN.js 和 browser-replay/history/*.js、agent-context.md 以及 agent-history.md；不得重写 test-cases.md、test-plan.md、change-summary.md 或 config.yaml。
  • 配置策略：了解配置，只读。读取 paths.description、paths.architecture、paths.qa、language.ui、language.artifacts、language.technical_terms 和 git.enabled；绝不写入 config.yaml。

关键规则

  1. 如果没有 test-cases.md，则不得运行。
  2. 在人工模式下，每次只能展示一个用例。
  3. 在人工模式下，必须询问用户该用例是否有效。
  4. 写入前，除必须对敏感值进行脱敏外，必须保留用户失败评论的原文措辞。
  5. 在 Agent 模式下，如果没有针对该用例的适当执行界面提供的具体证据，则不得将用例标记为通过。
  6. 不得仅因无法进行实时浏览器自动化，就阻止非浏览器用例。
  7. 必须将确定性的内部／后端／CLI／API／数据库不变量用例归类为自动化检查；不得以人工 QA 替代缺失的自动化覆盖。
  8. 必须将当前结果绑定到（tested_revision 和 worktree_digest）或 manual_build_id，以及 source_digest 和 case_digests。
  9. 如果受测版本、工作区摘要、手动构建 ID、完整源代码摘要或单个用例摘要发生变化，必须将结果标记为过期。
  10. 对生产环境／未知目标以及具有破坏性或外部副作用的用例，必须要求明确授权。
  11. 写入评论或证据前，必须对凭据、Cookie、授权值、令牌和敏感 URL 参数进行脱敏。
  12. 每完成一个用例后，必须保存进度。
  13. 在自动执行之前，以及向用户询问设置相关信息之前，必须读取 agent-context.md 和 agent-history.md，以便复用先前的答案。
  14. 如果因缺少 URL、凭据、登录路由、字段标识符、设置状态、选择器、命令、测试筛选器、测试夹具或类似可恢复信息而要阻止 Agent 模式下的用例，必须先向用户询问缺失的、可由用户提供的执行上下文。
  15. 如果缺少登录凭据或用户状态，不得阻止浏览器／UI 用例，除非已搜索可复用的上下文、现有测试夹具、种子数据生成器／工厂、文档和安全的本地／测试数据；在环境为本地／测试且工具可用时，已尝试安全地创建一次性测试夹具；或者已询问用户是否可以提供凭据、设置测试夹具或授权创建一次性测试夹具。
  16. 只有在获得用户明确许可后，才可将可复用的仅用于测试的凭据保存到 agent-context.md；绝不得保存生产凭据、个人凭据、Cookie、会话令牌、一次性验证码或共享密钥。
  17. 只能将可复用的非敏感跨 QA 答案和发现的稳定执行事实写入 agent-context.md；只有发现了可反复复用的经验或阻塞模式时，才可向 agent-history.md 追加内容。
  18. 如果当前存在任何可由人工验证的 Blocked 用例，在结束 Agent 运行前，必须询问用户是否要在人工模式下继续处理符合条件的阻塞用例。
  19. 必须将浏览器／UI 自动化保存为绑定到用例、目标和内容的 browser-replay/TC-NNN.js 脚本，并在生成新的浏览器操作前执行匹配的脚本。
  20. 修订版本、工作区或手动构建发生变化后，必须重新回放先前已通过的浏览器用例所对应的脚本，以检查回归。
  21. 不得仅为了回放工件而添加浏览器测试依赖项或运行器。
  22. 回放后，必须根据证据做出并记录浏览器探索决策；回放只是基准，当存在具体的变更风险信号时，不能替代有界探索。
  23. 不得自动将新建或更新的回放脚本执行两次；只有在恢复／验证了前置条件，并重新获得外部副作用所需的授权后，才可重复执行。
  24. 必须将找不到选择器视为可能的产品回归，除非具体证据证明仅是定位器机制发生变化；修复前必须保留原始脚本和错误。
  25. 回放前必须验证 case_digest、target_fingerprint 和 script_digest；脚本发生任何更改或目标重新绑定后，都必须执行一次验证运行。

评论

支持 Markdown