qa-automation

QA 自动化

使用此技能，通过受治理的变更集工作流创建或更新自动化脚本。将 automation_change_set.json 视为范围、映射、计划变更、已应用变更、验证、审核关卡、晋级就绪状态、Notion 同步、Plane 同步、桥接同步、差距和下游状态更新的唯一事实来源。

核心规则

仅执行自动化工作。不要根据原始需求创建测试用例、作为执行者开展手动 QA、编写最终 QA 报告、提交问题、臆造选择器／端点／凭据／测试数据、自动为差距创建后续事项，也不要在未经用户明确请求和批准的情况下推送或合并远程分支。

仅在请求和写入策略明确时创建／更新 Notion 或 Plane 对象。只有在用户阅读目标并了解影响后明确批准，才能删除／归档 Notion 或 Plane 对象。

输入

接受六种输入路径。

规划器约定：

• 加载 create_scripts、update_scripts、manual_only、自动化状态、优先级筛选条件、自动化差距、已批准的测试用例和预期结果。
• 将 To Be Automate 映射为脚本创建。
• 将 Already Automate 映射为脚本更新或验证。
• 除非有人明确更改状态，否则跳过 Manual Only。

执行器信号：

• 加载自动化相关失败用例、技术性不稳定失败、选择器差距、API 差距、数据差距和更新候选项。
• 仅在根因明确时改进等待、断言、隔离或定位器。
• 不要弱化断言，也不要为了让测试通过而更改测试来掩盖业务失败。

手动请求：

• 接受测试用例文本／表格、脚本更新请求、仓库路径、现有脚本路径、框架说明、分支策略或验证命令。
• 如果仓库存在，请遵循仓库的框架、风格、包管理器、文件夹命名、夹具和辅助工具模式。
• 如果仓库／框架不存在，则回退使用 Playwright TypeScript。
• 如果缺少必要信息，请询问，或在 automation_change_set.json 中记录差距。

Notion 输入：

• 接受 Notion 页面 URL、数据库／数据源 URL、页面 ID、数据库 ID、数据源 ID、评论或 MCP 负载。
• 将 Notion 视为来源和同步状态界面，而非唯一事实来源。
• 如果存在 Notion 信号，请先阅读 references/notion-mcp.md 再继续。
• 为每个来自 Notion 的测试用例保留来源定位信息。
• 创建／更新脚本后，将 Automation Status 更新为 Automation Implemented。
• 只有在脚本审核结果为 OK 且相关验证结果为 passed 后，才将 Automation Status 更新为 Already Automate。

Plane 输入：

• 接受可读的 Plane ID（例如 DKI-179）、Plane URL、UUID、工作项／卡片／子工作项、评论、页面／Wiki 或 MCP 负载。
• 将 Plane 视为工作流界面和同步摘要界面，而非唯一事实来源。
• 如果存在 Plane 信号，请先阅读 references/plane-mcp.md 再继续。
• 状态变更前读取可用的项目状态。仅使用动态的用户／包映射；不要臆造状态。

Notion + Plane 桥接：

• 当同时提供这两个系统，或 Plane 内容中包含 Notion 链接时启用。
• 如果存在桥接信号，请先阅读 references/notion-plane-bridge.md 再继续。
• 除非用户另有说明，否则使用 Notion 作为测试用例／状态来源，Plane 作为工作流摘要。

工作流

1. 检查输入和仓库上下文。
2. 如果有可用的验证工具，使用 schemas/automation-change-set.schema.json 创建或更新 automation_change_set.json。
3. 如果 Notion 和 Plane 来源引用处于启用状态，则解析这些引用；如果工具缺失或失败，则记录读取缺口。
4. 在执行任何写入前，确认 Notion 和 Plane 的写入策略。
5. 检测框架、包管理器、测试命令、测试 ID 约定、分支策略和现有脚本风格。
6. 在编辑前规划每项文件变更，并将每项变更映射到 TC ID 或已批准的手动请求。
7. 仅在必要时生成或更新脚本、Page Object、fixture、辅助工具、配置或测试数据。
8. 执行可用的轻量验证：格式检查、lint、类型检查、配置验证。
9. 仅在环境、凭证来源和数据均已就绪时运行定向自动化。
10. 仅在用户明确要求或发布策略要求时运行完整自动化套件。
11. 如果策略允许，在创建或更新脚本后将 Notion 状态同步为 Automation Implemented。
12. 生成脚本审查材料包；如有要求，则等待人工给出 OK/NOK。
13. 仅在脚本审查结果为 OK 且验证结果为 passed 后，将 Notion 状态同步为 Already Automate。
14. 仅在策略允许时同步 Plane 终结评论、描述摘要、链接、工作日志、页面／wiki 或状态。
15. 生成晋级检查清单，并在执行任何远程推送、部署或合并前要求明确批准。

变更集

使用 automation_change_set.json 作为规范状态文件。包含：

• repo_context：仓库路径、包管理器、测试命令、分支信息、检测到的约定。
• framework：检测到的框架，或回退使用 Playwright TypeScript。
• branch_policy：仓库策略，或回退为 develop -> master。
• automation_scope：创建、更新、仅手动处理、跳过或仅验证的工作。
• test_case_mappings：TC ID 到脚本路径、规格标题、断言、选择器和状态的映射。
• planned_changes：编辑前计划执行的文件操作。
• applied_changes：编辑后实际执行的文件操作。
• validation_results：lint、类型检查、格式检查、配置验证、定向运行、完整运行。
• review_gates：脚本审查和晋级审查及其 OK/NOK 状态。
• promotion_status：推送、部署或合并的就绪状态。
• notion_context、notion_write_policy、notion_sync：Notion 来源引用、写入规则和同步记录。
• plane_context、plane_write_policy、plane_state_mapping、plane_sync：Plane 来源引用、动态状态处理、写入规则和同步记录。
• notion_plane_bridge：发现的引用、交叉链接、幂等键和部分同步状态。
• crud_operations：Notion 和 Plane 的读取／创建／更新／删除／归档／评论／链接／状态变更审计。
• gaps：选择器、数据、环境、fixture、API、仓库或框架缺口。
• changelog：带日期的变更集事件。

允许的操作包括 create_script、update_script、skip_manual_only、mark_gap、refactor_approved、validation_only、sync_notion、sync_plane 和 bridge_notion_plane。

脚本规则

• 优先遵循现有框架，然后才使用回退方案。
• 仅对新建自动化或无框架项目回退使用 Playwright TypeScript。
• 在规格标题、注解、注释或元数据中注明 TC ID。
• 根据预期结果推导断言。
• 切勿写入真实密钥、令牌、密码、Cookie 或 PII。
• 使用 fixture／配置存放测试数据，并使用 .env.example 存放环境变量名称。
• 对重复的 UI 流程使用 Page Object Model。
• 如果仓库已使用共享的身份验证／会话 fixture，则优先复用。
• 在相关时验证 API 状态、负载、标头和错误正文。
• 仅在连接和查询安全且已提供时进行 DB 验证。
• 除非无法避免，否则避免使用 waitForTimeout()；如需使用，应在变更集中记录原因。
• 确保测试具有确定性、相互隔离，并考虑清理。
• 除非必须或已明确批准，否则尽量减少重构。

定位器策略

默认优先级：

1. 使用带有可访问名称的 getByRole()。
2. 对表单输入使用 getByLabel()。
3. 仅当没有标签且占位符稳定时，使用 getByPlaceholder()。
4. 仅当文本唯一且稳定时，使用 getByText()。
5. 按照仓库的测试 ID 配置使用 getByTestId()。
6. 仅当语义定位器不可用时，使用稳定的 CSS id/class。
7. 仅在最后手段时使用 XPath，并说明原因。

不要使用生成的类哈希、过深的 CSS 链、不稳定的 id、易变文本或盲目使用的 .nth() 选择器。缺少稳定选择器时，记录 selector_gap 并建议改进可测试性。

审核关卡

脚本审核：

• 人工审核脚本、补丁摘要、固件、定位器、断言和验证。
• 状态为 OK 或 NOK。
• 状态为 NOK 时，须先修改变更集和脚本，再进行晋级。

晋级审核：

• 要求脚本审核通过（OK）、验证状态已知、差距已记录、分支策略已知，并且已记录远程操作的审批状态。
• 远程推送、部署或合并均须获得用户明确批准，即使就绪状态为 ready_to_push、ready_to_deploy 或 ready_to_merge。

晋级状态：draft、script_review_required、revision_required、validation_required、promotion_review_required、ready_to_push、ready_to_deploy、ready_to_merge、promoted、blocked。

Notion 托管同步

仅当 Notion 输入/输出处于活动状态时使用 Notion。先阅读 references/notion-mcp.md。

默认写入策略：

• 已识别出可写入的测试用例来源时，启用来源状态更新
• 在支持或有要求时，启用简短评论同步
• 除非有要求，否则禁用自动化页面和结果数据库同步
• 除非有要求或策略允许，否则禁用架构更新
• 删除/归档始终需要明确批准

状态规则：

• Manual Only：保持不变，除非人工更改
• To Be Automate：源用例需要自动化
• Automation Implemented：脚本已创建或更新，但脚本审核通过（OK）和验证通过尚未全部完成
• Already Automate：脚本审核为 OK，且相关验证已通过

如果缺少 Notion 属性，且架构更新已禁用或不可用，则记录 notion_schema_gap；在可能的情况下，使用评论或 Notes 作为备用方式。使用同步记录和托管标记，避免重复创建评论、页面或行。

Plane 托管同步

仅当 Plane 输入/输出处于活动状态时使用 Plane。先阅读 references/plane-mcp.md。

默认写入策略：

• Plane 上下文处于活动状态时，启用最终评论同步
• 有要求或发现现有托管区块时，启用描述同步
• 除非提供了动态映射或有要求，否则禁用状态同步
• 除非有要求，否则禁用工时记录和页面/wiki 同步
• 工具支持时，启用脚本、变更集、验证、审核和 Notion 引用的链接同步
• 禁用后续事项创建
• 删除/归档始终需要明确批准

状态策略：

• 状态变更前先读取项目状态
• 仅使用明确的用户/软件包/工作项映射
• 缺少映射时，跳过状态变更并记录 plane_state_mapping_gap
• 缺少目标状态时，跳过并记录状态转换差距

Plane 评论和描述摘要应简洁。Notion 中有详细输出时，Plane 只需包含摘要和链接。

Notion + Plane 桥接

两个系统都处于活动状态或 Plane 内容包含 Notion 链接时，阅读 references/notion-plane-bridge.md。

规则：

• automation_change_set.json 仍为规范来源
• 存在高置信度来源时，Notion 是测试用例/状态来源
• Plane 是工作流界面
• 存在多个 Notion 引用或角色不明确时，询问用户
• 策略允许时，交叉链接 Notion 和 Plane
• 将桥接状态记录为 synced、partial、failed 或 skipped
• 远程同步不完整不会使本地自动化输出失效

输出

规范输出：

• automation_change_set.json

面向人工的输出：

• automation-review.md
• validation-report.md
• patch-summary.md
• promotion-checklist.md

下游输出：

• automation_status_update
• qa_executor_validation_request
• qa_reporter_automation_summary

状态更新规则：

• 创建/更新脚本 -> 可设为 Automation Implemented
• 脚本审核通过且验证通过 -> 可设为 Already Automate
• 已创建脚本但尚未运行验证 -> 保持或设为 Automation Implemented，标记 script_created_unvalidated
• 因存在缺口而受阻 -> 保持 To Be Automate，记录缺口
• 除非人工更改自动化状态，否则 Manual Only 保持不变

质量门禁

提交可供审核的输出前：

• 每项计划/已应用的更改都对应一个 TC ID 或已批准的人工请求
• 每条断言都对应一个预期结果
• 选择器符合定位器策略，或已记录缺口
• 不写入机密或 PII
• 写入前已解决 Notion/Plane 写入策略
• Notion 状态使用 Manual Only、To Be Automate、Automation Implemented 或 Already Automate
• 只有在脚本审核结果为 OK 且验证结果为 passed 后，才能使用 Already Automate
• 移动状态前先读取 Plane 状态；未找到映射时跳过状态移动
• 执行具有破坏性的 Notion/Plane 操作前，必须明确获得删除/归档批准
• 对尝试执行的 Notion/Plane 写入都存在同步记录
• 将部分同步/同步失败记录为缺口
• 缺口不会自动创建后续事项

资源

仅在需要时读取：

• schemas/automation-change-set.schema.json：规范变更集架构。
• schemas/automation-review.schema.json：脚本和推广审核反馈架构。
• schemas/validation-result.schema.json：验证命令结果架构。
• schemas/automation-status-update.schema.json：下游自动化状态架构。
• schemas/notion-sync-record.schema.json：Notion 写入幂等性和同步结果架构。
• schemas/plane-sync-record.schema.json：Plane 写入幂等性和同步结果架构。
• templates/：可复用的审核、验证、补丁、推广和变更集模板。
• references/playwright-typescript.md：备用项目结构和命令模式。
• references/locator-policy.md：选择器优先级和防脆弱规则。
• references/branch-policy.md：分支和远程操作策略。
• references/notion-mcp.md：Notion MCP 读取/写入/删除策略、状态更新、幂等性、回退和脱敏。
• references/plane-mcp.md：Plane MCP 读取/写入/删除策略、动态状态映射、托管评论、描述、链接、工时记录、页面/知识库、回退和脱敏。
• references/notion-plane-bridge.md：发现、分类、交叉链接、重复项策略、部分同步和安全性。
• examples/：规划器契约、执行器信号、变更集和审核示例。