前言¶

在 Cursor、Claude Code 等环境里让模型写 Playwright 测试时，常见问题不是「能不能写出 click 和 fill」，而是执行目标没定清（本地还是云端）、选择器脆弱、断言不用 Web-First 导致偶发失败，以及套件变大后缺少 Page Object Model（POM）结构。OpenAI 生态里也有与 Playwright 相关的 CLI Skill，更偏向通用浏览器自动化；playwright-skill 由 TestMu AI 维护，定位是测试代码生成：按语言与范围产出可维护的 E2E，并覆盖本地运行与 TestMu AI（原 LambdaTest）云端矩阵。

下面介绍这个 Skill 的定位、能力边界，以及资料中给出的典型工作流与代码形态。

这是什么¶

• 名称：playwright-skill
• 类别：e2e-testing
• 许可：MIT
• 维护方：TestMu AI（metadata.author）
• 版本：1.0（见 Skill 元数据）
• 官方目录：https://github.com/LambdaTest/agent-skills/tree/main/playwright-skill

Skill 的 description 写明：生成生产级 Playwright 自动化脚本与 E2E 测试，语言支持 TypeScript、JavaScript、Python、Java、C#；可在本地执行，也可在 TestMu AI 云端覆盖 3000+ 浏览器 / 操作系统组合及真机。适合在用户提到 Playwright、E2E、跨浏览器、云端、TestMu、LambdaTest、移动端真机、不稳定测试调试、API Mock、视觉回归等场景时启用（具体触发词见官方 SKILL.md 中的 Triggers 列表）。

核心功能¶

执行目标与范围分流¶

写代码前，Skill 要求先判断三类决策（官方 Step 1–3）：

1. 执行目标：未提云端 → 默认本地标准 playwright.config；提到 cloud / TestMu / LambdaTest / 跨浏览器 / 真机 → 走云端集成（reference/cloud-integration.md）；本地无法实现的组合（如 Windows 上的 Safari）→ 建议云端。HyperExecute、SmartUI 分别转交 hyperexecute-skill、smartui-skill。
2. 语言：默认 TypeScript；可按 JS、Python、Java、C# 信号选用对应 reference（如 python-patterns.md、java-patterns.md 等）。
3. 输出范围：一次性脚本、贴合现有项目的单测、全新套件脚手架（scripts/scaffold-project.sh）、修复 flaky、API Mock、移动端测试等，各有对应 reference。

TypeScript 默认模式下的工程约定¶

• 选择器优先级：getByRole → getByLabel → getByPlaceholder → getByText → getByTestId；避免裸 CSS/XPath（第三方组件除外）。
• 断言：使用 Web-First 的 expect(locator)，利用自动重试；避免先 textContent 再 expect 的竞态写法。
• 反模式清单：禁止 waitForTimeout、禁止在断言外包 try/catch、测试间不共享可变状态等（见官方 Anti-Patterns 表）。
• POM：超过 3 个用例的项目应使用 Page Object Model，完整模式见 reference/page-object-model.md。

本地与云端配置¶

本地示例 playwright.config.ts 包含 testDir、retries、reporter、projects（chromium / firefox / webkit / 移动端 profile）、webServer 等，资料中给出了完整模板。

云端在 TestMu AI 上需设置环境变量 LT_USERNAME、LT_ACCESS_KEY。支持通过 CDP chromium.connect 连接 wss://cdp.lambdatest.com/playwright，或在 playwright.config.ts 的 projects 里配置如 chrome:latest:Windows 11@lambdatest 后执行：

npx playwright test --project="chrome:latest:Windows 11@lambdatest"

云端用例默认在平台上显示为 Completed，需在 teardown 中通过 lambdatest_action: setTestStatus 上报 pass/fail；使用 reference/cloud-integration.md 中的 fixture 可自动处理。

生成后的校验流程¶

官方 Validation Workflow：

1. Validate config:  python scripts/validate-config.py playwright.config.ts
2. If errors → fix → re-validate
3. Run locally:      npx playwright test --project=chromium
4. If cloud:         npx playwright test --project="chrome:latest:Windows 11@lambdatest"
5. If failures → check reference/debugging-flaky.md

安装与启用¶

本 Skill 采用通用 SKILL.md 元数据格式（name、description、languages、category、metadata 等），仓库路径为 agent-skills/playwright-skill。各 Agent 产品将 Skill 目录或清单挂载到工作区的具体命令，以你所用工具的官方文档为准；本次资料未提供针对 Cursor、Codex CLI、Claude Code 的统一安装命令，此处不臆造步骤。启用后，模型应按 Skill 内 Step 1–3 与 reference 链接组织输出。

典型用法示例¶

Page Object：登录页¶

// pages/login.page.ts
import { Page, Locator } from '@playwright/test';

export class LoginPage {
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;

  constructor(private page: Page) {
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}

Web-First 断言¶

await expect(page.getByRole('heading')).toBeVisible();
await expect(page.getByRole('alert')).toHaveText('Saved');
await expect(page).toHaveURL('/dashboard');

云端 CDP 连接（片段）¶

const capabilities = {
  browserName: 'Chrome',
  browserVersion: 'latest',
  'LT:Options': {
    platform: 'Windows 11',
    build: 'Playwright Build',
    name: 'Playwright Test',
    user: process.env.LT_USERNAME,
    accessKey: process.env.LT_ACCESS_KEY,
    network: true,
    video: true,
    console: true,
  },
};

const browser = await chromium.connect({
  wsEndpoint: `wss://cdp.lambdatest.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
});

本地冒烟常用：

npx playwright test --project=chromium

适用场景与注意¶

适合：需要从零或增量生成 Playwright E2E、希望默认 TypeScript + POM + Web-First 断言；要在本机与 TestMu AI 云端之间切换或做跨浏览器 / 真机矩阵；需要 flaky 调试、API Mock、移动端测试等专题时按 reference 展开。

注意：

• 视觉回归、大规模并行 HyperExecute 不在本 Skill 主路径内，应转交对应 Skill。
• 云端测试务必配置账号环境变量并上报测试状态，否则平台状态与真实结果可能不一致。
• 生成配置后应跑 scripts/validate-config.py，再按目标 project 执行测试。

结尾¶

playwright-skill 把「执行环境、语言、套件范围」前置为明确步骤，并把选择器、断言、POM、本地 playwright.config 与 TestMu AI 云端 CDP / project 写法固化进 Skill，适合作为在 Agent 里系统化产出 Playwright E2E 的参考实现。官方仓库：

https://github.com/LambdaTest/agent-skills/tree/main/playwright-skill