Playwright

エンジニアのためのWebチートシート

インストール

• Playwrightのセットアップ方法です。

  # Create new project with Playwright
  npm init playwright@latest
  
  # Or add to existing project
  npm install -D @playwright/test
  npx playwright install
  

CSS / XPath セレクター

• 推奨ロケーターで対応できない場合に使用します。

  // CSS selector
  page.locator('.submit-button')
  page.locator('#email-input')
  page.locator('[data-cy="login"]')
  page.locator('article >> .title')
  
  // XPath
  page.locator('xpath=//button[@type="submit"]')
  
  // nth element
  page.locator('.item').nth(2)
  page.locator('.item').first()
  page.locator('.item').last()

ロケーターの連鎖

• ロケーターをチェインして絞り込むパターンです。

  // Filter by text
  page.getByRole('listitem')
    .filter({ hasText: 'Product' })
  
  // Filter by child locator
  page.getByRole('listitem')
    .filter({
      has: page.getByRole('heading', { name: 'Title' })
    })
  
  // Chain locators
  page.getByRole('dialog')
    .getByRole('button', { name: 'OK' })
  
  // Filter + action
  page.getByRole('row')
    .filter({ hasText: 'admin' })
    .getByRole('button', { name: 'Edit' })
    .click()

テスト構造

• @playwright/test の基本的なテスト構造です。

  import { test, expect } from '@playwright/test';
  
  test.describe('Login', () => {
    test('valid credentials', async ({ page }) => {
      await page.goto('/login');
      await page.getByLabel('Email').fill('user@test.com');
      await page.getByLabel('Password').fill('pass123');
      await page.getByRole('button', { name: 'Login' }).click();
      await expect(page).toHaveURL('/dashboard');
    });
  
    test('invalid credentials', async ({ page }) => {
      await page.goto('/login');
      await page.getByLabel('Email').fill('wrong@test.com');
      await page.getByLabel('Password').fill('wrong');
      await page.getByRole('button', { name: 'Login' }).click();
      await expect(page.getByText('Invalid credentials')).toBeVisible();
    });
  });

カスタムFixtures

• 再利用可能なセットアップロジックを定義するパターンです。

  import { test as base } from '@playwright/test';
  
  const test = base.extend<{ loggedInPage: Page }>({
    loggedInPage: async ({ page }, use) => {
      await page.goto('/login');
      await page.getByLabel('Email').fill('admin@test.com');
      await page.getByLabel('Password').fill('admin');
      await page.getByRole('button', { name: 'Login' }).click();
      await use(page);
    },
  });

  // Use fixture in test
  test('dashboard', async ({ loggedInPage }) => {
    await expect(loggedInPage).toHaveURL('/dashboard');
  });

テスト制御

• テストのスキップや条件付き実行のパターンです。

  // Skip a test
  test.skip('feature not ready', async () => {});
  
  // Run only this test
  test.only('debug this', async ({ page }) => {});
  
  // Conditional skip
  test('mobile only', async ({ page, isMobile }) => {
    test.skip(!isMobile, 'Mobile only test');
    // ...
  });
  
  // Slow test (3x timeout)
  test('complex flow', async ({ page }) => {
    test.slow();
    // ...
  });

基本設定

• playwright.config.ts の主要な設定項目です。

  // playwright.config.ts
  import { defineConfig, devices } from
    '@playwright/test';
  
  export default defineConfig({
    testDir: './tests',
    timeout: 30_000,
    retries: process.env.CI ? 2 : 0,
    workers: process.env.CI ? 1 : undefined,
    fullyParallel: true,
    reporter: [
      ['html'],
      ['json', { outputFile: 'results.json' }],
    ],
    use: {
      baseURL: 'http://localhost:3000',
      viewport: { width: 1280, height: 720 },
      locale: 'ja-JP',
      timezoneId: 'Asia/Tokyo',
      screenshot: 'only-on-failure',
      trace: 'on-first-retry',
      actionTimeout: 10_000,
    },
  });

ブラウザプロジェクト設定

• 複数ブラウザでのテスト実行設定です。

  // playwright.config.ts (projects section)
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    { name: 'mobile', use: { ...devices['iPhone 13'] } },
  ],

Webサーバー自動起動

• テスト前に開発サーバーを自動起動する設定です。

  // playwright.config.ts
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },

スクリーンショット

• テスト中にスクリーンショットを取得するパターンです。

  // Full page
  await page.screenshot({ path: 'full.png', fullPage: true });
  
  // Element only
  await page.getByRole('main').screenshot({ path: 'main.png' });
  
  // With clip region
  await page.screenshot({
    path: 'clip.png',
    clip: { x: 0, y: 0, width: 800, height: 600 },
  });

トレース

• テスト実行の詳細なトレースを記録するパターンです。

  // Start tracing
  await context.tracing.start({
    screenshots: true, snapshots: true, sources: true,
  });
  
  // ... run test actions ...
  
  // Stop and save
  await context.tracing.stop({ path: 'trace.zip' });
  // View: npx playwright show-trace trace.zip

ビジュアルリグレッションテスト

• スクリーンショットベースのUI回帰テストです。

  // Visual comparison test
  await expect(page).toHaveScreenshot(
    'homepage.png'
  );
  
  // With threshold
  await expect(page).toHaveScreenshot(
    'homepage.png',
    { maxDiffPixelRatio: 0.01 }
  );
  
  // Update baselines:
  // npx playwright test --update-snapshots