Playwright 浏览器自动化与端到端测试 - 跨浏览器测试框架完整指南

playwright by secondsky/claude-skills

281 周安装量

91 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/secondsky/claude-skills --skill playwright

自动化 JavaScript 框架测试

🇨🇳中文介绍

Playwright - 浏览器自动化与端到端测试

使用 Playwright 进行浏览器自动化和端到端测试的专家知识 - 一个现代化的跨浏览器测试框架。

重要提示 - 路径解析： 此技能可以安装在不同的位置。在执行命令之前，请根据加载此 SKILL.md 文件的位置确定技能目录，并在所有命令中使用该路径。将 $SKILL_DIR 替换为实际发现的路径。

常见安装路径：

插件系统：~/.claude/plugins/*/playwright/skills/playwright
手动全局安装：~/.claude/skills/playwright
项目特定：<project>/.claude/skills/playwright

关键工作流程 - 遵循以下步骤

当自动化浏览器任务时：

自动检测开发服务器 - 对于 localhost 测试，务必首先运行服务器检测：

cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

104,600 周安装

GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题

27,800 周安装

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

27,600 周安装

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  webServer: {
    command: 'bun run dev',
    url: 'http://localhost:3000',
  },
})

// /tmp/playwright-test-responsive.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自动检测

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();

  // 桌面测试
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log('Desktop - Title:', await page.title());
  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });

  // 移动端测试
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });

  await browser.close();
})();

// /tmp/playwright-test-login.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自动检测

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/login`);
  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  await page.waitForURL('**/dashboard');
  console.log('✅ Login successful, redirected to dashboard');

  await browser.close();
})();

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto('http://localhost:3000');

  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };

  for (const link of links) {
    const href = await link.getAttribute('href');
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }

  console.log(`✅ Working links: ${results.working}`);
  console.log(`❌ Broken links:`, results.broken);

  await browser.close();
})();

import { test, expect } from '@playwright/test'

test.describe('Login flow', () => {
  test('successful login', async ({ page }) => {
    await page.goto('/')
    await page.getByRole('link', { name: 'Login' }).click()
    await page.getByLabel('Email').fill('user@example.com')
    await page.getByLabel('Password').fill('password123')
    await page.getByRole('button', { name: 'Sign in' }).click()

    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible()
  })

  test('shows error for invalid credentials', async ({ page }) => {
    await page.goto('/login')
    await page.getByLabel('Email').fill('wrong@example.com')
    await page.getByLabel('Password').fill('wrongpassword')
    await page.getByRole('button', { name: 'Sign in' }).click()

    await expect(page.getByText('Invalid credentials')).toBeVisible()
  })
})

// 可见性
await expect(page.getByText('Success')).toBeVisible()
await expect(page.getByRole('button')).toBeEnabled()

// 文本
await expect(page.getByRole('heading')).toHaveText('Welcome')
await expect(page.getByRole('alert')).toContainText('error')

// 属性
await expect(page.getByRole('link')).toHaveAttribute('href', '/home')

// URL/标题
await expect(page).toHaveURL('/dashboard')
await expect(page).toHaveTitle('Dashboard')

// 数量
await expect(page.getByRole('listitem')).toHaveCount(5)

// pages/LoginPage.ts
import { Page, Locator } from '@playwright/test'

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

  constructor(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()
  }
}

// 使用
const loginPage = new LoginPage(page)
await loginPage.login('user@example.com', 'password123')

const helpers = require('./lib/helpers');

// 检测正在运行的开发服务器（关键 - 首先使用这个！）
const servers = await helpers.detectDevServers();
console.log('Found servers:', servers);

// 带重试的安全点击
await helpers.safeClick(page, 'button.submit', { retries: 3 });

// 带清除的安全输入
await helpers.safeType(page, '#username', 'testuser');

// 获取带时间戳的截图
await helpers.takeScreenshot(page, 'test-result');

// 处理 Cookie 横幅
await helpers.handleCookieBanner(page);

// 提取表格数据
const data = await helpers.extractTableData(page, 'table.results');

// 创建带有自定义标头的上下文
const context = await helpers.createContext(browser);

关键：首先检测服务器 - 在编写测试代码之前始终运行 detectDevServers()
使用 /tmp 存放测试文件 - 写入 /tmp/playwright-test-*.js，切勿写入技能目录
参数化 URL - 将检测到/提供的 URL 放入 TARGET_URL 常量
默认：可见浏览器 - 除非明确要求，否则始终使用 headless: false
优先使用基于角色的选择器 - 比 CSS 选择器更稳定
信任自动等待 - 无需手动休眠
每个测试获取新的上下文 - 自动隔离
并行运行测试 - 默认行为
模拟外部依赖 - 使用 page.route()
使用跟踪查看器 - 时间旅行调试

放慢速度： 使用 slowMo: 100 使操作可见
等待策略： 使用 waitForURL、waitForSelector、waitForLoadState 而不是固定的超时
错误处理： 始终使用 try-catch 进行稳健的自动化
控制台输出： 使用 console.log() 跟踪进度

🇺🇸English

Playwright - Browser Automation & E2E Testing

Expert knowledge for browser automation and end-to-end testing with Playwright - a modern cross-browser testing framework.

IMPORTANT - Path Resolution: This skill can be installed in different locations. Before executing commands, determine the skill directory based on where you loaded this SKILL.md file, and use that path in all commands. Replace $SKILL_DIR with the actual discovered path.

Common installation paths:

Plugin system: ~/.claude/plugins/*/playwright/skills/playwright
Manual global: ~/.claude/skills/playwright
Project-specific: <project>/.claude/skills/playwright

CRITICAL WORKFLOW - Follow These Steps

When automating browser tasks:

Auto-detect dev servers - For localhost testing, ALWAYS run server detection FIRST:
```
cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(servers => console.log(JSON.stringify(servers)))"
```
- If 1 server found : Use it automatically, inform user
- If multiple servers found : Ask user which one to test
- If no servers found : Ask for URL or offer to help start dev server
Write scripts to /tmp - NEVER write test files to skill directory; always use /tmp/playwright-test-*.js
Use visible browser by default - Always use headless: false unless user specifically requests headless mode
Parameterize URLs - Always make URLs configurable via constant at top of script
Execute via run.js - Always run: cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js

Quick Start

First-Time Setup

# Navigate to skill directory
cd $SKILL_DIR

# Install using bun (preferred)
bun run setup

# Or using npm
npm run setup:npm

This installs Playwright and Chromium browser. Only needed once.

Installation (For E2E Testing Projects)

# Using Bun (preferred)
bun add -d @playwright/test
bunx playwright install

# Using npm
npm init playwright@latest

Configuration

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  webServer: {
    command: 'bun run dev',
    url: 'http://localhost:3000',
  },
})

Browser Automation Patterns

How It Works

You describe what you want to test/automate
I auto-detect running dev servers (or ask for URL)
I write custom Playwright code in /tmp/playwright-test-*.js
I execute it via: cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js
Results displayed in real-time, browser window visible

Test a Page (Multiple Viewports)

// /tmp/playwright-test-responsive.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();

  // Desktop test
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log('Desktop - Title:', await page.title());
  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });

  // Mobile test
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });

  await browser.close();
})();

Execute: cd $SKILL_DIR && node run.js /tmp/playwright-test-responsive.js

Test Login Flow

// /tmp/playwright-test-login.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // Auto-detected

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/login`);
  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  await page.waitForURL('**/dashboard');
  console.log('✅ Login successful, redirected to dashboard');

  await browser.close();
})();

Check for Broken Links

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto('http://localhost:3000');

  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };

  for (const link of links) {
    const href = await link.getAttribute('href');
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }

  console.log(`✅ Working links: ${results.working}`);
  console.log(`❌ Broken links:`, results.broken);

  await browser.close();
})();

E2E Testing Patterns

Running Tests

# Run all tests
bunx playwright test

# Headed mode (see browser)
bunx playwright test --headed

# Specific file
bunx playwright test tests/login.spec.ts

# Debug mode
bunx playwright test --debug

# UI mode (interactive)
bunx playwright test --ui

# Specific browser
bunx playwright test --project=chromium

# Generate report
bunx playwright show-report

Writing Tests

import { test, expect } from '@playwright/test'

test.describe('Login flow', () => {
  test('successful login', async ({ page }) => {
    await page.goto('/')
    await page.getByRole('link', { name: 'Login' }).click()
    await page.getByLabel('Email').fill('user@example.com')
    await page.getByLabel('Password').fill('password123')
    await page.getByRole('button', { name: 'Sign in' }).click()

    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible()
  })

  test('shows error for invalid credentials', async ({ page }) => {
    await page.goto('/login')
    await page.getByLabel('Email').fill('wrong@example.com')
    await page.getByLabel('Password').fill('wrongpassword')
    await page.getByRole('button', { name: 'Sign in' }).click()

    await expect(page.getByText('Invalid credentials')).toBeVisible()
  })
})

Selectors (Best Practices)

// ✅ Role-based (recommended)
await page.getByRole('button', { name: 'Submit' })
await page.getByRole('link', { name: 'Home' })

// ✅ Text/Label
await page.getByText('Hello World')
await page.getByLabel('Email')

// ✅ Test ID (fallback)
await page.getByTestId('submit-button')

// ❌ Avoid CSS selectors (brittle)
await page.locator('.btn-primary')

Assertions

// Visibility
await expect(page.getByText('Success')).toBeVisible()
await expect(page.getByRole('button')).toBeEnabled()

// Text
await expect(page.getByRole('heading')).toHaveText('Welcome')
await expect(page.getByRole('alert')).toContainText('error')

// Attributes
await expect(page.getByRole('link')).toHaveAttribute('href', '/home')

// URL/Title
await expect(page).toHaveURL('/dashboard')
await expect(page).toHaveTitle('Dashboard')

// Count
await expect(page.getByRole('listitem')).toHaveCount(5)

Actions

// Clicking
await page.getByRole('button').click()
await page.getByText('File').dblclick()

// Typing
await page.getByLabel('Email').fill('user@example.com')
await page.getByLabel('Search').press('Enter')

// Selecting
await page.getByLabel('Country').selectOption('us')

// File Upload
await page.getByLabel('Upload').setInputFiles('path/to/file.pdf')

Network Mocking

test('mocks API response', async ({ page }) => {
  await page.route('**/api/users', async route => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
    })
  })

  await page.goto('/users')
  await expect(page.getByText('Test User')).toBeVisible()
})

Visual Testing

test('captures screenshot', async ({ page }) => {
  await page.goto('/')
  await page.screenshot({ path: 'screenshot.png', fullPage: true })
  await expect(page).toHaveScreenshot('homepage.png')
})

Authentication State

// Save state after login
setup('authenticate', async ({ page }) => {
  await page.goto('/login')
  await page.getByLabel('Email').fill('user@example.com')
  await page.getByLabel('Password').fill('password123')
  await page.getByRole('button', { name: 'Sign in' }).click()
  await page.context().storageState({ path: 'auth.json' })
})

// Reuse in config
use: { storageState: 'auth.json' }

Page Object Model

// pages/LoginPage.ts
import { Page, Locator } from '@playwright/test'

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

  constructor(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()
  }
}

// Usage
const loginPage = new LoginPage(page)
await loginPage.login('user@example.com', 'password123')

Available Helpers

Optional utility functions in lib/helpers.js:

const helpers = require('./lib/helpers');

// Detect running dev servers (CRITICAL - use this first!)
const servers = await helpers.detectDevServers();
console.log('Found servers:', servers);

// Safe click with retry
await helpers.safeClick(page, 'button.submit', { retries: 3 });

// Safe type with clear
await helpers.safeType(page, '#username', 'testuser');

// Take timestamped screenshot
await helpers.takeScreenshot(page, 'test-result');

// Handle cookie banners
await helpers.handleCookieBanner(page);

// Extract table data
const data = await helpers.extractTableData(page, 'table.results');

// Create context with custom headers
const context = await helpers.createContext(browser);

Custom HTTP Headers

Configure custom headers for all HTTP requests via environment variables:

# Single header (common case)
PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
  cd $SKILL_DIR && node run.js /tmp/my-script.js

# Multiple headers (JSON format)
PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
  cd $SKILL_DIR && node run.js /tmp/my-script.js

Headers are automatically applied when using helpers.createContext().

Inline Execution (Simple Tasks)

For quick one-off tasks:

cd $SKILL_DIR && node run.js "
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('http://localhost:3001');
await page.screenshot({ path: '/tmp/quick-screenshot.png', fullPage: true });
console.log('Screenshot saved');
await browser.close();
"

When to use:

Inline : Quick one-off tasks (screenshot, element check)
Files : Complex tests, reusable automation

Best Practices

CRITICAL: Detect servers FIRST - Always run detectDevServers() before writing test code
Use /tmp for test files - Write to /tmp/playwright-test-*.js, never to skill directory
Parameterize URLs - Put detected/provided URL in TARGET_URL constant
DEFAULT: Visible browser - Always use headless: false unless explicitly requested
Prefer role-based selectors - More stable than CSS selectors
Trust auto-waiting - No manual sleeps needed
Each test gets fresh context - Automatic isolation
Run tests in parallel - Default behavior
Mock external dependencies - Use page.route()
Use trace viewer - Time-travel debugging

Tips

Slow down: Use slowMo: 100 to make actions visible
Wait strategies: Use waitForURL, waitForSelector, waitForLoadState instead of fixed timeouts
Error handling: Always use try-catch for robust automation
Console output: Use console.log() to track progress

Troubleshooting

Playwright not installed:

cd $SKILL_DIR && bun run setup

Module not found: Ensure running from skill directory via run.js wrapper

Browser doesn't open: Check headless: false and ensure display available

Element not found: Add wait: await page.waitForSelector('.element', { timeout: 10000 })

When to Load References

Load references/API_REFERENCE.md when you need:

Advanced selector patterns and locator strategies
Network interception and request/response mocking
Authentication patterns and session management
Visual regression testing setup
Mobile device emulation configurations
Performance testing and metrics
Debugging techniques (trace viewer, inspector)
CI/CD pipeline integration
Accessibility testing with axe-core
Data-driven and parameterized testing
Page Object Model advanced patterns
Parallel execution strategies

Weekly Installs

281

Repository

secondsky/claude-skills

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

Installed on

gemini-cli261

opencode260

cursor255

codex254

github-copilot252

kimi-cli243

Playwright 浏览器自动化与端到端测试 - 跨浏览器测试框架完整指南

🇨🇳中文介绍

Playwright - 浏览器自动化与端到端测试

关键工作流程 - 遵循以下步骤

相关 Skills

快速开始

首次设置

安装（用于端到端测试项目）

配置

浏览器自动化模式

工作原理

测试页面（多视口）

测试登录流程

检查损坏链接

端到端测试模式

运行测试

编写测试

选择器（最佳实践）

断言

操作

网络模拟

视觉测试

认证状态

页面对象模型

可用辅助函数

自定义 HTTP 标头

内联执行（简单任务）

最佳实践

提示

故障排除

另请参阅

何时加载参考文档