生成 UI 集成自动化脚本
任务背景
- 适用于根据用户明确提供的测试用例文件，生成面向浏览器 UI 流程验证的 Python
pytest 自动化脚本。
- 适用于已经明确脚本针对的用例分层集类型的任务，例如冒烟集、主流程集、边界集、回归集或项目约定的其他分层集。
- 适用于需要按需求版本、功能标题和用例分层集类型归档 UI 集成自动化脚本及其环境变量配置的场景。
- 适用于项目没有现成 UI 自动化脚本模板时，默认采用
pytest 与 Playwright for Python 组织页面对象、浏览器会话、登录和断言逻辑。
- 适用于测试脚本需要使用系统管理员账号完成 UI 登录，并通过用例特有环境变量补充特殊测试账户、业务数据或附件路径的场景。
- 不适用于缺少测试用例文件路径或缺少用例分层集类型的任务；遇到此类输入时只要求用户补充信息。
- 不适用于需要离开当前系统完成验证的用例执行；此类用例只在脚本中生成跳过标识和跳过原因。
任务步骤
- 执行输入门禁校验；门禁未通过时结束本次任务。
- 读取测试用例文件，识别需求版本号、功能标题、用例编号、用例名称、前置条件、操作步骤、预期结果和是否涉及当前系统外验证。
- 按用户指定的用例分层集类型筛选用例，只为该分层集内的用例生成测试函数。
- 根据用例涉及的页面、菜单、路由、按钮、输入框、表格、弹窗和文件入口，梳理需要使用的页面对象和稳定元素标识。
- 在编写脚本前检查用例涉及页面的前端代码是否已有稳定且唯一的
data-testid；若缺少，则先补充元素标识，且不得改变前端样式和业务逻辑。
- 创建或更新版本级公共环境变量文件
<项目根目录>/output/ui_test_scripts/<需求版本号>/.env.local。
- 创建脚本输出目录
<项目根目录>/output/ui_test_scripts/<需求版本号>/<功能标题>/<用例分层集类型>/。
- 在脚本输出目录中创建用例特有环境变量文件
.env.local。
- 生成
<功能标题>_UI集成自动化脚本.py，按规定结构写入模块说明、依赖导入、常量、配置读取、工具函数、页面对象、fixtures 和测试用例。
- 对生成脚本执行编译检查，并根据检查结果修正语法问题。
- 最终回复生成位置、配置文件位置和编译检查结果。
任务要求
输入门禁
- 用户消息中必须明确提供测试用例文件路径；没有路径时停止执行，并要求用户补充测试用例文件路径。
- 用户消息中必须明确说明脚本针对的用例分层集类型；未说明时停止执行，并要求用户确认用例分层集类型。
- 可接受 Windows 绝对路径或项目相对路径；不得根据历史上下文猜测缺失路径。
- 只处理用户指定分层集类型中的用例，不跨分层自动扩展范围。
输出目录
<项目根目录>/output/ui_test_scripts/<需求版本号>/<功能标题>/<用例分层集类型>/<功能标题>_UI集成自动化脚本.py
<需求版本号> 优先从测试用例文件路径或文件内容中提取；无法提取时使用 unknown-version，并在最终回复中说明。<功能标题> 优先从测试用例文件标题或元信息中提取；无法提取时使用测试用例文件名去掉扩展名后的名称。<用例分层集类型> 使用用户明确提供的名称，保留中文语义，不自行改写为其他分层。
环境变量配置
<项目根目录>/output/ui_test_scripts/<需求版本号>/.env.local
- 版本级公共环境变量文件不存在时必须创建，且只包含以下 8 个固定配置项：
# FRONTEND_BASE_URL
# 含义：前端应用基础访问地址。
# 是否必填：是。
# 示例值：http://localhost:5173
FRONTEND_BASE_URL=
# BROWSER_TYPE
# 含义：浏览器类型，可选值为 chromium、firefox、webkit。
# 是否必填：是。
# 示例值：chromium
BROWSER_TYPE=
# BROWSER_HEADLESS
# 含义：是否以无头模式运行浏览器，可选值为 true、false。
# 是否必填：是。
# 示例值：true
BROWSER_HEADLESS=
# ELEMENT_TIMEOUT_MS
# 含义：页面元素默认等待超时时间，单位为毫秒。
# 是否必填：是。
# 示例值：10000
ELEMENT_TIMEOUT_MS=
# RESPONSE_TIMEOUT_MS
# 含义：接口响应默认等待超时时间，单位为毫秒。
# 是否必填：是。
# 示例值：15000
RESPONSE_TIMEOUT_MS=
# NAVIGATION_TIMEOUT_MS
# 含义：页面跳转默认等待超时时间，单位为毫秒。
# 是否必填：是。
# 示例值：15000
NAVIGATION_TIMEOUT_MS=
# ADMIN_USERNAME
# 含义：系统登录管理员账号。
# 是否必填：是。
# 示例值：admin
ADMIN_USERNAME=
# ADMIN_PASSWORD
# 含义：系统登录管理员密码。
# 是否必填：是。
# 示例值：admin123
ADMIN_PASSWORD=
- 脚本同级目录必须生成用例特有
.env.local，用于存放该脚本独有的特殊测试账户、业务编码、测试数据、上传文件路径或外部依赖开关。
- 脚本同级
.env.local 中每个配置项必须写明含义、是否必填和示例值；没有特有配置时保留文件并写入说明性注释。
- 生成脚本中的
RuntimeConfig 必须按优先级解析配置：先读取脚本同级 .env.local，再读取进程环境变量，最后读取版本级公共 .env.local 补齐仍为空的公共配置；同名配置以前序来源为准。
脚本结构
- 脚本必须使用 Python 语言和
pytest 框架；默认浏览器自动化库为 Playwright for Python。
- 脚本文件的基本结构必须按以下顺序组织：
模块说明 docstring
import 区
常量区
RuntimeConfig 配置读取区
通用工具函数区
Page Object 页面对象区
pytest fixtures 区
pytest test cases 区
- 模块说明 docstring 必须包含脚本标题、作者、时间、运行基础前置条件、覆盖用例列表和脚本运行方式。
- 作者统一写为
Codex-<git提交作者>；优先通过仓库 git config user.name 获取作者。
- 脚本运行方式必须包含依赖安装命令和脚本运行命令；脚本运行命令格式为：
pytest <脚本的绝对路径> -vv -rA --tb=short
- 常量区中的每个常量必须有中文注释，避免在测试函数、页面对象和工具函数中散落魔法字符串。
pytest test cases 区中的测试函数名必须带上用例编号，例如 test_tc_login_001_admin_login_success。
元素定位
- 禁止使用文本内容、CSS 类名、DOM 层级、XPath、数组下标或组件库生成的临时 class 作为元素定位依据。
- 所有可交互操作元素必须使用不重复的
data-testid 定位，包括按钮、链接、输入框、选择器、上传入口、下载入口、表格操作按钮、弹窗确认按钮、弹窗取消按钮、菜单项和页签。
data-testid 属性值必须使用英文小写短横线命名，并包含模块、页面、元素和动作语义，例如 document-list-add-button。- 前端页面缺少稳定
data-testid 时，必须先补充元素标识再编写脚本；禁止用脆弱选择器绕过缺失标识。
- 补充
data-testid 只允许增加稳定测试标识，不得修改前端样式、交互流程、接口调用或业务判断。
等待与业务完成信号
- 所有基于
data-testid 的元素，在点击、填写、读取或断言前必须显式等待目标状态。
- 点击元素前必须确认元素可见且可用；填写元素前必须确认元素可见且可编辑；读取或断言元素前必须确认元素已挂载或可见并达到预期值。
- 所有触发登录、页面跳转、接口请求、弹窗展示、列表刷新或表单保存的操作，执行后必须等待对应业务完成信号。
- 可接受的业务完成信号包括接口成功响应、URL 变化、目标页面关键元素可见、按钮状态恢复、成功提示出现或数据回显完成。
- 禁止仅依赖
domcontentloaded 或 networkidle 判断业务已完成。
登录与账户
- 脚本统一使用版本级公共配置中的系统管理员账号和密码执行 UI 登录。
- 用例涉及其他特殊测试账户时，必须把账号配置写入脚本同级
.env.local，不得硬编码在脚本中。
- 日志、断言消息和异常信息不得明文输出密码、Token、手机号或身份证等敏感信息。
用例转换
- 每个测试函数只覆盖一个测试用例，不得把多个用例合并到同一个测试函数中。
- 测试函数应尽量复用 Page Object 方法表达页面操作，避免在测试函数中堆叠底层定位细节。
- 需要离开当前系统进行验证的用例，测试函数必须使用
pytest.mark.skip 或 pytest.skip 标识跳过，并写清楚跳过原因。
- 断言必须来自可观察的 UI 状态、接口响应结果、URL 变化、下载结果或页面数据回显，不能只断言函数调用完成。
检查要求
文件检查
- 确认脚本文件已生成到指定目录。
- 确认脚本同级
.env.local 已生成，并包含每个配置项的含义、是否必填和示例值。
- 确认版本级公共
.env.local 已存在，且固定 8 项配置名称齐全。
结构检查
- 检查脚本是否按模块说明 docstring、import 区、常量区、
RuntimeConfig 配置读取区、通用工具函数区、Page Object 页面对象区、pytest fixtures 区和 pytest test cases 区的顺序组织。
- 检查模块说明 docstring 是否包含脚本标题、作者、时间、运行基础前置条件、覆盖用例列表、依赖安装命令和
pytest <脚本的绝对路径> -vv -rA --tb=short 运行命令。
- 检查测试函数名是否包含对应测试用例编号。
定位与等待检查
- 检查脚本中是否存在文本内容、CSS 类名、DOM 层级、XPath、数组下标或临时 class 定位；发现后必须改为
data-testid。
- 检查每个
data-testid 定位后的点击、填写、读取和断言是否具备显式状态等待。
- 检查登录、跳转、请求、弹窗、刷新和保存动作后是否等待业务完成信号。
- 检查离开当前系统验证的测试函数是否标识为跳过并包含原因。
编译检查
python -m py_compile <脚本的绝对路径>
- 不运行
pytest 测试脚本。
- 不启动浏览器执行 UI 流程。
- 不在脚本生成后额外检查前端代码。
Scan to join WeChat group