┌─────────────────────────────────────────────────────────┐
│                    Playwright 应用                        │
│  ┌───────────────────────────────────────────────────┐  │
│  │            Playwright API (多语言)                  │  │
│  │   JS/TS  │  Python  │  Java  │  C#                │  │
│  └──────────┬────────────────────────────────────────┘  │
│             │ WebSocket / Pipe                           │
│  ┌──────────▼────────────────────────────────────────┐  │
│  │          Browser Server                            │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐        │  │
│  │  │ Chromium  │  │ Firefox  │  │  WebKit   │        │  │
│  │  │ (Chrome)  │  │          │  │ (Safari)  │        │  │
│  │  └──────────┘  └──────────┘  └──────────┘        │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

# 创建项目
mkdir pw-demo && cd pw-demo
npm init -y

# 安装 Playwright Test (推荐，包含测试框架)
npm init playwright@latest

# 或仅安装 Playwright 库
npm install playwright

# 下载浏览器 (通常自动执行)
npx playwright install

# 仅下载 Chromium
npx playwright install chromium

pip install playwright
playwright install            # 下载所有浏览器
playwright install chromium   # 仅下载 Chromium

<dependency>
    <groupId>com.microsoft.playwright</groupId>
    <artifactId>playwright</artifactId>
    <version>1.40.0</version>
</dependency>

mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install"

dotnet add package Microsoft.Playwright
dotnet build
pwsh bin/Debug/net8.0/playwright.ps1 install

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

(async () => {
  // 启动浏览器
  const browser = await chromium.launch({
    headless: true,
    args: ['--no-sandbox']
  });

  // 创建页面 (等同于创建 BrowserContext + Page)
  const context = await browser.newContext({
    viewport: { width: 1920, height: 1080 },
    locale: 'zh-CN',
  });
  const page = await context.newPage();

  // 导航
  await page.goto('https://example.com');

  // 获取标题
  console.log('标题:', await page.title());

  // 截图
  await page.screenshot({ path: '/tmp/pw-example.png', fullPage: true });

  // 关闭
  await browser.close();
})();

// tests/example.spec.js
const { test, expect } = require('@playwright/test');

test('首页加载正确', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});

test('搜索功能正常', async ({ page }) => {
  await page.goto('https://example.com');
  await page.fill('#search', 'Playwright');
  await page.press('#search', 'Enter');
  await expect(page.locator('.results')).toBeVisible();
});

# 运行测试
npx playwright test

# 运行指定文件
npx playwright test tests/example.spec.js

# 有头模式 (调试)
npx playwright test --headed

# UI 模式 (可视化调试)
npx playwright test --ui

# 查看报告
npx playwright show-report

// CSS 选择器
const button = page.locator('#submit-btn');
const items = page.locator('.list-item');

// XPath
const heading = page.locator('xpath=//h1');

// 文本内容
const link = page.locator('text=登录');              // 精确匹配
const link2 = page.locator('text=/log\\w+/i');       // 正则匹配
const partial = page.locator(':text("欢迎")');        // 包含文本

// 角色 (ARIA Role, 推荐)
const submitBtn = page.getByRole('button', { name: '提交' });
const heading = page.getByRole('heading', { level: 1 });
const textbox = page.getByRole('textbox', { name: '用户名' });
const link = page.getByRole('link', { name: '首页' });

// 按标签文本 (表单)
const email = page.getByLabel('邮箱地址');

// 按 placeholder
const search = page.getByPlaceholder('输入搜索关键词');

// 按测试 ID
const element = page.getByTestId('submit-button');

// 按 Alt 文本 (图片)
const logo = page.getByAltText('公司 Logo');

// 按 Title 属性
const tooltip = page.getByTitle('提示信息');

// 组合定位
const row = page.locator('tr').filter({ hasText: '张三' });
const item = page.locator('.card', { has: page.locator('.active') });

1. page.getByRole()        ← 最语义化，推荐首选
2. page.getByLabel()       ← 表单元素
3. page.getByPlaceholder() ← 输入框
4. page.getByTestId()      ← 测试专用，不受 UI 变化影响
5. page.getByText()        ← 文本匹配
6. page.locator(CSS)       ← 灵活但可能因 CSS 变化而失效
7. page.locator(XPath)     ← 最后选择

// 无需手动 waitForSelector!
await page.click('#submit-btn');   // 自动等待:
                                   // 1. 元素存在于 DOM
                                   // 2. 元素可见
                                   // 3. 元素稳定 (无动画)
                                   // 4. 元素可接收事件 (未被遮挡)
                                   // 5. 元素已启用 (未 disabled)

await page.fill('#email', 'test@example.com');  // 自动等待元素可编辑

// 断言也有自动等待
await expect(page.locator('.result')).toBeVisible();
await expect(page.locator('.item')).toHaveCount(5);
await expect(page.locator('.status')).toHaveText('完成');
await expect(page.locator('#price')).toHaveText(/^\$\d+/);

// 等待元素出现
await page.locator('#dynamic-content').waitFor({ state: 'attached' });

// 等待元素消失
await page.locator('.loading').waitFor({ state: 'detached' });

// 等待网络空闲
await page.waitForLoadState('networkidle');

// 等待特定 URL
await page.waitForURL('**/dashboard');

// 等待响应
const response = await page.waitForResponse('**/api/data');
const data = await response.json();

// 等待超时设置
await page.click('#btn', { timeout: 10000 });

// 输入文本 (自动清空)
await page.fill('#username', 'admin');
await page.fill('#password', 'secret123');

// 逐字符输入 (模拟真实用户)
await page.locator('#search').pressSequentially('Hello', { delay: 100 });

// 清空
await page.fill('#field', '');

// 选择下拉框
await page.selectOption('#country', 'CN');            // 按值
await page.selectOption('#country', { label: '中国' }); // 按标签
await page.selectOption('#country', { index: 0 });    // 按索引

// 复选框 / 单选框
await page.check('#agree');
await page.uncheck('#agree');
await page.setChecked('#agree', true);
await page.setInputFiles('#upload', '/path/to/file.pdf');        // 单文件
await page.setInputFiles('#upload', ['/file1.pdf', '/file2.pdf']); // 多文件

// 提交表单
await page.locator('#search').press('Enter');

// 点击
await page.click('#button');
await page.dblclick('#item');                 // 双击
await page.click('#button', { button: 'right' });  // 右键
await page.click('#button', { modifiers: ['Shift'] }); // Shift+点击

// 悬停
await page.hover('.dropdown-toggle');

// 拖拽
await page.locator('#source').dragTo(page.locator('#target'));

// 精确鼠标操作
await page.mouse.click(100, 200);
await page.mouse.dblclick(100, 200);
await page.mouse.move(100, 200);
await page.mouse.down();
await page.mouse.move(300, 400);
await page.mouse.up();

await page.keyboard.press('Enter');
await page.keyboard.press('Tab');
await page.keyboard.press('Control+a');
await page.keyboard.press('Control+c');
await page.keyboard.press('Control+v');
await page.keyboard.press('Escape');

// 组合键
await page.keyboard.press('Shift+KeyA');
await page.keyboard.press('Control+Shift+KeyI'); // 打开 DevTools

// 方法 1: 通过 frameLocator
const frame = page.frameLocator('#iframe-id');
await frame.locator('#inner-element').click();

// 方法 2: 获取 Frame 对象
const frameHandle = page.frame({ url: /iframe-url/ });
await frameHandle.locator('#element').click();

// 嵌套 iframe
const nested = page.frameLocator('#outer').frameLocator('#inner');
await nested.locator('#deep-element').click();

// 监听 dialog 事件
page.on('dialog', async (dialog) => {
  console.log(`弹窗类型: ${dialog.type()}`);
  console.log(`弹窗消息: ${dialog.message()}`);
  await dialog.accept();     // 确定
  // await dialog.dismiss(); // 取消
  // await dialog.accept('输入内容'); // prompt 输入
});

// 触发弹窗
await page.click('#trigger-alert');

// playwright.config.js
const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'mobile-chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'mobile-safari',
      use: { ...devices['iPhone 14'] },
    },
  ],
  fullyParallel: true,
  retries: 2,
  workers: 4,
  reporter: [['html'], ['list']],
});

# 运行所有浏览器
npx playwright test

# 仅运行 Chromium
npx playwright test --project=chromium

# 仅运行移动设备
npx playwright test --project=mobile-chrome --project=mobile-safari

import pytest
from playwright.sync_api import Page, expect

# conftest.py 或直接使用 pytest-playwright
@pytest.fixture(params=["chromium", "firefox", "webkit"])
def browser_name(request):
    return request.param

def test_homepage(page: Page):
    page.goto("https://example.com")
    expect(page).to_have_title(/Example/)

# 启动录制
npx playwright codegen https://example.com

# 指定语言
npx playwright codegen --target=python https://example.com
npx playwright codegen --target=java https://example.com

# 模拟移动设备
npx playwright codegen --device="iPhone 14" https://example.com

# 保存到文件
npx playwright codegen --output=tests/generated.spec.ts https://example.com

// 由 Playwright Codegen 自动生成
import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {
  await page.goto('https://example.com/');
  await page.getByPlaceholder('搜索').click();
  await page.getByPlaceholder('搜索').fill('playwright');
  await page.getByRole('button', { name: '搜索' }).click();
  await expect(page.getByText('搜索结果')).toBeVisible();
});

// playwright.config.js
module.exports = defineConfig({
  use: {
    trace: 'on-first-retry', // 仅在重试时记录
    // trace: 'on',          // 始终记录
    // trace: 'retain-on-failure', // 失败时保留
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
});

# 查看 Trace
npx playwright show-trace trace.zip

# 在线查看
# https://trace.playwright.dev

选择 Playwright:
  ✅ 新项目首选（现代化 API、自动等待、内置测试框架）
  ✅ 需要跨浏览器测试
  ✅ 需要录制/回放调试能力
  ✅ 需要并行测试

选择 Selenium:
  ✅ 已有 Selenium 项目（迁移成本高）
  ✅ 需要 Selenium Grid 分布式测试
  ✅ 需要最广泛的浏览器支持（旧版浏览器）

选择 Puppeteer:
  ✅ 只需 Chrome 专项操作
  ✅ 需要 CDP 底层能力（性能 Trace、协议级操作）
  ✅ Node.js 项目，不需要跨浏览器

// tests/login.spec.ts
import { test, expect } from '@playwright/test';

test.describe('用户登录', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
  });

  test('使用正确凭据登录成功', async ({ page }) => {
    await page.getByLabel('用户名').fill('admin');
    await page.getByLabel('密码').fill('password123');
    await page.getByRole('button', { name: '登录' }).click();

    // 验证跳转到首页
    await expect(page).toHaveURL(/.*dashboard/);
    await expect(page.getByText('欢迎回来')).toBeVisible();
  });

  test('错误密码显示提示', async ({ page }) => {
    await page.getByLabel('用户名').fill('admin');
    await page.getByLabel('密码').fill('wrongpassword');
    await page.getByRole('button', { name: '登录' }).click();

    // 验证错误提示
    await expect(page.locator('.error-message')).toContainText('用户名或密码错误');
  });

  test('空用户名阻止提交', async ({ page }) => {
    await page.getByLabel('密码').fill('password123');
    await page.getByRole('button', { name: '登录' }).click();

    // 验证仍在登录页
    await expect(page).toHaveURL(/.*login/);
    await expect(page.getByLabel('用户名')).toBeFocused();
  });
});