5
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 5

ラクスパートナーズ Advent Calendar 2025

@H-Iida

PlaywrightでE2Eテストとビジュアルリグレッションテストを実装する

5
Last updated at Posted at 2025-11-09

この記事は、ラクスパートナーズ AdventCalendar 2025の5日目の記事です。

最近業務で大規模な改修作業があったので、E2Eテストとビジュアルリグレッションテストでプロジェクト全体に予期せぬ変更がないか、を検証したいと考えていました。
そこでE2Eテストツールについて調べたところ、Playwrightが非常に良いと感じたので、特徴と使い方を書いていきたいと思います。
（JavaScript/TypeScriptを使っているプロジェクトへの導入を想定して書いています）

Playwrightとは？

E2Eテストを実装できるテストツールです。
https://playwright.dev/docs/intro

E2Eテストとは？
人によって定義がバラバラですが
「システムが想定通りの動作をしているかを、システム全体を通して検証するテスト」
のことです。

Playwrightの特徴

以下のような特徴があります。

  • テストが安定していて速い
  • 主要なブラウザに対応している（Chromium、Webkit（Safari）、FireFoxなど）
  • 機能が豊富
    • エミュレート機能がある（AndroidやiOS端末の挙動もテストできる）
    • ビジュアルリグレッションテストも単体で実装できる

ビジュアルリグレッションテストとは？
テスト実行時に画面のスクリーンショットを撮り、以前撮ったスクリーンショットと比較を行うテストのことです。これにより、画面に予期せぬ差分がないかを確認することができます。

Playwrightを選定した理由

  • 担当プロジェクトでほぼ全てのページやコンポーネントを触る作業をしたので、プロジェクト全体で動作やレイアウトに問題がないかを検証したい
  • チーム内でブラックボックステスト（実装内容に問題がないかを手作業で確認するテスト）をしている状況だったので、その負担を軽減したい

という条件を満たしていたため、Playwrightを選定しました。

最初は人気なCypressを候補に考えていたのですが、以下の理由のため断念しました。

  • WebKitベースのブラウザ（Safari）への対応がexperimental（実験的）の状態である
    • 担当プロジェクトでは、最新版Safariを推奨環境としていたので断念しました
  • テストの実行が他のテストツールに比べて速くない(Playwrightの方が速い)
  • 単体ではビジュアルリグレッションテストを実装できない
    • reg-suit（ライブラリ）やPercy（クラウドサービス）を併用する必要がある
    • ビジュアルリグレッションテストで細かいレイアウト崩れも検知できるのは魅力に思っていたので、手軽に実装できるPlaywrightの方が良いと考えました

また、npm trendsで主要なテストツールと比較してみましたが、Playwrightが圧倒的に1位でした。ピーク時は、2位のCypressに4〜5倍近くの差をつけていますね。非常に人気なテストツールであることが伺えます。

インストール方法

プロジェクトで npm init playwright@latest を実行し、質問に回答すればすぐ使えるようになります。
今回は以下のように回答しました。

  • Do you want to use TypeScript or JavaScript? → JavaScript
  • 1Where to put your endo-to-end tests? → e2e
  • Add a GitHub Actions workflow?(y/N) → No
  • Install Playwright browsers (Can be done manually via 'npx playwright install')?(Y/n) → Yes

すると、以下5つのファイルが生成されます。

  • playwright.config.js
  • package.json
  • package-lock.json
  • e2e/（テストファイルの置き場所）
    • ecample.spec.js
  • tests-examples/（サンプルコードが入っているだけなので削除可）

あとは、.gitignoreにも設定が追加されます。
これでPlaywrightのインストールは完了です。

テストの実行

テストを実行するには、npx playwright testを実行します。すると、各ブラウザ(Chromium、Webkit、Firefox)でテストが実行され、テストの成功/失敗の結果がコンソールに表示されます。

また、テスト実行後にnpx playwright show-reportを実行すると、テストの詳細を確認できるページが立ち上がります（テスト失敗時は自動で立ち上がります）。

テストコードの書き方

以下は公式ドキュメントにあるサンプルコードです。こちらを使って説明します。
https://playwright.dev/docs/writing-tests

サンプル
import { test, expect } from '@playwright/test';

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Click the get started link.
  await page.getByRole('link', { name: 'Get started' }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

各関数の解説

test()

テストを宣言する関数です。
test('テスト名', async ({ page }) => テストの内容)
の形式でテストを書いていきます。
引数のpageオブジェクトを使って、テストの中でページ遷移させたり、HTML要素を取得したりします。

page.goto()

引数にページのURLを指定することで、任意のページに遷移できます。

click()

actionsの一つです。取得した要素に指定することで、その要素をクリックできます。

expect()

テストの結果が想定通りかを確認するアサーション関数です。
expect(pageオブジェクトやLocator).マッチャー関数
の形式で書きます。
上記の例では、toBeVisible()関数で、指定した要素がページ内に存在しているかをチェックしています。

page.getByRole()

page.getByRole('WAI-ARIAに基づくロール名', { name: '要素のテキストやラベル' })の形式でHTML要素を取得できます。
例：よくある送信ボタンなら page.getByRole('button', { name: '送信' });

WAI-ARIA(ウェイ アリア)とは？
Web Accessibility Initiative Accessible Rich Internet Applications の略です。
障がいを持つ方も適切な情報を得られることを目的に定められた、Webアクセシビリティの仕様の一つです。スクリーンリーダーなどを通してWebサイトにアクセスしたとき、HTMLだけでは表現できないことを補完します。

WAI-ARIAを構成する要素の一つであるロール は、HTML要素に対して「この要素はどんな役割を持つか？」を意味付けする属性です。
例：button、link、heading、input、img、textbox、checkbox、radio、formなど。
<div role="heading" aria-level="1">これはメインのページ見出しです</div>

「こんなことしなくても、HTML要素のidやclassを指定して取得すればいいのでは？」
と思いましたが、
「簡単に変わるDOMの構造に依存したテストは失敗する可能性がある」
と公式ドキュメントに記載されていました。

Your DOM can easily change so having your tests depend on your DOM structure can lead to failing tests. For example consider selecting this button by its CSS classes. Should the designer change something then the class might change, thus breaking your test.

こちらから引用：https://playwright.dev/docs/best-practices#prefer-user-facing-attributes-to-xpath-or-css-selectors

HTML要素を取得する際は、getByRole()のようなLocatorと呼ばれる機能を使うことが推奨されています。
(この辺りのテストを書く上でのベストプラクティスについては、また別記事で書こうと思います)

長くなりましたが、サンプルコードの解説については以上です。

ブラウザ操作によるテストコード生成

npx playwright codegen を実行すると、立ち上がったブラウザの操作に合わせてテストコードを生成してくれます。
Chromiumブラウザをデフォルトで使用しますが、以下のように特定のブラウザを指定してコード生成をすることもできます。

  • Chromium: npx playwright codegen --browser=chromium
  • WebKit: npx playwright codegen --browser=webkit
  • Firefox: npx playwright codegen --browser=firefox

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

ビジュアルリグレッションテストを実装するには、toHaveScreenshot()関数を使用します。

ビジュアルリグレッションテスト
import { test, expect } from '@playwright/test';

test('get started link', async ({ page }) => {
  await page.goto('http://localhost:8080/');

  await expect(page).toHaveScreenshot({
      fullPage: true,             // 画面全体を撮影する
      animations: 'disabled',     // アニメーションを無効化
      mask: [                     // テストに含めたくない要素をマスク(無視)する
          page.locator('.hoge'),
          page.locator('.fuga'),
      ],
      maskColor: '#00ff00'        // マスクする際の色を指定
  });
});

ただ、最初は比較対象となるスクリーンショットが存在しないため、
npx playwright testを実行するとエラーが出てしまいます。そのため、まだスクリーンショットが保存されていない場合は、
npx playwright test --update-snapshots
を実行します。

--update-snapshotsオプションをつけることで、今の画面を新しい正解として保存し直すことができます。
まだスクリーンショットが保存されていない場合や、正解となる画面を今の画面に更新したい場合は、
npx playwright test --update-snapshots
を実行するようにしてください。

また、サンプルコードに記載しているオプションについては以下の通りです（基本的には会ったほうが便利だと思います）。

  • fullPage：trueを指定することで、ページ全体を撮影できる
    • これがないとファーストビューしか撮影できないので、必須だと思います
  • animations：'disabled'を指定することで、ページ内のアニメーションを無効化でき
    • 'allow'でアニメーションを有効にできますが、ビジュアルリグレッションテストが失敗しやすくなるので無効化した方が良いと思います
  • mask：指定した要素にピンク色のマスクをかけて無視できるようになります
    • 内容が頻繁に変わる要素（スライダーやお知らせバナーなど）などに指定すると、テストが失敗しにくくなります
  • maskColor：maskで指定した要素にかけるマスクの色を変更できます
    • デフォルトは濃いめのピンクですが、例では目に優しい緑へ変更してみました

ビジュアルリグレッションテストについては以上となります。

まとめ

  • テストの実行速度が速くて安定している
  • 機能が豊富
  • 主要ブラウザに対応している

という三拍子が揃ったPlaywrightについて紹介させていただきました。

Playwright公式でテストを書く上でのベストプラクティスも紹介されていたので、また記事にしたいと思います。
ここまで読んでくださり、ありがとうございました。

5
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
5
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?