Playwright 入門と実践

Playwright（プレイライト）は、Microsoft が開発しているブラウザ自動化とテストのためのオープンソースです（ライセンスは Apache 2.0）。プログラムからブラウザを起動し、ページを開き、入力し、クリックし、表示を確かめる。人が手でやっていた操作を、コードで正確に再現します。

• 3種類のブラウザエンジンに対応 ── Chromium（Chrome・Edge）、Firefox、WebKit（Safari）。Windows・macOS・Linux で動く
• 4つの言語で書ける ── TypeScript／JavaScript、Python、Java、.NET（C#）。この記事は TypeScript で書く
• テストの道具一式が付いてくる ── テストランナー（Playwright Test）、操作の録画からコードを作る codegen、失敗を再生するトレースビューア、HTML レポート

主な持ち場は E2E（エンドツーエンド）テストです。画面から DB まで、システムを丸ごと通して「利用者の操作で、期待どおりに動くか」を確かめます。テストにはいくつかの段があり、よく「ピラミッド」にたとえられます。

ブラウザを自動で動かす試みは、20年以上前から続いています。最初の大きな流れは Selenium です。Selenium の公式サイトによると、始まりは2004年、シカゴの ThoughtWorks 社で、ジェイソン・ハギンズ（Jason Huggins）が社内の「勤怠・経費」アプリ（Time and Expenses）をテストするために作った道具でした。この記事で経費精算を題材にするのは、ちょっとした縁でもあります。Selenium は後に WebDriver と合流し、ブラウザを外から操作する方法は W3C の標準（WebDriver）になりました。

2017年、Google の Chrome DevTools チームが Puppeteer を公開します。Chrome の開発者ツールが使う通信方式（CDP）で Chrome を直接操作するため、速くて細かい制御ができました。ただし当初は Chrome（Chromium）専用。実際のユーザーは Safari も Firefox も使います。

そこで、Puppeteer を作った中心メンバーが Microsoft に移り、2020年1月に公開したのが Playwright です。当時の InfoQ の記事には、チームの「私たちは、もともと Google で Puppeteer を作ったのと同じチームです」という言葉が紹介されています。狙いは二つ。Chromium・Firefox・WebKit を一つの API で動かすこと、そしてテストに向いた APIにすることでした。Puppeteer のテックリードだったアンドレイ・ルシニコフ（Andrey Lushnikov）も、Playwright のコアチームのメンバーとして紹介されています。

その後の広がりは急でした。技術コンサルティング会社 Thoughtworks の「Technology Radar」では、2020年10月に Assess（評価）、2021年4月に Trial（試行）、2023年9月に Adopt（採用を推奨）へ。npm の @playwright/test は、2026年10月の時点で週に約7,600万回ダウンロードされています（2026年10月6〜12日。CI や AI エージェントによる自動インストールも含む数字で、利用者数そのものではありません）。執筆時点の最新版は 1.64.1（2026年10月14日）で、ほぼ毎月新しい版が出ています。

Playwright は三つの層でできています。テストを書く言語のライブラリ、命令を実際のブラウザ操作に変える Playwright 本体（サーバー）、そしてブラウザです。

• ブラウザごとの「通訳」を持っている ── Chromium とは CDP、Firefox とは「Juggler」と呼ばれる独自の通信、WebKit とも専用の通信で話す。Playwright のソースには、Firefox 用の Juggler や WebKit 用のパッチがそのまま入っている
• ブラウザは「パイプ」で直結 ── 起動したブラウザとはパイプ（プロセス間の通り道）でつながり、命令を送るだけでなく、ページの読み込みや画面の変化といった出来事もブラウザ側から届く
• 手を入れたブラウザを使う ── Firefox と WebKit は、自動操作に必要な機能を足した Playwright 用の版を npx playwright install で入れる。Chromium は、Chrome や Edge 本体を使うこともできる

昔ながらの WebDriver は、命令のたびに HTTP で問い合わせて返事を待つ方式です。Playwright はつなぎっぱなしの通り道の上で双方向にやり取りするので、ブラウザの状態の変化をすぐ知ることができます。これが、次に見る「自動で待つ」仕組みの土台になっています。

Playwright の大事な発明がブラウザコンテキストです。一つのブラウザの中に、Cookie も保存領域も別々の「シークレットウィンドウ」をいくつでも作れます。公式ドキュメントの言葉では「速く、安く作れる」。

Playwright Test は、テストごとに新しいコンテキストを用意します。前のテストのログイン状態や入力内容を引きずらないので、テストを並列に走らせても、順番を入れ替えても結果が変わりません。「前のテストが落ちたせいで、次のテストも全部落ちる」という連鎖を防げます。

画面の自動テストでいちばん多いトラブルは「待ち」です。ボタンがまだ出ていないのに押そうとして失敗する。それを避けるために「2秒待つ」と書くと、速い日はムダに待ち、遅い日はやはり失敗します。Playwright はこの問題を自動待機（オートウェイト）で解決しました。

確認（アサーション）も同じ考え方です。expect(合計).toHaveText('3,000円') と書くと、Playwright は表示が「3,000円」になるまで繰り返し確かめます。これを Web ファーストのアサーションと呼びます。既定の制限時間は、確認1つにつき5秒、テスト1本で30秒（この記事のテストでも、失敗時の表示でこの値を確認しました）。

画面のどの部品を操作するかを指定するのがロケーターです。Playwright の公式ガイドは、利用者に見える手がかりで探すことを勧めています。

ロケーターには厳密モードもあります。操作しようとした指定に要素が2つ以上当てはまると、「どちらか分からない」としてエラーにします。適当に1つ目を押して、たまたま通ってしまうことを防ぐ仕組みです。この記事のテストでも、二度これに助けられました（十一章）。

テストを書いて直すための道具も揃っています。

ここからは、実際にテストを書いて動かします。題材は、多くの会社にある経費精算。説明のために、筆者が小さなデモアプリ（Node.js、外部ライブラリなし）を作りました。申請者がログインして明細を入力し、承認者が承認する、という流れです。

この画面には、次のようなルールがあります。テストを書く前に、まずルールを表にするところから始めます。

R1〜R4 は1画面の中のルール、R5 は二人の利用者をまたぐ流れです。なお、R3 の境目（29,999円と30,000円）のような細かい組み合わせは、本来は単体テストや API のテストで網羅し、E2E では代表的なケースだけを見るのが効率的です。

Playwright を入れるのは1行です。npm init playwright@latest を実行すると、設定ファイルとサンプルが作られます（今回は npm i -D @playwright/test で入れ、ファイルは手で書きました）。テスト一式は次のように組み立てます。

まず設定です。テストの前にアプリを起動する（webServer）、ログイン用の下準備（setup）を先に走らせる、といったことをここに書きます。

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,                       // テストは並列に走らせる
  retries: process.env.CI ? 2 : 0,           // CI では失敗時に2回まで再実行
  reporter: [['list'], ['html', { open: 'never' }]],
  use: {
    baseURL: 'http://localhost:3000',
    locale: 'ja-JP',                         // 日付や数値の表示を日本の形式に
    timezoneId: 'Asia/Tokyo',
    trace: 'on-first-retry',                 // 再実行したときだけトレースを残す
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'] },
    // Firefox や Safari（WebKit）も、同じ形で1行ずつ足せる
  ],
  webServer: {                               // テストの前にアプリを起動しておく
    command: 'node app/server.js',
    env: { APP_ENV: 'test' },
    url: 'http://localhost:3000/login',
    reuseExistingServer: !process.env.CI,
  },
});

次に、最初に1回だけ走る下準備です。データを初期化し、申請者と承認者でログインして、その状態（Cookie など）を storageState としてファイルに保存します。各テストはこのファイルを読み込むだけで、ログイン済みの状態から始められます。テストのたびにログイン画面を操作するより、ずっと速く、安定します。

// tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';

// テスト用アカウント（検証環境だけに存在する）
const accounts = [
  { id: 'tanaka', password: 'pass-tanaka', file: '.auth/applicant.json', home: '/' },        // 申請者
  { id: 'sato',   password: 'pass-sato',   file: '.auth/approver.json',  home: '/approve' }, // 承認者
];

setup('テストデータを初期化する', async ({ request }) => {
  const res = await request.post('/api/test/reset');   // テスト専用の API
  expect(res.ok()).toBeTruthy();
});

for (const a of accounts) {
  setup(`${a.id} でログインしておく`, async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('社員ID').fill(a.id);
    await page.getByLabel('パスワード').fill(a.password);
    await page.getByRole('button', { name: 'ログイン' }).click();
    await expect(page).toHaveURL(a.home);
    await page.context().storageState({ path: a.file });   // ログイン状態をファイルに保存
  });
}

画面の操作のしかたは Page Object という1つのクラスにまとめます。「金額欄はラベル『金額』で探す」「申請ボタンは名前『申請する』で探す」といった知識をここに集めておけば、画面が変わったときに直す場所は1か所で済みます。

// tests/pages/expense-page.ts
import { type Page, type Locator } from '@playwright/test';

type Line = { date: string; kind: string; memo: string; amount: number; currency?: 'JPY' | 'USD' };

// 申請画面の「操作のしかた」をここに集める（Page Object）
export class ExpensePage {
  readonly lines: Locator;
  readonly total: Locator;
  readonly errors: Locator;
  readonly done: Locator;

  constructor(readonly page: Page) {
    this.lines  = page.getByTestId('expense-line');
    this.total  = page.getByTestId('total-amount');
    this.errors = page.getByRole('alert');
    this.done   = page.getByRole('status', { name: '申請結果' });
  }

  async goto() {
    await this.page.goto('/');
  }

  async fillLine(i: number, l: Line) {
    if (await this.lines.count() <= i)
      await this.page.getByRole('button', { name: '明細を追加' }).click();
    const row = this.lines.nth(i);
    await row.getByLabel('日付').fill(l.date);
    await row.getByLabel('区分').selectOption(l.kind);
    await row.getByLabel('内容').fill(l.memo);
    await row.getByLabel('金額').fill(String(l.amount));
    if (l.currency) await row.getByLabel('通貨').selectOption(l.currency);
  }

  async attachReceipt(name = 'receipt.pdf') {
    await this.page.getByLabel(/領収書/).setInputFiles({
      name, mimeType: 'application/pdf', buffer: Buffer.from('%PDF-1.4 dummy'),
    });
  }

  async submit() {
    await this.page.getByRole('button', { name: '申請する' }).click();
  }
}

明細の各行には data-testid="expense-line" という目印を付けました。行そのものには利用者に見える名前がないためです。見える手がかりで探せないところだけ、開発者と約束した目印を使う。これがロケーターのおすすめ順の使い方です。

次はフィクスチャ（テストの下準備）です。ここで外部の為替 API をモックに差し替えます。本物の為替レートは毎日変わるので、そのままでは「3,000円になるはず」と書けません。page.route() を使うと、ブラウザが出す通信を途中で受け止めて、決まった答えを返せます。

// tests/fixtures.ts
import { test as base, expect } from '@playwright/test';
import { ExpensePage } from './pages/expense-page';

export const test = base.extend<{ expensePage: ExpensePage }>({
  expensePage: async ({ page }, use) => {
    // 外部の為替 API は、いつも同じ値を返すモックに差し替える
    await page.route('https://api.rates.example/**', route =>
      route.fulfill({ json: { base: 'USD', rates: { JPY: 150 } } }));
    const expensePage = new ExpensePage(page);
    await expensePage.goto();
    await use(expensePage);
  },
});
export { expect };

そして、テスト本体です。ルール表の R1〜R4 が、そのまま4本のテストになっています。

// tests/expense.spec.ts
import { test, expect } from './fixtures';

test.use({ storageState: '.auth/applicant.json' });   // 申請者としてログイン済みで始める

test('明細の合計が自動で計算される', async ({ expensePage }) => {
  await expensePage.fillLine(0, { date: '2026-10-14', kind: '交通費', memo: '新幹線 東京→新大阪', amount: 14720 });
  await expensePage.fillLine(1, { date: '2026-10-14', kind: '会議費', memo: '打ち合わせ（3名）', amount: 3300 });
  await expect(expensePage.total).toHaveText('18,020円');
});

test('ドル建ての明細は為替レートで円に換算される', async ({ expensePage }) => {
  await expensePage.fillLine(0, { date: '2026-10-14', kind: 'その他', memo: 'クラウド利用料', amount: 20, currency: 'USD' });
  await expect(expensePage.total).toHaveText('3,000円');            // 20ドル × 150円
});

test('3万円以上は領収書がないと申請できない', async ({ expensePage }) => {
  await expensePage.fillLine(0, { date: '2026-10-14', kind: '宿泊費', memo: 'ホテル 2泊', amount: 32000 });
  await expensePage.submit();
  await expect(expensePage.errors).toContainText('領収書を添付してください');

  await expensePage.attachReceipt();
  await expensePage.submit();
  await expect(expensePage.done).toContainText('申請しました');
});

test('未来の日付は申請できない', async ({ expensePage }) => {
  const tomorrow = new Date(Date.now() + 86400000).toISOString().slice(0, 10);
  await expensePage.fillLine(0, { date: tomorrow, kind: '交通費', memo: 'タクシー', amount: 2400 });
  await expensePage.submit();
  await expect(expensePage.errors).toContainText('未来の日付は申請できません');
});

2本目のテストを見てください。通貨を USD に切り替えると、画面は為替 API に問い合わせてから合計を書き換えます。でもテストには「API の応答を待つ」という行がありません。toHaveText('3,000円') が、合計が 3,000円になるまで自動で確かめ続けるからです。

R5 は、申請者（田中さん）と承認者（佐藤さん）の二人が登場します。ここでブラウザコンテキストが活きます。一つのブラウザの中に二人分のコンテキストを作り、それぞれのログイン状態で画面を開きます。

// tests/approval.spec.ts
import { test, expect } from '@playwright/test';
import { ExpensePage } from './pages/expense-page';

test('申請して承認されると「承認済み」になる', async ({ browser }) => {
  // 1つのブラウザの中に、申請者と承認者の2つの「コンテキスト」を作る
  const applicant = await browser.newContext({ storageState: '.auth/applicant.json' });
  const approver  = await browser.newContext({ storageState: '.auth/approver.json' });
  let no = '';                                              // 例: "No.0003"

  await test.step('田中さんが申請する', async () => {
    const p = new ExpensePage(await applicant.newPage());
    await p.goto();
    await p.page.getByLabel('件名').fill('大阪出張');
    await p.fillLine(0, { date: '2026-10-14', kind: '交通費', memo: '新幹線 往復', amount: 29440 });
    await p.submit();
    await expect(p.done).toContainText('申請しました');
    no = (await p.done.textContent())!.match(/No\.\d{4}/)![0];   // 採番された番号で後から探す
  });

  await test.step('佐藤さんが承認する', async () => {
    const page = await approver.newPage();
    await page.goto('/approve');
    const row = page.getByRole('row').filter({ hasText: no });
    await row.getByRole('button', { name: '承認' }).click();
    await expect(row.getByText('承認済み')).toBeVisible();
  });

  await test.step('田中さんの画面でも「承認済み」になっている', async () => {
    const page = await applicant.newPage();
    await page.goto('/');
    const row = page.getByRole('table', { name: '申請一覧' }).getByRole('row').filter({ hasText: no });
    await expect(row).toContainText('承認済み');
  });

  await applicant.close();
  await approver.close();
});

test.step() で区切ると、レポートやトレースに「田中さんが申請する」といった見出しが付き、どこで失敗したかがひと目で分かります。

実行は npx playwright test だけです。アプリの起動、ログインの下準備、8件のテストまでが自動で流れます。

$ npx playwright test
Running 8 tests using 1 worker

  ✓  1 [setup] › tests/auth.setup.ts:9:6 › テストデータを初期化する (44ms)
  ✓  2 [setup] › tests/auth.setup.ts:15:8 › tanaka でログインしておく (606ms)
  ✓  3 [setup] › tests/auth.setup.ts:15:8 › sato でログインしておく (472ms)
  ✓  4 [chromium] › tests/approval.spec.ts:4:5 › 申請して承認されると「承認済み」になる (1.2s)
  ✓  5 [chromium] › tests/expense.spec.ts:5:5 › 明細の合計が自動で計算される (600ms)
  ✓  6 [chromium] › tests/expense.spec.ts:11:5 › ドル建ての明細は為替レートで円に換算される (435ms)
  ✓  7 [chromium] › tests/expense.spec.ts:16:5 › 3万円以上は領収書がないと申請できない (536ms)
  ✓  8 [chromium] › tests/expense.spec.ts:26:5 › 未来の日付は申請できない (461ms)

  8 passed (6.3s)

ただ、最初から全部うまくいったわけではありません。厳密モードに二度止められました。

• 1回目：「申請しました」の表示が2つ見つかった ── 完了メッセージを getByRole('status') で探したところ、合計金額の表示に使った <output> 要素も、HTML の決まりで同じ「status」の役割を持っていた。メッセージ側に aria-label="申請結果" と名前を付け、getByRole('status', { name: '申請結果' }) で区別した
• 2回目：並列で走らせたら、同じ件名の行が2つ ── 最初は件名に一意な文字列を付けて行を探していたが、同じテストを並列で5回ずつ繰り返す負荷試験（--workers 4 --repeat-each 5）をかけると、その文字列が繰り返しのあいだで同じになり、行が2つ見つかった。アプリが採番した番号（No.0003 など）を画面から読み取り、その番号で探す方式に変えて、28件すべて成功

どちらも、厳密モードがなければ「たまたま1つ目が当たって通る」テストになっていたはずです。偶然に頼るテストは、いつか理由もなく落ちます（いわゆる「フレーキーなテスト」）。

もう一つ、わざと失敗させてみました。画面のボタン名を「申請する」から「提出する」に変えると、テストは次のように落ちます。

  1) [chromium] › tests/expense.spec.ts:26:5 › 未来の日付は申請できない ────────────────────────────────────────
    Test timeout of 30000ms exceeded.
    Error: locator.click: Test timeout of 30000ms exceeded.
    Call log:
      - waiting for getByRole('button', { name: '申請する' })
       at pages/expense-page.ts:41
      39 |
      40 |   async submit() {
    > 41 |     await this.page.getByRole('button', { name: '申請する' }).click();
         |                                                           ^
      42 |   }
      43 | }
      44 |

ここで大事なのは、この失敗が「テストが古い」のか「画面の不具合」なのかは、Playwright には分からないということです。ボタン名の変更が仕様どおりならテストを直し、意図しない変更なら画面を戻す。この判断は、後で見る AI の時代にも人の仕事として残ります。

ここまでのテストが短く、安定して書けたのは、実はアプリの側にテストしやすい作りを最初から入れておいたからです。Playwright の力を引き出せるかどうかは、テストを書く前、つまり設計と開発の段階でほぼ決まります。

たとえば、データ初期化の口はこれだけです。テスト用モードで起動したときだけ有効にし、本番では存在しないようにしておきます。

// app/server.js（抜粋）
// テスト専用：データを初期状態に戻す（本番では無効）
if (TEST_MODE && req.method === 'POST' && url.pathname === '/api/test/reset') {
  db = { seq: 0, expenses: [] };
  return send(res, 200, { ok: true });
}

テストは、書いただけでは価値が半分です。変更のたびに自動で走るようにして初めて、「いつの間にか壊れていた」を防げます。

GitHub Actions なら、たとえば次のように書けます（公式ドキュメントの例を、この記事の構成に合わせて短くしたもの）。

# .github/workflows/e2e.yml
name: e2e
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npx playwright install chromium --with-deps   # 使うブラウザだけ入れる
      - run: npx playwright test
        env:
          CI: true                                  # 再実行2回・トレースが有効になる
      - uses: actions/upload-artifact@v7
        if: ${{ !cancelled() }}                     # 失敗しても結果は残す
        with:
          name: playwright-report
          path: playwright-report/

もう一つの準備が、書き方のルールを機械でチェックすることです。ESLint のプラグイン eslint-plugin-playwright と TypeScript の規則を使うと、「CSS セレクタで探している」「2秒待っている」「await を付け忘れている」といった、壊れやすいテストの書き方を、実行する前に見つけられます。

// eslint.config.mjs
import tseslint from 'typescript-eslint';
import playwright from 'eslint-plugin-playwright';

export default tseslint.config({
  files: ['tests/**/*.ts'],
  extends: [playwright.configs['flat/recommended']],
  languageOptions: { parser: tseslint.parser, parserOptions: { projectService: true } },
  plugins: { '@typescript-eslint': tseslint.plugin },
  rules: {
    '@typescript-eslint/no-floating-promises': 'error',   // await の付け忘れ
    'playwright/no-raw-locators': 'error',                // CSS・XPath で探さない
    'playwright/no-wait-for-timeout': 'error',            // 「とりあえず2秒待つ」を禁止
    'playwright/prefer-web-first-assertions': 'error',
  },
});

次のような「悪い例」を書いて、実際にチェックにかけてみました。

// AI が書いてきた「悪い例」
import { test, expect } from '@playwright/test';

test('合計が出る（悪い例）', async ({ page }) => {
  await page.goto('/');
  await page.locator('#lines tr:nth-child(1) td:nth-child(4) input').fill('14720');
  page.locator('button.primary').click();
  await page.waitForTimeout(2000);
  expect(await page.locator('#total').isVisible()).toBe(true);
});

$ npx eslint tests
tests/bad/bad.spec.ts
  5:9   error  Usage of raw locator detected. Use methods like .getByRole() or .getByText() instead of raw locators  playwright/no-raw-locators
  6:3   error  Promises must be awaited, end with a call to .catch, ... or be explicitly marked as ignored with the `void` operator  @typescript-eslint/no-floating-promises
  6:3   error  Usage of raw locator detected. ...  playwright/no-raw-locators
  7:9   error  Unexpected use of page.waitForTimeout()  playwright/no-wait-for-timeout
  8:3   error  Replace isVisible() with toBeVisible()  playwright/prefer-web-first-assertions
  8:16  error  Usage of raw locator detected. ...  playwright/no-raw-locators

✖ 6 problems (6 errors, 0 warnings)

6か所すべてが止められました。この仕組みは、人が書くテストにも、AI が書くテストにも同じように効きます。

• 不安定なテストは放置しない ── CI で「再実行したら通った」テストは、レポートに Flaky として出る。原因を調べて直すか、直るまで隔離する
• ブラウザは必要なものだけ ── まずは Chromium だけで始め、Safari の利用者が多いなら WebKit を足す、と段階的に
• 時間が延びてきたら分割 ── --shard=1/2 のように分けて複数台で並列に流す

Playwright は、2025年から「AI にブラウザを使わせるための道具」としても使われるようになりました。鍵になるのが、ページを文字にしたアクセシビリティ・スナップショットです。

この仕組みを使った実例を、執筆時点（2026年10月）のものから挙げます。

試しに、デモアプリのログイン画面を playwright-cli で操作してみました。AI が「番号 e8 に tanaka と入力」と命令すると、Playwright はそれを getByRole を使ったコードとして実行し、そのコードを返してきます。AI はこのコードをそのままテストに使えます。

$ playwright-cli open http://localhost:3000/login
$ playwright-cli fill e8 tanaka
### Ran Playwright code
await page.getByRole('textbox', { name: '社員ID' }).fill('tanaka');
$ playwright-cli fill e10 pass-tanaka
### Ran Playwright code
await page.getByRole('textbox', { name: 'パスワード' }).fill('pass-tanaka');
$ playwright-cli click e11
### Ran Playwright code
await page.getByRole('button', { name: 'ログイン' }).click();
### Page
- Page URL: http://localhost:3000/
- Page Title: 経費精算の申請

ここで十二章の準備が効いてきます。入力欄にラベルがあったから、返ってきたコードは getByRole('textbox', { name: '社員ID' }) という読みやすく壊れにくい形になりました。ラベルのない画面なら、AI も壊れやすい探し方をするしかありません。人にとって分かりやすい画面は、AI にとっても分かりやすいのです。

テストエージェントも入れてみました（AI の実行まではしていません。生成されたファイルの確認まで）。

$ npx playwright init-agents --loop=claude
 🎭 Using project "chromium" as a primary project
 📝 specs/README.md - directory for test plans
 🌱 tests/seed.spec.ts - default environment seed file
 🤖 .claude/agents/playwright-test-generator.md - agent definition
 🤖 .claude/agents/playwright-test-healer.md - agent definition
 🤖 .claude/agents/playwright-test-planner.md - agent definition
 🔧 .mcp.json - mcp configuration
 ✅ Done.

十一章でわざと失敗させたテストについて、Playwright が書き出した error-context.md の中身も見てみます。AI への指示文、エラー、そして失敗した瞬間のページのスナップショットが入っていて、「申請する」ボタンがなく「提出する」ボタンがあることが、AI にも読み取れる形になっています。

# error-context.md（抜粋・自動で書き出される）
# Instructions
- Following Playwright test failed.
- Explain why, be concise, respect Playwright best practices.
- Provide a snippet of code with the fix, if possible.

# Error details
Error: locator.click: Test timeout of 30000ms exceeded.
  - waiting for getByRole('button', { name: '申請する' })

# Page snapshot
      - status [ref=e39]: 2,400円
      ...
      - button "提出する" [ref=e42] [cursor=pointer]

AI にテストを書かせると、速い反面、書き方がばらばらになりがちです。CSS セレクタで探したり、2秒待ったり、テスト同士がデータを共有したり。そこで、プロジェクトのルールを文章にして AI に渡し、さらに機械のチェックで守らせる、という二段構えにします。

まずルールファイルです。AI のコーディングエージェントの多くは、リポジトリに置いた AGENTS.md（Claude Code なら CLAUDE.md、GitHub Copilot なら .github/copilot-instructions.md など）を読んでから作業します（AGENTS.md についてはAGENTS.md 覚書で詳しく書きました）。この記事のテストに合わせると、たとえば次のような節を足します。

## E2E テスト（Playwright）のルール

- テストは tests/ に置く。画面の操作は tests/pages/ の Page Object に書き、
  テスト本体には「何を確かめるか」だけを書く
- 要素は getByRole → getByLabel → getByText → getByTestId の順で探す。
  CSS セレクタ・XPath・nth-child は使わない
- 待つときは expect(...).toBeVisible() などの Web ファーストのアサーションを使う。
  waitForTimeout() は使わない
- テストは互いに独立させる。ほかのテストのデータや実行順に頼らない。
  行を探すときは、アプリが採番した番号を使う
- ログインは auth.setup.ts で保存した storageState を使う
- 外部サービス（為替 API など）は page.route() でモックする
- 画面を作るときは、入力欄にラベル、ボタンに名前を付ける。
  目印が必要なら data-testid を足す（kebab-case）
- 失敗したテストを直すとき、expect の期待値を変えない。仕様の変更か不具合か
  判断できなければ、手を止めて理由を報告する
- 終わったら npx eslint tests と npx playwright test を実行し、結果を報告に書く

次に、テストを頼むときのプロンプトの「ひな形」を用意しておきます。ポイントは、手本のファイルを名指しすること、いきなりコードを書かせず、先に計画を出させること、実行結果を貼らせることです。

# AI へのお願い（ひな形）
経費精算の「差戻し」の E2E テストを追加してください。

- 仕様：承認者が差し戻すと、申請者の一覧で状態が「差戻し」になる
- 手本：tests/approval.spec.ts と同じ書き方。AGENTS.md の
  「E2E テスト（Playwright）のルール」に従うこと
- まず specs/reject.md に手順と期待結果を書き、私の確認を待つ
- 確認後に実装し、npx eslint tests と npx playwright test の結果を貼る
- 画面にラベルや名前が足りなければ、テストで回避せず、画面側の修正案を出す

そして、ルールが守られているかを機械で確かめるのが十三章の ESLint です。文章のルールは AI が読み飛ばすことがありますが、CI の lint は読み飛ばせません。「ルールファイルで方向を示し、lint とテストで外れたら止める」。人のチームでも AI でも、同じやり方が効きます。

最後に、これからの方向を考えます。ここからは、すでにある機能を手がかりにした筆者の見立てです。

• 仕様からテストへ、が近づく ── テストエージェントは、Markdown の計画からテストを作る。受入条件をきちんと書いておけば、そこからテストの下書きまでは AI が作る、という流れが普通になっていくと考える。そのぶん、受入条件の書き方の重みが増す
• 「直すテスト」から「見張るテスト」へ ── 画面の変更にテストが追いつく修復は、すでにヒーラーが行っている。ただし、何でも直してしまうとテストが「今の画面」を追いかけるだけになり、不具合を見逃す。期待値の変更には人の承認を必須にする運用が、今後ますます大事になる
• アクセシビリティが品質の中心へ ── AI も Playwright も、ラベルや役割で画面を読む。画面の読み上げに配慮した作りが、そのまま「テストしやすさ」「AI の扱いやすさ」になる。三つの目的が一致するのは、開発の現場にとって追い風
• ページが AI に「操作の口」を差し出す ── 1.64 で入った WebMCP 対応のように、ページ自身が AI 向けの操作を宣言する試みが始まっている。まだ実験段階だが、画面をなぞる操作と、決められた口を呼ぶ操作が併用されていくかもしれない
• 人の仕事は「何が正しいか」を決めることに ── テストを書く・流す・直す手間は、AI と道具がどんどん引き受ける。残るのは、どんな振る舞いが正しいかを決め、AI の出した変更を見極める仕事だ