Playwrightの特徴と基本的な使い方

Posted at 2026-09-03

本記事の執筆にはAIを使用しています。

はじめに

Playwrightの特徴と、TypeScriptを使ったE2Eテストの基本的な書き方を紹介します。
よく使う関数も用途別にまとめます。

「Playwright」とは？

Microsoftが開発している、Webアプリ向けのE2Eテストフレームワークです。

Chromium、Firefox、WebKitを同じAPIで操作できます。
テストランナーやアサーション、並列実行、レポートなど、E2Eテストに必要な機能がまとまっています。

環境

Node.js: 24.13.0
Playwright: 1.60.0

特徴

主要なブラウザに対応している

Chromium、Firefox、WebKitに対応しています。
Google ChromeやMicrosoft Edgeなどのブラウザチャンネルも指定できます。

端末の画面サイズやUser-Agentを変えて、モバイル端末を再現することもできます。
同じテストを複数のブラウザや端末で実行したいときに便利です。

操作できる状態になるまで自動で待つ

Playwrightは、要素が操作できる状態になるまで自動で待ちます。
例えば click() は、対象が表示され、動きが止まり、クリックを受け取れる状態になってから実行されます。

そのため、決め打ちの待機処理を減らせます。
基本的には page.waitForTimeout() を使わず、ロケーターとWeb向けアサーションに待機を任せます。

ユーザーから見た要素の探し方を使える

Playwrightでは、要素を探す仕組みを「ロケーター」と呼びます。
役割で探す getByRole() や、ラベルで探す getByLabel() などが用意されています。

DOMの構造に強く依存する長いCSSセレクターやXPathより、画面上の意味に沿ったロケーターが推奨されています。
HTMLの細かな変更でテストが壊れにくくなります。

テストごとに状態が分かれる

各テストは独立した BrowserContext で実行されます。
CookieやLocal Storageなどの状態は、ほかのテストと共有されません。

テストの実行順による失敗を防ぎやすくなります。

失敗の原因を調べやすい

HTMLレポートやUIモード、Trace Viewerを使えます。
Trace Viewerでは、各操作の前後の画面、DOM、ネットワーク通信、コンソールなどを確認できます。

CIだけで失敗するテストの調査にも役立ちます。

基本的な使い方

セットアップする

次のコマンドを実行します。

$ npm init playwright@latest

対話形式で言語やテストの保存先などを選びます。
本記事ではTypeScriptを選び、ブラウザもインストールします。

主に次のファイルが作られます。

パス	役割
`playwright.config.ts`	ブラウザやタイムアウトなどの設定
`tests/example.spec.ts`	サンプルのテスト
`package.json`	コマンドや依存パッケージの管理

既存のプロジェクトへ手動で追加する場合は、パッケージとブラウザを別々にインストールします。

$ npm install --save-dev @playwright/test
$ npx playwright install

LinuxのCIでOSの依存パッケージも必要な場合は、 --with-deps を付けます。

$ npx playwright install --with-deps

テストを書く

Playwrightのドキュメントを開き、リンク先の見出しを確認するテストです。

tests/playwright.spec.ts

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

test.describe('Playwrightのドキュメント', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('https://playwright.dev/');
  });

  test('タイトルにPlaywrightが含まれる', async ({ page }) => {
    await expect(page).toHaveTitle(/Playwright/);
  });

  test('Get startedからインストール手順へ移動できる', async ({ page }) => {
    await page.getByRole('link', { name: 'Get started' }).click();

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

test() でテストを定義します。
引数の page は、テストごとに用意されるブラウザのタブです。

page.goto() でページを開き、 getByRole() で要素を探し、 click() で操作します。
最後に expect() で結果を確認します。

Web向けの expect() は条件を満たすまで再試行するため、 await を付けてください。

テストを実行する

すべてのテストを実行します。

$ npx playwright test

ブラウザを表示しながら実行する場合は、 --headed を付けます。

$ npx playwright test --headed

特定のファイルのみ実行する場合は、ファイル名を指定します。

$ npx playwright test tests/playwright.spec.ts

UIモードで確認する

UIモードでは、テストを選んで実行し、各ステップの状態を画面上で確認できます。

$ npx playwright test --ui

テストを書きながら動作を確かめたいときに便利です。

HTMLレポートを開く

実行結果のHTMLレポートを開きます。

$ npx playwright show-report

成功、失敗、スキップなどで結果を絞り込めます。
失敗したテストを選ぶと、エラーや添付ファイルを確認できます。

主要な関数一覧

ここでは、Playwright Testでよく使うAPIを紹介します。
すべてのAPIは公式のAPIリファレンスを確認してください。

テストを組み立てる関数

関数	説明
`test()`	テストを定義する
`test.describe()`	関連するテストをまとめる
`test.beforeEach()`	各テストの前に処理する
`test.afterEach()`	各テストの後に処理する
`test.beforeAll()`	グループ内のテストを実行する前に一度だけ処理する
`test.afterAll()`	グループ内のテストを実行した後に一度だけ処理する
`test.step()`	テスト内の処理を名前付きの手順にまとめる
`test.use()`	ブラウザや端末などの設定をテスト単位で変える
`test.skip()`	条件に応じてテストをスキップする

ページを操作する関数

関数	説明
`page.goto()`	URLを開く
`page.goBack()`	前のページへ戻る
`page.reload()`	ページを再読み込みする
`page.screenshot()`	スクリーンショットを保存する
`page.waitForResponse()`	条件に合うレスポンスを待つ
`page.getByRole()`	ARIAロールと名前で要素を探す
`page.getByLabel()`	フォームのラベルで要素を探す
`page.getByText()`	表示テキストで要素を探す
`page.getByPlaceholder()`	プレースホルダーで要素を探す
`page.getByTestId()`	`data-testid` で要素を探す
`page.locator()`	CSSやXPathなどのセレクターで要素を探す

要素を探すときは、まず getByRole() や getByLabel() を検討します。
getByTestId() は、画面上の情報だけでは要素を特定しにくい場合に使います。

要素を操作する関数

関数	説明
`locator.click()`	クリックする
`locator.fill()`	入力欄へ文字列を入れる
`locator.clear()`	入力欄を空にする
`locator.check()`	チェックボックスやラジオボタンを選ぶ
`locator.uncheck()`	チェックボックスの選択を外す
`locator.selectOption()`	セレクトボックスの項目を選ぶ
`locator.hover()`	マウスポインターを重ねる
`locator.press()`	キーを押す
`locator.setInputFiles()`	ファイルを選ぶ
`locator.filter()`	条件を追加して対象を絞る
`locator.nth()`	一致した要素を番号で選ぶ

結果を確認する関数

関数	説明
`expect(locator).toBeVisible()`	要素が表示されていることを確認する
`expect(locator).toBeHidden()`	要素が表示されていないことを確認する
`expect(locator).toBeEnabled()`	要素が操作できることを確認する
`expect(locator).toBeChecked()`	要素が選択されていることを確認する
`expect(locator).toHaveText()`	要素のテキストが一致することを確認する
`expect(locator).toContainText()`	要素のテキストに値が含まれることを確認する
`expect(locator).toHaveValue()`	入力欄の値を確認する
`expect(locator).toHaveCount()`	一致する要素の数を確認する
`expect(page).toHaveTitle()`	ページのタイトルを確認する
`expect(page).toHaveURL()`	ページのURLを確認する
`expect(value).toEqual()`	値が一致することを確認する

toBeVisible() や toHaveText() などのWeb向けアサーションは、既定では最大5秒間再試行します。
一方で、値に対する toEqual() などはすぐに判定されます。

安定したテストを書くコツ

CSSやXPathより、 getByRole() や getByLabel() を優先する
固定時間を待つ処理を避け、自動待機とWeb向けアサーションを使う
テスト同士で実行順や状態に依存しない
外部サービスではなく、自分が管理する画面やAPIをテストする
CIでは初回実行時にリトライし、Trace Viewerで失敗を調べる

おわりに

Playwrightは、ブラウザ操作の自動待機と読みやすいロケーターにより、E2Eテストを簡潔に書けます。
まずはUIモードで小さなテストを1つ動かし、普段の開発へ少しずつ取り入れてみてください

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up