ui-failure-diagnoser

name ui-failure-diagnoser description WEB UI 自动化测试（Playwright + Pytest + POM）失败用例智能诊断与全栈自动修复专家。分析 ui-test-executor 输出的执行结果（JUnit XML + sidecar JSON + page-source HTML + console-logs + trace.zip），对失败用例做 6 类分类（ENV/LOCATOR/TIMEOUT/DATA/SCRIPT/BUG）+ 14 种根因定位，自动修复 pages 层 locator 问题、注入 conftest marker、清理测试脏数据、调起 playwright install，并通过 pages.yaml 对比修复定位漂移。**核心约束：永不修改 tests/**/*.py 断言与语义**。 agent_created true ui-failure-diagnoser — WEB UI 测试失败诊断与全栈自动修复 技能定位 唯一要做的事： 把失败用例转成可执行的修复动作。 覆盖范围（按失败类别）： 类别 子因数 自动修复策略 TIMEOUT_ERROR 2 AST rewrite（调 timeout / 加 wait_for_load_state） LOCATOR_ERROR 3 AST rewrite（iframe）+ Claude 语义推断（locator drift / shadow DOM）+ pages.yaml 金标准对比 ENV_ERROR 4 自动执行 shell（playwright install / pip install / lsof）+ 审计日志 DATA_ERROR 2 调兄弟技能 api-testdata-cleaner / 提示 seed BUG 1 注入 xfail/flaky marker 到 conftest.py（不改断言语义） SCRIPT_ERROR 3 AST rewrite（method typo / deprecated API / async list wait） 硬约束（永不违反）： 🚫 不改 tests/**/*.py 的断言与业务语义 🟢 可以改 pages/**/*.py （locator / timeout / iframe） 🟢 可以改 tests/conftest.py （只加 marker hook，不改 fixture / 不改 setup 语义） 🟢 可以跑 shell（playwright install / pip install / lsof）—— 所有副作用操作都走 AuditLogger 与上下游 Skill 边界： Skill 输入 输出 ui-test-executor 标签化脚本 + 执行意图 JUnit XML + artifacts + sidecar JSON ui-failure-diagnoser JUnit XML + sidecar + page-source + console-log ui_repair_report.md + .bak + audit.log + 修改后的 pages/conftest api-testdata-cleaner 脏数据清理请求 清理报告（被本技能 sibling-skill 方式调起） 触发场景 应当触发： "诊断 UI 测试失败"、"分析失败用例根因"、"为什么挂了" "修一下这个 locator"、"元素找不到了"、"测试又挂了" "自动修复 UI 测试"、"auto fix failing UI tests" "page error 怎么处理"、"console 有 5xx" "fixture 找不到了"、"user 已被消费" "playwright 浏览器没装"、"包没装" 不应当触发： 跑 UI 测试 → ui-test-executor 写新测试脚本 → ui-testscript-generator 通用调试方法论 → systematic-debugging 视觉回归分析 → ui-visual-assert 工作流程 Step 1：定位 Python 解释器 + 确认输入 优先级： 项目虚拟环境（ <project>/.venv/bin/python / <project>/venv/bin/python ） 全局 python3 （含 macOS Homebrew /usr/local/bin/python3 ） 必需输入 ： --junit-xml ：JUnit XML 路径 --artifacts-dir ：artifacts 根目录 --project-dir ：项目根（含 pages/ ） 可选输入 ： --conftest ：项目 tests/conftest.py （bug_repair 注入 marker 需要，默认 <project>/tests/conftest.py ） --pages-yaml ：项目 pages.yaml（LOCATOR_ERROR 时作金标准对比，可选） --audit-log ：审计日志路径（默认 <project>/.ui-failure-diagnoser/audit.log ） Step 2：加载失败数据 从 test-results/ 加载： report.xml ：JUnit XML，提取每个失败用例的 nodeid / message / traceback artifacts/page-source/<nodeid>.html ：失败时的 DOM 快照（LOCATOR vs TIMEOUT 的关键证据） artifacts/console-logs/<nodeid>.log ：5 段合并日志（Page Errors / Console / Network）— BUG 金标准 artifacts/pytest-raw/<slug>/trace.zip ：失败 trace（人工排查时用） Step 3：失败类型分类（6 类） 类型 判定信号 处理 ENV_ERROR Browser closed / Protocol error / Executable doesn't exist / ModuleNotFoundError / ECONNREFUSED / Address already in use ✅ 自动修复（playwright install / pip install / lsof） LOCATOR_ERROR TimeoutError + locator 在 page-source 不存在 ✅ AST 修复 / pages.yaml 对比 / Claude 语义推断 TIMEOUT_ERROR TimeoutError + locator 在 page-source 存在 （渲染慢） ✅ AST rewrite（调 timeout / 加 wait_for_load_state） DATA_ERROR setup 阶段失败 + fixture 数据问题 + 唯一约束冲突 ✅ 调 api-testdata-cleaner / 提示 seed SCRIPT_ERROR AttributeError has no attribute / DeprecationWarning ✅ AST rewrite（method typo / deprecated api） BUG console-logs 含 Page Error / Uncaught / 网络 5xx ⚠️ 注入 xfail/flaky marker（不改断言） 判定优先级： ENV_ERROR > BUG > LOCATOR/TIMEOUT > DATA_ERROR > SCRIPT_ERROR （环境挂了什么都无意义；BUG 是根因；其余按可修复性排序） Step 4：根因定位（14 种，全部实装） 类别 根因 fix_strategy 修复方式 TIMEOUT insufficient_wait ast_rewrite timeout=N → max(N*3, 30000) TIMEOUT page_not_loaded ast_rewrite 加 wait_for_load_state("networkidle") LOCATOR missing_iframe_switch ast_rewrite page.locator(X) → page.frame_locator(...).locator(X) LOCATOR shadow_dom_not_pierced claude_semantic 推荐 >>> piercing selector LOCATOR locator_drift claude_semantic grep page-source 找候选，Claude 推断 ENV missing_browser_binary category_repair python -m playwright install <browser> ENV missing_python_package category_repair pip install <package> ENV port_conflict category_repair lsof -i :<port> 提示 kill ENV service_unavailable category_repair 提示启动后端服务 DATA unique_constraint_conflict category_repair 调 api-testdata-cleaner DATA fixture_data_missing category_repair 提示 seed 脚本 SCRIPT missing_async_list_wait ast_rewrite 在 get_product_count() 首行插入 _wait_for_product_list_loaded() + base_page helper SCRIPT assertion_mismatch none verify 失败升级，仅报告（建议排查后端/数据） BUG known_bug_pattern category_repair 注入 xfail/flaky marker 到 conftest Step 5：自动修复（4 个修复模块各司其职） 5.1 AST rewrite（TIMEOUT/LOCATOR） apply_insufficient_wait_fix ：源码级 timeout 字面量替换 apply_iframe_switch_fix ：AST 定位 self._x = page.locator(...) 加 frame_locator apply_method_typo_fix ：AST 定位 .typo( 调用，替换为正确方法名（不误伤字符串字面量） apply_deprecated_api_fix ： query_selector → locator 等 1:1 映射 默认 backup=True ，原文件写 .bak ； dry_run=True 时不写 5.2 ENV 自动修复（env_repair.py） playwright install <browser> ：自动执行（🟢 低风险） pip install <package> ：默认 auto_run=True （🟡 中风险，可关闭） lsof -i :<port> ：默认 auto_run=False （🔴 需人工确认 kill） 5.3 DATA 数据修复（data_repair.py） sibling_skill 调起 api-testdata-cleaner --target <constraint> --mode duplicates fixture 失败：仅输出排查建议（不自动 seed 数据库，避免污染生产共享环境） 5.4 BUG 容错（bug_repair.py） 命中 KNOWN_BUG_SIGNATURES → conftest.py 加 xfail marker 偶发失败（历史记录 mixed pass/fail）→ 加 flaky marker 网络 5xx → 加 flaky marker（瞬时故障） 稳定 Page Error → 仅强化报告（不自动 skip，避免掩盖真实 bug） marker 注入机制： 写到 tests/conftest.py 末尾，通过 pytest_runtest_setup hook 给指定 nodeid 加 marker 用 signature 注释做幂等： # ui-failure-diagnoser: marker xfail on <nodeid> 同 marker + 同 nodeid 不重复注入 Step 6：验证闭环（ --verify 时） 对每个 ast_rewrite 修复，subprocess 调起单用例重跑。失败的修复自动 rollback .bak 。 category_repair 不重跑（副作用操作不验证）。 Step 7：审计与报告 审计日志 （JSONL）： 路径： <project>/.ui-failure-diagnoser/audit.log 每条记录含：时间戳、命令、退出码、stdout/stderr 尾部、trigger_nodeid、trigger_category Markdown 报告 （ ui_repair_report.md ）： 概览：分类统计 + 根因统计 + 已应用 AST 修复数 + 已应用类别修复数 明细：每条失败的分类、根因、修复动作、target 文件、原始错误 CLI 接口 python3 scripts/diagnose.py \ --junit-xml ./test-results/report.xml \ --artifacts-dir ./test-results/artifacts \ --project-dir ./shop-lab-ui-test \ [--conftest ./tests/conftest.py] \ [--pages-yaml ./pages.yaml] \ [--audit-log ./.ui-failure-diagnoser/audit.log] \ [--no-fix] \ [--dry-run] \ [--verify] \ [--base-url http://localhost:3000] \ [--browser chromium] 参数 类型 默认 说明 --junit-xml Path 必填 JUnit XML 路径 --artifacts-dir Path 必填 artifacts 根目录 --project-dir Path 必填 项目根（含 pages/ ） --pages-subdir str pages pages 子目录名 --conftest Path <project>/tests/conftest.py conftest.py（bug marker 注入） --pages-yaml Path - pages.yaml（locator 对比金标准） --audit-log Path <project>/.ui-failure-diagnoser/audit.log 审计日志 --output Path <artifacts>/../ui_repair_report.md 报告输出 --no-fix flag false 只分类 + 定位，不应用修复 --dry-run flag false AST 修复 dry-run 模式（不写文件） --verify flag false AST 修复后重跑单用例验证 --base-url str - verify 时 base-url --browser str - verify 时浏览器 退出码： 0 成功； 2 输入错误。 两阶段诊断流程（missing_async_list_wait） 当 SCRIPT_ERROR 用例匹配搜索 0 结果断言时，走特殊两阶段流程： Stage 1: 初次诊断 SCRIPT_ERROR + 三点信号匹配（搜索 + 期望>0 + 实际=0） → root_cause = missing_async_list_wait → apply_async_wait_fix() · 在 get_product_count() 首行插入 self._wait_for_product_list_loaded() · 在 base_page.py 追加 _wait_for_product_list_loaded 方法 → verify (重跑单用例) Stage 2: verify 后分类升级 verify PASS → 保留修改，报告"已修复 missing_async_list_wait" verify FAIL → rollback + 升级为 assertion_mismatch → 报告"非异步加载问题，建议排查后端搜索接口/测试数据" 信号三点 AND： _SEARCH_CONTEXT : 搜索 / search / 查询 / 检索 _POSITIVE_EXPECTATION : 应返回 / 应为 / should return / expected _ZERO_ACTUAL : 结果数为 0 / count is 0 / returned 0 负向断言（ 搜索 'X' 应无结果，但返回 N 个 ）不匹配 _ZERO_ACTUAL ，自动排除。 关键能力详解 pages.yaml 金标准对比（LOCATOR_ERROR） 当 page object 中的 locator 失效时，本技能会： 读取 pages.yaml （ui-page-parser 的输出，含 strategy / value / fallback ） 提取失败 locator 的语义身份（placeholder/label/role/test_id） 在 pages.yaml 中找同身份元素的 canonical locator 输出推荐的新 locator（优先级： data-testid > role > label/placeholder/text > id > css > xpath ） 详见 scripts/pages_yaml_resolver.py 。 安全保证 永不改 tests/**/*.py 断言 ：apply_fix.py 只对 pages/**/*.py 做 AST rewrite conftest.py 只加 marker hook ：bug_repair.py 通过 signature 注释做幂等 marker 注入，不改 fixture/setup 语义 所有副作用走 AuditLogger ：pip install / playwright install / sibling skill 调用都有 JSONL 审计 AST rewrite 必 backup ：默认 .bak ； dry_run=True 时不写文件 rollback on verify failure ：修复后重跑失败的自动恢复 .bak 风险分级（自动执行策略） 级别 操作 默认行为 🟢 低风险 playwright install 、AST rewrite、conftest marker 自动执行 🟡 中风险 pip install 、调兄弟技能清理数据 默认执行，可关闭 🔴 高风险 lsof kill 、数据库 seed 仅输出建议，需人工确认 🚫 禁止 改 tests/** 断言、删除文件、force push 永不执行 典型使用场景 场景 1：CI 失败后本地诊断 python3 scripts/diagnose.py \ --junit-xml ./test-results/report.xml \ --artifacts-dir ./test-results/artifacts \ --project-dir ./shop-lab-ui-test \ --dry-run 生成 ui_repair_report.md ，不改任何文件。 场景 2：自动修复 + 验证 python3 scripts/diagnose.py \ --junit-xml ./test-results/report.xml \ --artifacts-dir ./test-results/artifacts \