尧图网页设计 
1. 为什么“Skill”突然变成了 AI 测试的关键词先抛一个结论Skill 不是新的编程语言也不是某个厂商的专有格式它是把“一段可复用的 AI 能力”打包成标准文件结构的方法。过去半年凡是接触过 Claude Code、Codex、Cursor 或各类 AI Agent 的测试工程师都会频繁看到一个目录里放着SKILL.md文件。很多人的第一反应是“这不就是给 AI 看的说明书吗”这句话只对了一半。真正的关键点在于Skill 本质上是在给 AI 大模型“外挂记忆和工具”让 AI 不需要每次重新理解测试流程而是直接读取一套写好的方法、脚本和注意事项然后按步骤执行。传统 Web 自动化测试我们通常会经历这样一个过程用 Selenium 或 Playwright 写脚本把脚本组织成 Page Object 模式封装公共方法比如等待元素、读取数据写好测试报告重新配置 CI 流水线在本地或服务器上跑。这个过程最耗时的不是写代码而是“切换上下文”。当你从写登录用例切到写订单流程用例时你要重新回忆项目里有哪些选择器、有哪些公共 API、哪些场景容易出问题。而有了 Skill 之后流程变化非常明显AI 自动读取SKILL.md理解测试项目的目录结构和约定AI 按照 Skill 里定义的步骤直接生成完整的 Web 自动化测试脚本AI 自动调用封装好的 Playwright 公共模块测试工程师只负责评审代码、补充边界场景、运行脚本和排查失败原因。说白了Skill 降低的是“人把业务规则翻译成测试代码”的成本而不是“AI 生成代码”的成本。这也解释了为什么很多测试团队试用 AI 写自动化测试后评价两极分化用了 Skill 的团队觉得效率翻倍没用 Skill 的团队觉得 AI 总是写出“看起来对、跑起来废”的脚本。本文会直接给出一个可照抄的 Web 自动化测试 Skill 完整方案包括目录结构、SKILL.md写法、Playwright 脚本、md 文档模板、运行验证和常见坑。整篇文章不追求“包装成 100 倍效率神器”而是把一眼能用、拿到手就能跑的细节讲透。如果你是以下读者这篇文章会很有用想用 AI 辅助完成 Web 自动化测试但不知道如何约束 AI 输出质量的测试工程师在团队里负责测试工具链想沉淀一套可复用的自动化测试能力正在准备 AI 测试相关面试需要理解 Agent、Skill、代码生成这三者之间关系的候选人已经接触过 Playwright 但希望把它和 AI 工作流结合起来的开发者。2. Skill 在 AI 测试体系里的定位2.1 从 Agent 到 SkillAI 测试的三种角色要理解 Skill先得看它在 AI 测试体系里的位置。一个典型的 AI 测试 Agent 工作流里通常有三个层次层次名称作用举例第一层Agent负责任务拆解、决策、调用工具用户说“帮我跑一下登录页的自动化测试”Agent 决定用什么工具第二层Skill提供特定领域的知识、步骤、脚本模板登录测试 Skill、订单流程测试 Skill、断言规范 Skill第三层Tool / API执行具体动作Playwright 启动浏览器、读取测试报告、执行命令Agent 是大脑Skill 是操作手册Tool 是手脚。这个比喻很关键。如果只给 AI 一个 Playwright 工具它确实能写代码但它不知道你的测试项目里有哪些公共函数你期望的等待策略是什么你的环境变量从哪个文件读取哪些用例在 CI 上容易跑挂测试报告应该输出成什么格式。这些都属于“领域知识”而 Skill 就是把这些知识结构化、文件化的载体。2.2 为什么传统自动化测试方案中“测试代码”很难直接复用到 AI 场景传统测试代码的复用方式是“函数复用”和“类继承”但这套方式对 AI 并不友好。原因在于AI 不理解你的代码架构除非你告诉它。你把一个封装得很漂亮的 BasePage 类丢给 AI它可能不知道哪个方法是刷新页面哪个方法是等待元素。AI 生成代码时容易偏离团队约定。你的团队习惯用>web-test-skill/ ├── SKILL.md # Skill 的主文件AI 首先读取 ├── scripts/ │ ├── login_test.py # 登录场景的自动化脚本 │ ├── order_test.py # 订单流程的自动化脚本 │ ├── utils.py # 公共工具函数 │ └── config.py # 配置信息 ├── examples/ │ ├── quick_start.md # 快速上手文档 │ └── demo_test.py # 演示测试脚本 ├── docs/ │ ├── selector_guide.md # 元素定位规范 │ └── trouble_shooting.md # 常见问题 └── requirements.txt # Python 依赖列表从 AI 的角度看这个结构最重要的文件就是SKILL.md。AI Agent 在判断是否使用某个 Skill 时通常先读取它的描述信息然后加载主文件。如果主文件写得不清不楚AI 就会随机发挥效果自然不可控。4.1 SKILL.md 的编写要点SKILL.md是标准 Markdown 文件对 AI 来说它是“指令式文档”对团队成员来说它是“可读性极强的手册”。核心结构如下--- name: web-test-skill description: 用于 Web 端 UI 自动化测试的通用 Skill。支持登录、订单流程、页面元素断言等场景。 --- # Web 自动化测试 Skill ## 使用场景 适用于以下情况 - 需要对 Web 页面进行端到端自动化测试 - 需要生成 Playwright 脚本 - 需要排查 UI 自动化测试失败原因 ## 前置条件 1. Python 3.9 以上 2. 已安装 playwright 3. 已安装浏览器内核playwright install chromium ## 步骤 1. 分析测试需求确定测试页面和测试数据 2. 在 scripts/utils.py 中复用公共方法 3. 按照模板生成测试脚本 4. 运行测试并输出结果 ## 代码模板 参考 examples/demo_test.py ## 常见错误 - 不要使用 time.sleep 等待元素使用 Playwright 自动等待 - 不要针对动态数据写死断言使用模糊匹配需要提醒的是description字段要写得明确且克制。不要写“这个 Skill 能做所有事”而要写清楚它“擅长什么、不擅长什么”。AI 在模型层面会做工具选择描述越准确选错的概率越低。5. 完整代码实现一套可照抄的 Web 测试 Skill下面我会给出三个核心文件足够支撑你搭建第一个 Skill 并跑通示例。5.1 安装依赖与环境准备在开始之前先确认环境。推荐使用 Python 3.9 以上的虚拟环境mkdir web-test-skill cd web-test-skill python -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate pip install playwright pytest playwright install chromium这里解释一下为什么安装pytestSkill 本身不关心测试框架但 pytest 在断言失败时能提供更清晰的报错堆栈而且 AI 生成的测试用例通常基于 pytest 的断言风格两者兼容性更好。如果团队已经在用 unittest也可以替换但下面的示例以 pytest 写法为准。5.2scripts/config.py统一管理测试配置测试配置是自动化测试最容易混乱的地方。环境地址、账号、超时时间等散落在各个脚本里AI 生成的代码很容易出现“这里一个环境变量、那里一个硬编码”的问题。建议统一收敛到一个配置文件中。# 文件路径web-test-skill/scripts/config.py class TestConfig: BASE_URL https://example.com LOGIN_URL /login DEFAULT_TIMEOUT 10000 # 毫秒 DEFAULT_USERNAME test_user DEFAULT_PASSWORD test_password SCREENSHOT_DIR ./screenshots REPORT_DIR ./test-reports这是一个最简配置实际项目中你可能需要从环境变量或配置中心读取。写这个类的好处是AI 读取 Skill 后能明确知道测试环境从哪里来不会在脚本里到处写死 IP 和端口。5.3scripts/utils.py把 Playwright 的常用操作封装成公共方法公共方法的目的不是“为了封装而封装”而是给 AI 提供固定的动作原语。AI 在进行代码生成时如果发现 Skill 里已经存在open_page、click_element、fill_input、take_screenshot这样的函数它更倾向于直接调用而不是从零生成一套可能不稳定的代码。# 文件路径web-test-skill/scripts/utils.py from playwright.sync_api import Page, expect def open_page(page: Page, url: str) - None: 打开指定 URL并等待页面加载完成。 page.goto(url, wait_untilnetworkidle) def fill_input(page: Page, selector: str, value: str) - None: 填充输入框使用原生 fill 方法。 locator page.locator(selector) locator.fill(value) def click_element(page: Page, selector: str) - None: 点击元素Playwright 会自动等待元素可点击。 locator page.locator(selector) locator.click() def assert_text_visible(page: Page, text: str) - None: 断言页面上出现指定文本。 expect(page.get_by_text(text)).to_be_visible() def take_screenshot(page: Page, filename: str) - None: 保存截图便于排查失败原因。 page.screenshot(pathf./screenshots/{filename}, full_pageTrue) def login(page: Page, username: str, password: str) - None: 执行登录流程假设登录表单的 selector 如下。 open_page(page, https://example.com/login) fill_input(page, #username, username) fill_input(page, #password, password) click_element(page, #login-btn) assert_text_visible(page, Dashboard)这段代码里有几个值得注意的细节page.goto使用了wait_untilnetworkidle保证页面网络请求基本完成后再继续操作。对于大多数后台管理系统这个设置比默认的load更稳定。断言使用expect(...).to_be_visible()符合 Playwright 的推荐风格。AI 生成代码时如果我们明确在 Skill 的说明中要求“使用 Playwright 内置断言而不是assert判断元素存在”脚本的失败信息会友好很多。所有等待都依赖 Playwright 自动等待代码里看不到一个sleep这是刻意设计。5.4examples/demo_test.py一个完整的 pytest 测试用例下面给出一个最小但完整的登录测试用例用于验证 Skill 是否可用。# 文件路径web-test-skill/examples/demo_test.py import pytest from playwright.sync_api import sync_playwright from scripts.config import TestConfig from scripts.utils import login, assert_text_visible, take_screenshot pytest.fixture(scopemodule) def browser_page(): with sync_playwright() as p: browser p.chromium.launch(headlessTrue) context browser.new_context(viewport{width: 1280, height: 720}) page context.new_page() yield page browser.close() def test_login_success(browser_page): 验证正确账号密码可以登录成功。 page browser_page login(page, TestConfig.DEFAULT_USERNAME, TestConfig.DEFAULT_PASSWORD) assert_text_visible(page, Dashboard) def test_login_failed_with_wrong_password(browser_page): 验证错误密码时登录失败并出现错误提示。 page browser_page login(page, TestConfig.DEFAULT_USERNAME, wrong_password) assert_text_visible(page, Invalid username or password)这个示例里用pytest的 fixture 来管理浏览器生命周期避免在每个用例里重复写 Playwright 启动代码。对于 Skill 来说这种写法还有另一个好处AI 生成的多个测试用例可以直接套用同一个 fixture而不是每次复制一长串启动代码。5.5SKILL.md的完整写法为了让 AI 能正确调用上面的脚本SKILL.md需要写得足够精确。下面是一份可以直接使用的模板--- name: web-test-skill description: Playwright Web 自动化测试 Skill。用于生成登录、订单、页面断言等端到端测试脚本并指导 AI 使用 scripts/utils.py 中的公共方法。 --- # Web 自动化测试 Skill ## 使用场景 - 针对 Web 页面的端到端自动化测试 - 需要快速生成可运行的 Playwright 测试脚本 - 需要判断测试失败原因并处理 ## 环境要求 - Python 3.9 - Playwright 1.x - Chromium 浏览器内核 ## 核心规则 1. 优先复用 scripts/utils.py 中的函数不要从零生成浏览器操作代码。 2. 元素定位优先使用 data-testid、id、role不要使用非常长的 CSS 路径。 3. 禁止使用 time.sleep()等待逻辑统一交给 Playwright 自动等待。 4. 测试数据从 scripts/config.py 中读取不要硬编码账号密码。 5. 每个测试用例结束前建议调用 take_screenshot 保存一张截图。 ## 标准步骤 1. 分析测试需求确定测试场景。 2. 检查 scripts/config.py 中配置是否正确。 3. 编写测试用例复用 scripts/utils.py 中的方法。 4. 使用 pytest -s examples/demo_test.py 运行验证。 5. 如果用例失败检查 screenshots/ 目录下的截图。 ## 示例代码路径 - examples/demo_test.py登录成功/失败用例 - examples/quick_start.md快速上手文档如果你是在 Claude Code、Cursor 或 Codex 中使用这个 Skill建议把整个目录放在项目根目录下的.agent/skills/web-test-skill/或.cursor/skills/等约定位置。不同工具的读取路径不一样但核心文件结构保持一致就行。6. 如何验证 Skill 是否“真的可用”很多团队搭建 Skill 后遇到的第一个问题是AI 虽然能读取 Skill但生成的测试脚本仍然五花八门。这通常不是模型问题而是验证方式有问题。下面是推荐的验证流程从“最小可用”逐步到“业务可用”。6.1 第一步让 AI 生成一个最简单的用例在已配置 Skill 的 IDE 或命令行工具里给 AI 输入这样一条指令使用 web-test-skill生成一个检查首页标题的测试用例。预期结果是 AI 生成如下风格代码或直接读取示例后输出路径def test_homepage_title(browser_page): page browser_page page.goto(https://example.com) assert page.title() Example Domain如果 AI 没有参考 Skill 里的utils.py而是自己写了一大段 Playwright 代码说明 Skill 的调用机制没有生效需要检查 SKILL.md 的description是否被正确索引。6.2 第二步让 AI 生成一个包含登录的用例继续输入使用 web-test-skill生成登录成功后跳转 Dashboard 的用例并使用 utils 中的 login 方法。然后运行cd web-test-skill pytest examples/demo_test.py -s --tbshort预期输出collected 2 items examples/demo_test.py::test_login_success PASSED examples/demo_test.py::test_login_failed_with_wrong_password PASSED如果测试失败优先查看screenshots/目录下的截图。截图能直观反映页面当时的状态比看一堆 DOM 报错更高效。6.3 第三步检查 AI 输出的代码是否遵守约定这一步容易被忽略。有时测试通过了但代码质量并不符合团队规范。关键检查项包括有没有使用time.sleep()有没有硬编码 URL 和账号密码有没有直接使用.click()而不是.click(forceTrue)后者通常意味着定位器有问题有没有在测试结束后关闭浏览器上下文有没有输出清晰的中文或英文步骤说明。如果 AI 生成的代码不满足这些要求不要立刻责怪 AI而是检查SKILL.md的规则写得更明确。Skill 本质上像面向 AI 的编码规范越是把规则写进文件输出质量越稳定。7. 常见问题与排查思路问题现象可能原因排查方式解决方案AI 不读取 Skill 直接生成代码SKILL.md 的 description 不匹配当前任务查看工具日志里 Skill 是否被加载将 description 改成更贴合实际任务的描述比如“Web 自动化测试生成与执行”脚本运行报locator.click()超时页面元素被遮挡或需要滚动到可见区域查看截图确认元素状态改用scroll_into_view_if_needed()或使用role定位测试登录时一直失败但手动操作正常验证码、动态 Token 或前端加密干扰抓取点击登录按钮时的网络请求在测试环境禁用验证码或把动态数据用测试接口 mockAI 生成的代码总用time.sleep()Skill 中没有明确禁用规则检查 SKILL.md 是否写明禁止time.sleep在规则里增加“等待统一交给 Playwright 自动等待”测试用例依赖执行顺序单独运行就失败用例之间有状态依赖用 pytest 的--pdb定位失败点拆分用例每条用例独立建 context多浏览器跑测试时 webkit 失败WebKit 内核环境未安装运行playwright install webkit先统一只在 chromium 上跑稳定后再扩充这里特别想强调表格里第二行的问题。很多初学者遇到click超时就直接加time.sleep(5)这会让问题更隐蔽。正确做法是先截图看元素是否在视口中、是否被弹窗遮挡。Playwright 的定位器已经包含自动滚动和等待机制如果仍然超时大概率是页面本身有异常而不是等待时间不够。8. Skill 落地到团队的最佳实践8.1 不要追求“一个 Skill 覆盖所有测试场景”测试团队最常见的一个误区是试图把接口测试、UI 测试、性能测试全塞进一个 Skill 里。这样做的结果往往是 SKILL.md 越来越长AI 的选择越来越混乱。建议按场景拆成多个 Skillweb-ui-test-skill负责端到端 UI 测试api-test-skill负责接口自动化测试test-data-gen-skill负责测试数据生成。每个 Skill 只做好一件事。AI Agent 会根据任务描述自动选择合适的 Skill这比让一个超大 Skill 强行处理所有场景可靠得多。8.2 SKILL.md 要版本化并纳入 Code ReviewSkill 的更新会影响所有 AI 生成的代码因此应该像普通源码一样管理。团队里最好是测试架构师或资深测试开发负责维护 Skill 文件每次改动都要说明“为什么改”。比如新增了一条“禁止在断言中使用模糊文本”的规则就应该在 Commit Message 里写清楚是因为某个用例误判了页面上的两处相似文本才加这条约束。8.3 用示例代码而不是描述来约束 AIAI 对示例代码的模仿能力远强于对抽象规则的理解。如果你的团队希望所有测试脚本都使用> AI测试实战：用Skill+Playwright构建Web自动化测试体系
1. 为什么“Skill”突然变成了 AI 测试的关键词先抛一个结论Skill 不是新的编程语言也不是某个厂商的专有格式它是把“一段可复用的 AI 能力”打包成标准文件结构的方法。过去半年凡是接触过 Claude Code、Codex、Cursor 或各类 AI Agent 的测试工程师都会频繁看到一个目录里放着SKILL.md文件。很多人的第一反应是“这不就是给 AI 看的说明书吗”这句话只对了一半。真正的关键点在于Skill 本质上是在给 AI 大模型“外挂记忆和工具”让 AI 不需要每次重新理解测试流程而是直接读取一套写好的方法、脚本和注意事项然后按步骤执行。传统 Web 自动化测试我们通常会经历这样一个过程用 Selenium 或 Playwright 写脚本把脚本组织成 Page Object 模式封装公共方法比如等待元素、读取数据写好测试报告重新配置 CI 流水线在本地或服务器上跑。这个过程最耗时的不是写代码而是“切换上下文”。当你从写登录用例切到写订单流程用例时你要重新回忆项目里有哪些选择器、有哪些公共 API、哪些场景容易出问题。而有了 Skill 之后流程变化非常明显AI 自动读取SKILL.md理解测试项目的目录结构和约定AI 按照 Skill 里定义的步骤直接生成完整的 Web 自动化测试脚本AI 自动调用封装好的 Playwright 公共模块测试工程师只负责评审代码、补充边界场景、运行脚本和排查失败原因。说白了Skill 降低的是“人把业务规则翻译成测试代码”的成本而不是“AI 生成代码”的成本。这也解释了为什么很多测试团队试用 AI 写自动化测试后评价两极分化用了 Skill 的团队觉得效率翻倍没用 Skill 的团队觉得 AI 总是写出“看起来对、跑起来废”的脚本。本文会直接给出一个可照抄的 Web 自动化测试 Skill 完整方案包括目录结构、SKILL.md写法、Playwright 脚本、md 文档模板、运行验证和常见坑。整篇文章不追求“包装成 100 倍效率神器”而是把一眼能用、拿到手就能跑的细节讲透。如果你是以下读者这篇文章会很有用想用 AI 辅助完成 Web 自动化测试但不知道如何约束 AI 输出质量的测试工程师在团队里负责测试工具链想沉淀一套可复用的自动化测试能力正在准备 AI 测试相关面试需要理解 Agent、Skill、代码生成这三者之间关系的候选人已经接触过 Playwright 但希望把它和 AI 工作流结合起来的开发者。2. Skill 在 AI 测试体系里的定位2.1 从 Agent 到 SkillAI 测试的三种角色要理解 Skill先得看它在 AI 测试体系里的位置。一个典型的 AI 测试 Agent 工作流里通常有三个层次层次名称作用举例第一层Agent负责任务拆解、决策、调用工具用户说“帮我跑一下登录页的自动化测试”Agent 决定用什么工具第二层Skill提供特定领域的知识、步骤、脚本模板登录测试 Skill、订单流程测试 Skill、断言规范 Skill第三层Tool / API执行具体动作Playwright 启动浏览器、读取测试报告、执行命令Agent 是大脑Skill 是操作手册Tool 是手脚。这个比喻很关键。如果只给 AI 一个 Playwright 工具它确实能写代码但它不知道你的测试项目里有哪些公共函数你期望的等待策略是什么你的环境变量从哪个文件读取哪些用例在 CI 上容易跑挂测试报告应该输出成什么格式。这些都属于“领域知识”而 Skill 就是把这些知识结构化、文件化的载体。2.2 为什么传统自动化测试方案中“测试代码”很难直接复用到 AI 场景传统测试代码的复用方式是“函数复用”和“类继承”但这套方式对 AI 并不友好。原因在于AI 不理解你的代码架构除非你告诉它。你把一个封装得很漂亮的 BasePage 类丢给 AI它可能不知道哪个方法是刷新页面哪个方法是等待元素。AI 生成代码时容易偏离团队约定。你的团队习惯用>web-test-skill/ ├── SKILL.md # Skill 的主文件AI 首先读取 ├── scripts/ │ ├── login_test.py # 登录场景的自动化脚本 │ ├── order_test.py # 订单流程的自动化脚本 │ ├── utils.py # 公共工具函数 │ └── config.py # 配置信息 ├── examples/ │ ├── quick_start.md # 快速上手文档 │ └── demo_test.py # 演示测试脚本 ├── docs/ │ ├── selector_guide.md # 元素定位规范 │ └── trouble_shooting.md # 常见问题 └── requirements.txt # Python 依赖列表从 AI 的角度看这个结构最重要的文件就是SKILL.md。AI Agent 在判断是否使用某个 Skill 时通常先读取它的描述信息然后加载主文件。如果主文件写得不清不楚AI 就会随机发挥效果自然不可控。4.1 SKILL.md 的编写要点SKILL.md是标准 Markdown 文件对 AI 来说它是“指令式文档”对团队成员来说它是“可读性极强的手册”。核心结构如下--- name: web-test-skill description: 用于 Web 端 UI 自动化测试的通用 Skill。支持登录、订单流程、页面元素断言等场景。 --- # Web 自动化测试 Skill ## 使用场景 适用于以下情况 - 需要对 Web 页面进行端到端自动化测试 - 需要生成 Playwright 脚本 - 需要排查 UI 自动化测试失败原因 ## 前置条件 1. Python 3.9 以上 2. 已安装 playwright 3. 已安装浏览器内核playwright install chromium ## 步骤 1. 分析测试需求确定测试页面和测试数据 2. 在 scripts/utils.py 中复用公共方法 3. 按照模板生成测试脚本 4. 运行测试并输出结果 ## 代码模板 参考 examples/demo_test.py ## 常见错误 - 不要使用 time.sleep 等待元素使用 Playwright 自动等待 - 不要针对动态数据写死断言使用模糊匹配需要提醒的是description字段要写得明确且克制。不要写“这个 Skill 能做所有事”而要写清楚它“擅长什么、不擅长什么”。AI 在模型层面会做工具选择描述越准确选错的概率越低。5. 完整代码实现一套可照抄的 Web 测试 Skill下面我会给出三个核心文件足够支撑你搭建第一个 Skill 并跑通示例。5.1 安装依赖与环境准备在开始之前先确认环境。推荐使用 Python 3.9 以上的虚拟环境mkdir web-test-skill cd web-test-skill python -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate pip install playwright pytest playwright install chromium这里解释一下为什么安装pytestSkill 本身不关心测试框架但 pytest 在断言失败时能提供更清晰的报错堆栈而且 AI 生成的测试用例通常基于 pytest 的断言风格两者兼容性更好。如果团队已经在用 unittest也可以替换但下面的示例以 pytest 写法为准。5.2scripts/config.py统一管理测试配置测试配置是自动化测试最容易混乱的地方。环境地址、账号、超时时间等散落在各个脚本里AI 生成的代码很容易出现“这里一个环境变量、那里一个硬编码”的问题。建议统一收敛到一个配置文件中。# 文件路径web-test-skill/scripts/config.py class TestConfig: BASE_URL https://example.com LOGIN_URL /login DEFAULT_TIMEOUT 10000 # 毫秒 DEFAULT_USERNAME test_user DEFAULT_PASSWORD test_password SCREENSHOT_DIR ./screenshots REPORT_DIR ./test-reports这是一个最简配置实际项目中你可能需要从环境变量或配置中心读取。写这个类的好处是AI 读取 Skill 后能明确知道测试环境从哪里来不会在脚本里到处写死 IP 和端口。5.3scripts/utils.py把 Playwright 的常用操作封装成公共方法公共方法的目的不是“为了封装而封装”而是给 AI 提供固定的动作原语。AI 在进行代码生成时如果发现 Skill 里已经存在open_page、click_element、fill_input、take_screenshot这样的函数它更倾向于直接调用而不是从零生成一套可能不稳定的代码。# 文件路径web-test-skill/scripts/utils.py from playwright.sync_api import Page, expect def open_page(page: Page, url: str) - None: 打开指定 URL并等待页面加载完成。 page.goto(url, wait_untilnetworkidle) def fill_input(page: Page, selector: str, value: str) - None: 填充输入框使用原生 fill 方法。 locator page.locator(selector) locator.fill(value) def click_element(page: Page, selector: str) - None: 点击元素Playwright 会自动等待元素可点击。 locator page.locator(selector) locator.click() def assert_text_visible(page: Page, text: str) - None: 断言页面上出现指定文本。 expect(page.get_by_text(text)).to_be_visible() def take_screenshot(page: Page, filename: str) - None: 保存截图便于排查失败原因。 page.screenshot(pathf./screenshots/{filename}, full_pageTrue) def login(page: Page, username: str, password: str) - None: 执行登录流程假设登录表单的 selector 如下。 open_page(page, https://example.com/login) fill_input(page, #username, username) fill_input(page, #password, password) click_element(page, #login-btn) assert_text_visible(page, Dashboard)这段代码里有几个值得注意的细节page.goto使用了wait_untilnetworkidle保证页面网络请求基本完成后再继续操作。对于大多数后台管理系统这个设置比默认的load更稳定。断言使用expect(...).to_be_visible()符合 Playwright 的推荐风格。AI 生成代码时如果我们明确在 Skill 的说明中要求“使用 Playwright 内置断言而不是assert判断元素存在”脚本的失败信息会友好很多。所有等待都依赖 Playwright 自动等待代码里看不到一个sleep这是刻意设计。5.4examples/demo_test.py一个完整的 pytest 测试用例下面给出一个最小但完整的登录测试用例用于验证 Skill 是否可用。# 文件路径web-test-skill/examples/demo_test.py import pytest from playwright.sync_api import sync_playwright from scripts.config import TestConfig from scripts.utils import login, assert_text_visible, take_screenshot pytest.fixture(scopemodule) def browser_page(): with sync_playwright() as p: browser p.chromium.launch(headlessTrue) context browser.new_context(viewport{width: 1280, height: 720}) page context.new_page() yield page browser.close() def test_login_success(browser_page): 验证正确账号密码可以登录成功。 page browser_page login(page, TestConfig.DEFAULT_USERNAME, TestConfig.DEFAULT_PASSWORD) assert_text_visible(page, Dashboard) def test_login_failed_with_wrong_password(browser_page): 验证错误密码时登录失败并出现错误提示。 page browser_page login(page, TestConfig.DEFAULT_USERNAME, wrong_password) assert_text_visible(page, Invalid username or password)这个示例里用pytest的 fixture 来管理浏览器生命周期避免在每个用例里重复写 Playwright 启动代码。对于 Skill 来说这种写法还有另一个好处AI 生成的多个测试用例可以直接套用同一个 fixture而不是每次复制一长串启动代码。5.5SKILL.md的完整写法为了让 AI 能正确调用上面的脚本SKILL.md需要写得足够精确。下面是一份可以直接使用的模板--- name: web-test-skill description: Playwright Web 自动化测试 Skill。用于生成登录、订单、页面断言等端到端测试脚本并指导 AI 使用 scripts/utils.py 中的公共方法。 --- # Web 自动化测试 Skill ## 使用场景 - 针对 Web 页面的端到端自动化测试 - 需要快速生成可运行的 Playwright 测试脚本 - 需要判断测试失败原因并处理 ## 环境要求 - Python 3.9 - Playwright 1.x - Chromium 浏览器内核 ## 核心规则 1. 优先复用 scripts/utils.py 中的函数不要从零生成浏览器操作代码。 2. 元素定位优先使用 data-testid、id、role不要使用非常长的 CSS 路径。 3. 禁止使用 time.sleep()等待逻辑统一交给 Playwright 自动等待。 4. 测试数据从 scripts/config.py 中读取不要硬编码账号密码。 5. 每个测试用例结束前建议调用 take_screenshot 保存一张截图。 ## 标准步骤 1. 分析测试需求确定测试场景。 2. 检查 scripts/config.py 中配置是否正确。 3. 编写测试用例复用 scripts/utils.py 中的方法。 4. 使用 pytest -s examples/demo_test.py 运行验证。 5. 如果用例失败检查 screenshots/ 目录下的截图。 ## 示例代码路径 - examples/demo_test.py登录成功/失败用例 - examples/quick_start.md快速上手文档如果你是在 Claude Code、Cursor 或 Codex 中使用这个 Skill建议把整个目录放在项目根目录下的.agent/skills/web-test-skill/或.cursor/skills/等约定位置。不同工具的读取路径不一样但核心文件结构保持一致就行。6. 如何验证 Skill 是否“真的可用”很多团队搭建 Skill 后遇到的第一个问题是AI 虽然能读取 Skill但生成的测试脚本仍然五花八门。这通常不是模型问题而是验证方式有问题。下面是推荐的验证流程从“最小可用”逐步到“业务可用”。6.1 第一步让 AI 生成一个最简单的用例在已配置 Skill 的 IDE 或命令行工具里给 AI 输入这样一条指令使用 web-test-skill生成一个检查首页标题的测试用例。预期结果是 AI 生成如下风格代码或直接读取示例后输出路径def test_homepage_title(browser_page): page browser_page page.goto(https://example.com) assert page.title() Example Domain如果 AI 没有参考 Skill 里的utils.py而是自己写了一大段 Playwright 代码说明 Skill 的调用机制没有生效需要检查 SKILL.md 的description是否被正确索引。6.2 第二步让 AI 生成一个包含登录的用例继续输入使用 web-test-skill生成登录成功后跳转 Dashboard 的用例并使用 utils 中的 login 方法。然后运行cd web-test-skill pytest examples/demo_test.py -s --tbshort预期输出collected 2 items examples/demo_test.py::test_login_success PASSED examples/demo_test.py::test_login_failed_with_wrong_password PASSED如果测试失败优先查看screenshots/目录下的截图。截图能直观反映页面当时的状态比看一堆 DOM 报错更高效。6.3 第三步检查 AI 输出的代码是否遵守约定这一步容易被忽略。有时测试通过了但代码质量并不符合团队规范。关键检查项包括有没有使用time.sleep()有没有硬编码 URL 和账号密码有没有直接使用.click()而不是.click(forceTrue)后者通常意味着定位器有问题有没有在测试结束后关闭浏览器上下文有没有输出清晰的中文或英文步骤说明。如果 AI 生成的代码不满足这些要求不要立刻责怪 AI而是检查SKILL.md的规则写得更明确。Skill 本质上像面向 AI 的编码规范越是把规则写进文件输出质量越稳定。7. 常见问题与排查思路问题现象可能原因排查方式解决方案AI 不读取 Skill 直接生成代码SKILL.md 的 description 不匹配当前任务查看工具日志里 Skill 是否被加载将 description 改成更贴合实际任务的描述比如“Web 自动化测试生成与执行”脚本运行报locator.click()超时页面元素被遮挡或需要滚动到可见区域查看截图确认元素状态改用scroll_into_view_if_needed()或使用role定位测试登录时一直失败但手动操作正常验证码、动态 Token 或前端加密干扰抓取点击登录按钮时的网络请求在测试环境禁用验证码或把动态数据用测试接口 mockAI 生成的代码总用time.sleep()Skill 中没有明确禁用规则检查 SKILL.md 是否写明禁止time.sleep在规则里增加“等待统一交给 Playwright 自动等待”测试用例依赖执行顺序单独运行就失败用例之间有状态依赖用 pytest 的--pdb定位失败点拆分用例每条用例独立建 context多浏览器跑测试时 webkit 失败WebKit 内核环境未安装运行playwright install webkit先统一只在 chromium 上跑稳定后再扩充这里特别想强调表格里第二行的问题。很多初学者遇到click超时就直接加time.sleep(5)这会让问题更隐蔽。正确做法是先截图看元素是否在视口中、是否被弹窗遮挡。Playwright 的定位器已经包含自动滚动和等待机制如果仍然超时大概率是页面本身有异常而不是等待时间不够。8. Skill 落地到团队的最佳实践8.1 不要追求“一个 Skill 覆盖所有测试场景”测试团队最常见的一个误区是试图把接口测试、UI 测试、性能测试全塞进一个 Skill 里。这样做的结果往往是 SKILL.md 越来越长AI 的选择越来越混乱。建议按场景拆成多个 Skillweb-ui-test-skill负责端到端 UI 测试api-test-skill负责接口自动化测试test-data-gen-skill负责测试数据生成。每个 Skill 只做好一件事。AI Agent 会根据任务描述自动选择合适的 Skill这比让一个超大 Skill 强行处理所有场景可靠得多。8.2 SKILL.md 要版本化并纳入 Code ReviewSkill 的更新会影响所有 AI 生成的代码因此应该像普通源码一样管理。团队里最好是测试架构师或资深测试开发负责维护 Skill 文件每次改动都要说明“为什么改”。比如新增了一条“禁止在断言中使用模糊文本”的规则就应该在 Commit Message 里写清楚是因为某个用例误判了页面上的两处相似文本才加这条约束。8.3 用示例代码而不是描述来约束 AIAI 对示例代码的模仿能力远强于对抽象规则的理解。如果你的团队希望所有测试脚本都使用>