前言¶

在 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