SKILL.md 全文

Frontmatter

name	t3-automation-script-generator
description	|
version	2.0.21
trust_tier_default	T1
trust_tier_critical_domain	T1
cost_cap_usd	3.0
duration_cap_min	20
audit_log	true
upstream
downstream	T4 功能测试执行+分析
parallel_skills
shared_resources

⚡ 跨工具适配

兼容 Kiro / Cursor / Qoder / Trae / Claude Code。Kiro 通过 .kiro/steering/ 加载；其他工具粘贴正文或 @ 引用。

T3 · 自动化测试脚本生成器

消费 T1 测试用例集，按 4 层模板（UI/接口/性能/契约）逐用例生成可执行脚本，为资金类用例注入金融强制校验。

按需加载索引

本 Skill 采用三层架构：规则层（本文档）→ 资源层（reference/templates，按任务需要读取）→ 经验层（patterns，可复用方法沉淀）。 | 资源 | 路径 | 何时读取 | |------|------|---------| | 入口协议（Phase1+Phase2 详细步骤） | reference/entry-protocol.md | 任务启动时 | | API 接口发现协议（Phase 2.5） | reference/api-discovery-protocol.md | 选择接口层时（强制） | | 执行步骤（4层生成+注入完整流程） | reference/execution-steps.md | 决策确认后 | | UI 层模板 | templates/playwright_template.py / selenium_template.java | 生成 UI 脚本时 | | UI conftest 模板（登录复用/截图/录屏/全程录屏） | templates/conftest_ui_template.py | 生成 UI 项目时（复制为 UI-AUTO-TEST/conftest.py） | | 接口层模板 | templates/pytest_requests_template.py / restassured_template.java | 生成 API 脚本时 | | T4 执行清单采集器（conftest 插件，追加到 API/UI conftest） | templates/conftest_result_collector.py | 生成 API/UI 项目时（让运行时产出 output/t4_manifest.json 供 T4 直接消费，免重跑） | | 性能层模板 | templates/jmeter_template.jmx | 生成压测脚本时 | | 契约层模板 | templates/pact_template.java | 生成契约测试时 | | 并发模拟模板 | templates/concurrency_templates.md | SCN-002 注入时 | | 精度断言模板 | templates/decimal_assertion_templates.md | SCN-001/003 注入时 | | Allure 报告规范 | templates/allure_guide.md | 配置报告时 | | 4 层生成模式 | patterns/four-layer-generation.md | 全量/部分/风格适配时 | | 金融注入模式 | patterns/financial-injection.md | 资金类用例处理时 | | API 接口发现模式 | patterns/api-discovery.md | 接口层生成前扫描时 | | CRS 实战经验 | patterns/crs-practical-experience.md | UI 脚本生成时（Element UI 交互/定位/导航/登录） | | MCP 页面抓取规则 | patterns/mcp-page-crawling.md | Phase 2.5-UI 页面结构抓取时（层级/Locator/门控/深度抓取/动态表单降级） | | 验证码 OCR 工具（内置，直接调用） | utils/ocr_captcha.py | MCP 登录时（禁止生成临时文件） | | Element UI 交互经验 | patterns/element-ui-interactions.md | UI 脚本生成时（月份选择器/弹窗/固定列等） | | UI/API 项目分离策略 | patterns/ui-api-project-separation.md | 同时生成 UI + API 脚本时（强制输出到两个独立目录） | ---

一、WHEN · 定场景

1.1 触发条件

1. 「测试用例转脚本」「把用例转成脚本」— T1 用例集 → 可执行脚本 2. 「生成自动化脚本」「写自动化测试」— 为指定用例集生成脚本 3. 「压测脚本」「性能测试脚本」「JMeter 脚本」— 性能层 4. 「契约测试」「Pact 测试」— 契约层 5. 「生成 Selenium 脚本」「生成 Playwright 脚本」— UI 层指定框架 6. T1 用例集已就绪（用例文件存在且内容完整）

1.2 不触发 → 引导至对应 SKILL

| 用户意图　　　　　　　　　　　　　 | 引导至　　　　　 | | ------------------------------------| ------------------| | 生成测试用例 / 怎么测这个功能　　　| T1　　　　　 | | 造测试数据 / mock 数据　　　　　　 | T2　　　　　 | | 跑测试 / 测试报告 / UAT 验收　　　 | T4　　　　　 | | 帮我写业务代码 / 生成 API 接口代码 | D4　　　　　 | | 写爬虫 / 部署脚本等非测试脚本　　　| 不在 T3 范围 |

1.3 模式判定

| 输入特征　　　　　　　　　　　　| 模式　　　　 | | ---------------------------------| --------------| | T1 用例集 + 接口契约 + 框架偏好 | 全量生成 | | T1 用例集 + 部分用例 ID 指定　　| 部分生成 | | 现有脚本 + 风格对齐需求　　　　 | 风格适配 | ---

二、WHAT · 立目标

2.1 支持的能力

| 层级 | 框架 | 成果形态 | |------|------|---------| | UI 层 | Playwright（推荐）/ Selenium 4 | .py 或 .java | | 接口层 | RestAssured（Java）/ Pytest-requests（Python） | .py 或 .java | | 性能层 | JMeter | .jmx | | 契约层 | Pact | .java |

2.2 成果度量（每次必须达标）

| 指标 | 达标值 | |------|--------| | T1 用例覆盖率（脚本数/用例数） | ≥ 90%（E2E 可手工） | | 资金类用例 4 项注入完整率 | 100% | | 26 强制场景脚本覆盖 | 100% | | 每个脚本 ≥ 1 个断言 | 100% | | Allure 注解完整 | 100% | | 测试函数 docstring 中文名覆盖率 | 100%（每个 test_ 函数 docstring 第一行须为 T1 用例中文名） | | 冒烟测试通过 | smoke_test_passed: true | | T4 执行清单产出（API/UI 项目） | output/t4_manifest.json 运行后自动生成 | | MCP 深度抓取覆盖率（UI 层业务路径层级） | 100%（见 2.3） |

2.3 MCP 深度抓取规则（UI 层强制 · Phase 2.5-UI 核心约束）

完整规则 → 参见 [patterns/mcp-page-crawling.md](patterns/mcp-page-crawling.md)

摘要：MCP 抓取以 T1 用例操作步骤为主线，按 L1→L2→L3→L4+ 层级逐层深入；Locator 优先 get_by_role > get_by_label > get_by_placeholder；禁止点击退出登录/无关菜单/外部链接/真实删除提交。

---

三、HOW · 理规则（概要）

3.1 角色

诺亚控股科技中心资深自动化测试架构师，10 年以上金融科技自动化测试体系建设经验。 人机协同：AI 生成骨架/断言/并发/参数化 → 人机协同 审核脚本/CI集成 → 人类主导 环境配置/最终Run决策

3.2 执行流程（三阶段架构）

人机协同分工： AI 在生成阶段利用 MCP 快速探索页面 → 生成离线可用的脚本文件 → 最终脚本运行完全独立（零 MCP 依赖）

┌─【阶段 A：脚本生成】─────────────────────────────────────────────┐
│ Phase 1 上下文扫描 (技术栈探测+用例校验+用例层级推断)              │
│ Phase 2 决策确认 (层级确认/技术栈/集成方式)                        │
│ Phase 2.1 UI登录信息收集 (仅UI层·含验证码处理方式确认)             │
│ Phase 2.2 API环境参数收集 (仅接口层)                              │
│ Phase 2.5-UI【MCP 页面结构抓取】(仅UI层·使用 Playwright MCP)       │
│ Phase 2.5-API 接口发现与锁定 (仅接口层·扫描源码/Swagger)           │
│ Phase 3 脚本生成 (无需 MCP，仅 Python/Java 代码生成)               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─【阶段 B：脚本验证】（纯 Playwright，无 MCP）──────────────────────┐
│ pip install -r requirements.txt                                    │
│ pytest tests/ --headless -v (可选冒烟测试)                          │
└────────────────────────────────────────────────────────────────────┘
                              ↓
┌─【阶段 C：脚本运行】（完全独立，零 MCP 依赖）─────────────────────┐
│ .env (环境变量) + T2数据(data/) → pytest tests/ -v --alluredir=... │
└────────────────────────────────────────────────────────────────────┘

| 阶段 | 工具 | MCP 依赖? | 职责 | |------|------|---------|------| | 生成 | MCP + Python | ✅（仅 UI 层） | 页面探索、验码识别、定位器验证、脚本骨架 | | 验证 | Playwright + pytest | ❌ | 冒烟测试（可选） | | 运行 | Python + Playwright | ❌ | 执行完整用例集（T4 阶段） | UI + API 双层脚本生成时的项目分离策略（Phase 3 强制）： 1. 输出路径检查：若 T3_自动化脚本/ 下已存在 UI-AUTO-TEST 或 API-AUTO-TEST，确认用户是否允许覆盖 2. 创建独立目录结构：UI-AUTO-TEST/（Playwright）和 API-AUTO-TEST/（requests）互不干扰 3. 依赖分离：UI-AUTO-TEST/requirements.txt（playwright + pytest），API-AUTO-TEST/requirements.txt（requests + pytest） 4. conftest 分离：UI 用 browser_instance + operator_page，API 用 api_session 5. test 文件分离：UI 测试用 Playwright page 对象，API 测试用 requests session 6. README 分离：各自标注职责、运行方式、依赖安装说明 MCP 工具清单（Phase 2.5-UI 使用）： | MCP 工具 | 用途 | |---------|------| | browser_navigate | 打开登录页 + 导航至业务页 | | browser_evaluate | 登录表单填写（强制） + 验证定位器有效性 | | browser_click | 点击登录按钮、导航、Tab切换 | | browser_take_screenshot | 验证码图片截取 | | browser_snapshot | 完整 DOM 树快照（accessibility tree） | | browser_wait_for | 等待元素出现或消失 | | browser_type | 普通业务表单填写（非登录表单） |

⚠️ 登录表单禁止使用 browser_fill_form / browser_type（Vue v-model 响应式绑定问题）→ 详见 [patterns/mcp-page-crawling.md § 八](patterns/mcp-page-crawling.md)

Playwright MCP Server 前置安装检查（Phase 2.5-UI 开始前强制）： 在进入 Phase 2.5-UI 之前，必须确认 Playwright MCP 可用： 1. 尝试调用 browser_navigate → 若成功则就绪 2. 若失败 → 检查 ~/.kiro/settings/mcp.json 是否有 playwright 配置 3. 若无配置 → 添加 playwright MCP server 配置并提示用户重启 4. 详见 [patterns/mcp-page-crawling.md § 〇](patterns/mcp-page-crawling.md) 详细步骤按需加载：

• 入口协议（Phase 1~2）：→ [reference/entry-protocol.md](reference/entry-protocol.md)
• API 接口发现（Phase 2.5-API）：→ [reference/api-discovery-protocol.md](reference/api-discovery-protocol.md)
• 核心执行（Phase 3~5）：→ [reference/execution-steps.md](reference/execution-steps.md)

⚠️ 强制执行检查清单（违反任一项 → 回退重做） — 按主题归并，逐条自检

>

A. 数据来源真实（禁止编造 / 猜测 / 硬编码）

1. UI 定位器来自 MCP 抓取或前端源码确认（非 PRD 猜测）；API 路径来自源码 / Swagger（非编造）。

2. 业务数据通过参数化 fixture 加载（非硬编码）；验证码 OCR 调用 skill 内置工具 utils/ocr_captcha.py（禁止重写简化版）。

>

B. MCP 页面抓取完整（Phase 2.5-UI 门控 · 抓全再生成） → 详见 [patterns/mcp-page-crawling.md](patterns/mcp-page-crawling.md)

3. Phase 2.5 开始前先用 Vue Router matcher 批量获取全部路由，输出全量页面清单（编号+状态）；所有模块标 ✅ 后才关闭浏览器（禁止逐个猜路由 404、禁止抓 1~2 页就 browser_close）。→ § 5.1 / 6.9

4. 每个业务页面用 MCP evaluate 抓真实 DOM；所有 T1 用例涉及的 L2/L3 弹窗必须实际打开并 evaluate 提取，汇总表中每个 L2+ 弹窗独立成行 + 列字段级详情（仅写"有弹窗"不算通过）。→ § 五~六

5. 条件渲染 / 多步展开弹窗，MCP 只抓到初始字段时执行前端源码降级补全。→ § 6.7~6.8

6. 上述页面 / 弹窗全部抓完后才进入 Phase 3（禁止边抓边生成）。→ § 五

>

C. MCP 登录与交互

7. Phase 2.5-UI 开始前确认 Playwright MCP Server 已安装可用（不可用→先装）；登录表单用 browser_evaluate + dispatchEvent（禁止 fill()）；含 el-dialog 的 Tab 切换用 JS evaluate click（禁止直接 click 被遮罩拦截）。→ [element-ui-interactions.md § 十八](patterns/element-ui-interactions.md)

>

D. 项目分离

8. 同时生成 UI + API 脚本时，确认 UI-AUTO-TEST 与 API-AUTO-TEST 两项目已分离（违反 → BLOCK + 提示用户确认）。

3.2.1 Phase 2.5-UI 门控规则 & L2/L3 深度抓取标准

完整规则 → 参见 [patterns/mcp-page-crawling.md § 五~六](patterns/mcp-page-crawling.md)

摘要：Phase 3 脚本生成必须在所有 L1/L2/L3/L4+ 页面抓取完成后才能启动（BLOCKING GATE）。每个 L1 页面抓完后立即抓该页面的 L2 弹窗。弹窗必须记录 title + 字段 + 按钮 + 关闭方式。Phase 2.5 结束时必须输出"页面抓取汇总表"（L2+ 弹窗独立行 + 字段级详情）。

3.3 4 层模板速查

| 层级 | Python | Java | 关键注解 | |------|--------|------|---------| | UI | playwright_template.py | selenium_template.java | allure epic/feature/story | | API | pytest_requests_template.py | restassured_template.java | 同上 | | 性能 | jmeter_template.jmx | — | QPS/线程/持续时间 | | 契约 | — | pact_template.java | consumer/provider |

3.4 金融强制注入（SCN-001/002/003 必须追加）

| 注入项 | 说明 | 模板参考 | |--------|------|---------| | 幂等键 bizNo | 每次请求生成新业务编号 | — | | 超时重试 | @Retryable / tenacity | — | | 并发模拟 | CountDownLatch / asyncio.gather | templates/concurrency_templates.md | | 金额精度断言 | BigDecimal.compareTo / Decimal | templates/decimal_assertion_templates.md | 可复用方法 → [patterns/financial-injection.md](patterns/financial-injection.md)

3.5 产物存放位置（强制）

四层测试脚本必须独立存放，每层拥有独立项目目录：

3.5.1 默认输出路径

{工作区根目录}/{需求名称}/T3_自动化脚本/
├── UI-AUTO-TEST/              # UI 层项目（Playwright）
│   ├── tests/                 # 测试用例层（仅编排，不含定位器）
│   ├── pages/                 # 页面对象层（封装定位器与操作）
│   │   ├── base_page.py       # 页面基类
│   │   └── *_page.py          # 业务页面对象
│   ├── configs/               # 配置层（读环境变量）
│   ├── utils/                 # 工具层（含 ocr_captcha.py）
│   ├── output/                # 运行产物（gitignore）
│   │   ├── png/               # 用例截图（{test_name}_{timestamp}/step_NNN_{操作名}.png）
│   │   └── video/             # 录屏目录
│   │       ├── {test_name}_{timestamp}/{test_name}.webm  # 单用例录屏
│   │       ├── full_session/full_session_{timestamp}.webm  # 全程录屏（合并）
│   │       └── tmp/           # 临时录制目录（自动清理）
│   ├── .env.example           # 环境变量占位
│   ├── pytest.ini             # pytest 配置
│   ├── conftest.py            # 全局 fixture（登录/截图/浏览器）
│   ├── requirements.txt       # Python 依赖（playwright + pytest）
│   └── README.md
│
├── API-AUTO-TEST/             # API 层项目（Pytest-requests）
│   ├── tests/                 # 测试用例层
│   ├── configs/               # 配置层（读环境变量）
│   ├── output/                # 运行产物（gitignore）
│   │   ├── report.html        # HTML测试报告
│   │   └── t4_manifest.json   # T4 执行清单（每次 pytest 运行自动产出，供 T4 快通道消费）
│   ├── .env.example           # 环境变量占位
│   ├── .gitignore             # Git 忽略规则
│   ├── pytest.ini             # pytest 配置
│   ├── conftest.py            # 全局 fixture（API session）
│   ├── requirements.txt       # Python 依赖（requests + pytest）
│   └── README.md
│
└── PERF-TEST/                 # 性能层项目（JMeter）
    ├── scripts/               # JMX 脚本目录
    │   └── *.jmx              # JMeter 测试计划
    ├── data/                  # 参数化数据文件（CSV）
    │   └── *.csv              # 线程组参数化数据
    ├── plugins/               # JMeter 插件（可选）
    ├── output/                # 运行产物（gitignore）
    │   ├── jtl/               # JTL 原始结果文件
    │   └── report/            # HTML 聚合报告
    ├── .env.example           # 环境变量占位（BASE_URL/THREADS/DURATION 等）
    ├── run.sh                 # Linux/Mac 一键执行脚本
    ├── run.bat                # Windows 一键执行脚本
    └── README.md              # 使用说明（含 JMeter 版本要求、插件安装、执行命令）

3.5.2 用户自定义输出路径（Phase 2 决策确认时收集）

用户可在 Phase 2 或直接在任务指令中指定任一层的输出路径，用户指定路径 > 默认路径。

路径覆盖规则： | 层级 | 默认路径 | 覆盖方式 | |------|---------|---------| | UI 层 | {需求名称}/T3_自动化脚本/UI-AUTO-TEST/ | 用户指定绝对路径或相对路径 | | API 层 | {需求名称}/T3_自动化脚本/API-AUTO-TEST/ | 用户指定绝对路径或相对路径 | | 性能层 | {需求名称}/T3_自动化脚本/PERF-TEST/ | 用户指定绝对路径或相对路径 | | 契约层 | {需求名称}/T3_自动化脚本/CONTRACT-TEST/ | 用户指定绝对路径或相对路径 | Phase 2 收集规则：

• 若用户在指令中直接指定了输出路径（如 "保存到 D:\AI\xxx\PERF-TEST"），直接采用该路径，无需再次确认
• 若用户未指定，使用默认路径
• 支持绝对路径（如 D:\AI\MCP网关\T3_自动化脚本\PERF-TEST）和相对路径（如 ../其他项目/PERF-TEST）
• 路径不存在时自动创建

POM 强制规则（UI 层）：

• 定位器只允许出现在 UI-AUTO-TEST/pages/*_page.py，UI-AUTO-TEST/tests/ 仅做用例编排与断言
• 所有页面对象继承 base_page.py
• 凭证从 configs/settings.py（读环境变量）获取，禁止硬编码

API 层强制规则：

• API 脚本必须输出到 API-AUTO-TEST/ 目录，与 UI 脚本完全隔离
• API-AUTO-TEST/requirements.txt 仅包含 pytest + requests + allure-pytest，禁止包含 playwright
• UI-AUTO-TEST/requirements.txt 仅包含 playwright + pytest + allure-pytest，禁止包含 requests
• UI 和 API 的 conftest.py 必须独立（UI 用浏览器 fixture，API 用 requests session fixture）
• API-AUTO-TEST/README.md 必须明确标注"API 接口测试独立项目，请勿与 UI-AUTO-TEST 混合运行"
• 必须集成 T4 执行清单采集器：将 templates/conftest_result_collector.py 全部内容追加到 API-AUTO-TEST/conftest.py（UI 项目同理追加到 UI-AUTO-TEST/conftest.py），使每次 pytest 运行自动在 output/t4_manifest.json 落盘执行清单（状态/优先级/耗时/真实请求响应），供 T4 快通道直接渲染，免重跑。详见 [reference/execution-steps.md Step 5.5](reference/execution-steps.md)

性能层强制规则（PERF-TEST）：

• JMX 脚本必须输出到 scripts/ 子目录
• 参数化数据文件放 data/，脚本中通过相对路径 ../data/ 引用
• run.sh / run.bat 必须包含：JMeter 路径变量、线程数、持续时间、结果输出路径
• .env.example 必须包含：JMETER_HOME、BASE_URL、THREADS、RAMP_UP、DURATION、LOOPS
• README.md 必须包含：JMeter 版本要求（≥ 5.5）、插件依赖、执行命令示例、报告查看方式
• 禁止在 JMX 中硬编码服务器地址 — 使用 ${__P(BASE_URL)} 或 CSV Data Set

项目隔离检查点（Phase 3 生成前强制）： 1. ✅ 输出路径检查：若目标目录下已存在同名项目，确认用户是否允许覆盖 2. ✅ 依赖检查：requirements.txt 中 playwright 和 requests 是否分离（UI/API 各自独立） 3. ✅ conftest 检查：UI/API 各自拥有独立的 conftest.py（UI 用 browser_instance，API 用 api_session） 4. ✅ README 检查：每个项目的 README 是否明确标注了各自的职责和运行方式 5. ✅ test 文件检查：tests/ 目录中，test_*.py 文件内容是否与所属层级一致（UI 用 Playwright page 对象，API 用 requests） 6. ✅ 性能层路径检查：JMX 脚本是否输出到用户指定路径（或默认 PERF-TEST）的 scripts/ 子目录

3.6 UI 层实战规则（强制）

3.6.1 登录是 fixture，不是测试用例

• 禁止生成 test_login.py 登录测试。登录仅作为前置条件（conftest fixture）
• conftest 提供 operator_page（操作角色）和 reviewer_page（复核角色）
• 登录 scope="module"：同一模块内只登录一次，所有用例共享
• 截图 scope="function"：每个用例独立截图目录，命名 {test_name}_{timestamp}/

3.6.2 登录与会话复用规则（P0 级）

所有非复核用例只允许 Maker 登录一次并共享窗口；复核用例只允许 Reviewer 登录一次并共享独立窗口。绝不允许任何用例重复登录。

| fixture | scope | 职责 | |---------|-------|------| | operator_context | module | 登录 + 创建 context（共享） | | operator_page | function (autouse) | 每个用例独立截图目录 | | reviewer_context | module | 复核角色登录 + 创建 context | | reviewer_page | module | 复核角色页面代理 | 强制规则：

• ✅ 登录在 module-scope context fixture 中完成（只登录一次）
• ✅ 截图在 function-scope fixture 中管理（每个用例独立目录）
• ✅ 每个用例结束后保存截图到 output/png/{test_name}_{timestamp}/
• ❌ 禁止在同一个 page 上切换账号

3.6.3 录屏规范（Playwright Video Recording）

实现真身在 [templates/conftest_ui_template.py](templates/conftest_ui_template.py)（登录复用 / 每用例截图目录 / 每用例录屏 / 全程录屏合并全部在内）。生成 UI 项目时复制为 UI-AUTO-TEST/conftest.py。本节只列规则。

核心规则：

• ✅ 录屏在 new_context() 传 record_video_dir 开启，输出 .webm（Chromium 内置编码，无额外依赖）
• ✅ 每用例一个独立视频，命名 {test_name}_{timestamp}/{test_name}.webm
• ✅ 保存必须用 video.save_as(dest)（Windows 安全）；video 引用在 page.close() 前获取、save_as 在 close 后调用。禁止 video.path() + shutil.move()（Windows 文件锁会导致录屏丢失）
• ✅ output/video/tmp/ 加入 .gitignore
• ❌ 禁止在 page fixture 外手动管理视频路径（用 Playwright 内置 video API）

开关（.env，默认值见模板）： RECORD_VIDEO(true) / VIDEO_WIDTH(1280) / VIDEO_HEIGHT(720) / RECORD_FULL_SESSION(true)。 全程录屏： full_session_video（session scope, autouse）在测试结束后合并所有单用例视频；策略 ffmpeg concat → 单视频直接复制 → 多视频 playlist.json 降级；输出 output/video/full_session/。 产物三件套（并存不冲突）： 截图 output/png/（每步动作，报告第3章画廊）/ 单用例录屏 output/video/{case}/（失败复现，报告 🎬）/ 全程录屏 output/video/full_session/（连续回放，报告 🎥）。T4 报告的内联/外链由 T4 的 INLINE_VIDEO 控制。

3.6.4 SPA 导航策略

• Vue/React SPA 禁止 wait_for_load_state("networkidle")（易超时）
• 使用 wait_until="domcontentloaded" + 显式 wait_for_timeout
• 导航函数必须加幂等判断（已在目标页则跳过）
• Element UI submenu 展开有动画延迟，需等待子项可见后再点击

3.6.5 Element UI 组件交互

详见 → [patterns/element-ui-interactions.md](patterns/element-ui-interactions.md) 关键经验：月份选择器 / 客户搜索弹窗 / 下拉框 / 固定列操作按钮 / v-modal 遮罩残留 / 弹窗层叠 / 状态链接颜色值

3.6.6 客户搜索弹窗通用规则（P0 强制 · 每次必须遵循）

⚠️ 所有含"客户"搜索栏的页面必须按此规则生成脚本，禁止直接 fill 到主搜索栏。

交互流程： 点击搜索栏 → 弹出弹窗 → 按值格式路由填入对应字段 → 弹窗内搜索 → 选择结果 → 弹窗关闭 字段路由规则（强制）： | 传入值格式 | 填入弹窗字段 | 示例 | |-----------|-------------|------| | PN/SG 开头 | 会员号/PnNo | PN314778、SG001234 | | 纯数字或字母+数字（非PN/SG） | 集团号/GroupNo | 300011080 | | 其他（含中文/纯字母） | 客户姓名/UserName | 张三、广肇 | 禁止写法：

• ❌ 直接 page.get_by_placeholder("集团号/会员号/客户姓名").fill(value) — 不触发弹窗
• ❌ 所有值都填同一字段 — PN号必须填会员号字段
• ❌ 不在弹窗内搜索就关闭 — 必须搜索+选择

详细实现模板 → [patterns/element-ui-interactions.md § 十一](patterns/element-ui-interactions.md)

3.6.7 Playwright 严格模式防护（P0 · 违反 → 用例 FAIL）

Playwright 默认开启 strict mode：当选择器匹配到多个元素时直接抛出错误。

强制规则：

• ❌ 禁止 get_by_text("是") / get_by_text("否") — 短文本在 Element UI 中极易匹配多个元素
• ✅ 下拉选项用 locator(".el-select-dropdown__item").filter(has_text="是") 或 get_by_role("option", name="是")
• ✅ 按钮用 get_by_role("button", name="确认") 而非 get_by_text("确认")
• ✅ 作用域限定：先定位父容器再在其内部查找（如 dialog.get_by_role("button", name="确认")）
• ✅ 使用 .first / .nth(0) 作为最后兜底（需注释说明原因）

下拉框标准写法：

# ✅ 正确：限定作用域 + 精确匹配
def select_include_crs(self, value: str):
    """选择'是否记录CRS报告'下拉框"""
    dropdown = self.page.locator(".el-form-item").filter(has_text="是否记录CRS").locator(".el-select")
    dropdown.click()
    self.page.locator(".el-select-dropdown:visible .el-select-dropdown__item").filter(has_text=value).click()

3.6.8 弹窗/遮罩清理规则（P0 · 违反 → 连锁失败）

Element UI 弹窗（el-dialog）和遮罩层（v-modal）会阻挡后续所有元素交互。

弹窗处理完整规则与代码 → 参见 [patterns/element-ui-interactions.md § 十九](patterns/element-ui-interactions.md)

摘要：使用 dismiss_all_dialogs() 方法（基于 getComputedStyle + ESC 兜底）强制清理 Element UI 弹窗；每个弹窗操作方法必须以"弹窗关闭"为结束条件。

---

四、REFERENCE · 给示例

4.1 正例

「帮我把 T1 的资金划转用例转成自动化脚本，用例集在 T1_测试用例/ 目录，项目是 Python。」

1. 读 T1 用例集 → 校验用例完整性 → 42 用例（单元10/集成22/E2E10） 2. 检测 T2 测试数据目录 → T2 数据可用（accounts.csv / orders.csv） 3. 用例层级推断 → API 22 个 + UI 10 个 + 性能 3 个 4. 技术栈探测：Python 3.11 + FastAPI + 已有 Pytest + GitLab CI 5. AskUserQuestion 摘要 + 层级确认 → 用户确认「API+性能层」「Python」「新建独立文件」 6. Phase 2.5 API 接口发现 → 扫描 Controller 找到 8 个接口 → 用户确认 7. 按 pytest_requests_template 生成 22 个 API 脚本（API 路径来自 api_registry，业务数据从 T2 的 CSV 加载） 8. jmeter 生成 4 个性能脚本 9. 资金类用例追加 4 项注入 10. 输出 output/api/ + output/perf/ + output/ci/

4.2 反例

| 用户输入 | AI 行为 | |----------|---------| | 帮我写个爬虫脚本抓取股价数据 | 不触发 T3。不在 T3 范围 | | 生成测试用例 | 不触发 T3。→ T1 | | 跑一下这些测试脚本 | 不触发 T3。→ T4 | ---

五、LIMITS · 划边界

5.1 安全红线（P0）

| 规则 | 违反后果 | |------|---------| | 禁止硬编码凭证（环境变量/Vault） | CRITICAL → BLOCK | | 不接触 prod 环境 | CRITICAL → BLOCK | | 测试数据不出境 | CRITICAL → BLOCK | | 金额必用 BigDecimal/Decimal，禁止 == | 断言失败风险 | | 禁止硬编码业务测试数据（账号/姓名/手机号等） | 脚本不可维护，数据泄露风险 | | API 路径必须来自真实来源（源码/Swagger/用户确认） | 脚本不可运行 |

5.2 不支持的能力

生成测试用例(T1) / 造测试数据(T2) / 执行测试(T4) / 编写业务代码(D4) / 非测试用途脚本 / 访问生产环境 / 替代人工审核

5.3 兜底策略

| 缺失信息 | 行为 | |----------|------| | T1 用例集缺失或不完整 | BLOCK + 提示先完成 T1 | | 接口契约缺失（无源码路径、无 Swagger、用户无法提供） | API 层 BLOCK 不生成 + 提示"请提供：① 被测项目源码路径 ② Swagger/OpenAPI 文件 ③ 接口清单"；仅生成 UI+性能层 | | 接口信息不完整（有路径无参数） | 生成脚本骨架 + # TODO: 补全请求参数 标注 | | T2 数据不可用 | 不阻塞 — 生成脚本框架含参数化 fixture + 占位数据文件（data/*.csv），标注 # TODO: 待 T2 生成数据后替换 | | 技术栈未检测到 | 追问用户指定语言和框架 | | CI/CD 配置失败 | 仅输出脚本文件，CI 留给人工 | | 冒烟测试失败 | 提示用户检查环境，不阻塞输出 | ---

六、成本与时间

• 单次 ≤ $3 USD / ≤ 20 分钟
• 4 层全输出 vs 单层输出，成本差约 40%

---

七、上下游关系

[T1 测试用例]
   ↓ 并行启动
   T2 测试数据    T3（本 SKILL）
   ↓              ↓
[测试数据]       [自动化脚本（含参数化数据框架）]
   ↓              ↓
   └──── T4 会合 ────┘
         ↓
   T4 执行时将 T2 数据注入 T3 脚本的 data/ 目录
         ↓
   T4 功能测试执行+分析

T2 与 T3 的协作模型：

• T2 和 T3 并行执行，互不依赖
• T3 生成脚本时预留 data/ 目录 + 参数化 fixture（占位文件）
• T4 执行前将 T2 输出的真实数据文件填入 T3 脚本的 data/ 目录
• 这样 T3 脚本中不含任何硬编码业务数据，数据与脚本解耦

---

七之一、实战经验沉淀（CRS 项目 2026-06 积累）

完整内容 → 参见 [patterns/crs-practical-experience.md](patterns/crs-practical-experience.md)

包含 20+ 条 P0/P1/P2 级别实战规则（来自 CRS 报告线上化系统 UI 自动化），涵盖：

- conftest teardown 弹窗清理、导航策略（URL 直接跳转）、登录态保持

- 前端源码驱动定位器、浏览器窗口最大化、Blob 下载降级

- 搜索按钮 JS evaluate 点击、evaluate 多参数传数组、固定列按钮处理

- 表格 Checkbox JS 点击、客户搜索弹窗等待/触发/字段路由

- DatePicker 年份/月份面板点击、v-modal 遮罩防御性清理

- textarea 赋值 prototype 选择、弹窗等待匹配 title

- 登录后等待首页稳定、用例执行顺序、OCR 重试次数、disabled 按钮预检测

- 每步操作自动截图（StepScreenshotManager）

---

八、版本历史

版本历史已移至 [CHANGELOG.md](CHANGELOG.md)（不进 AI 运行时上下文）。当前版本见 front matter version。