Playwrightを活用したE2Eテストの導入

はじめに

この記事は、every Tech Blog Advent Calendar 2023 の4日目の記事です。

tech.every.tv

はじめまして。株式会社エブリー DELISH KITCHEN 開発本部の羽馬(@NaokiHaba )と申します。

今回は、簡単なハンズオンを通して、Playwrightの基本的な使い方を紹介していきます。

実装したソースコードは以下のレポジトリで公開していますので、興味のある方はご覧ください。

github.com

想定読者

この記事では、以下のような方を想定しています。

playwrightを触ってみたい方。
E2Eテストを導入したい方。

ハンズオンの前提条件

この記事を読む前に、以下の準備をお願いします。

Node.jsのセットアップ
- お済みでない方は、こちらを参考にNode.jsをインストールしてください。
GitHubアカウントの作成
- GitHub のアカウントをお持ちでない方は、こちらからアカウントを作成してください。
GitHubリポジトリの作成
- お済みでない方は、こちらを参考に任意のリポジトリを作成してください。

この記事で得られるもの

この記事を読むことで、Playwrightを使ったE2Eテストの導入ができるようになることを目指します。

実行環境

Next.js v14.0.3
playwright v1.40.1
Mac OS Sonoma v14.1.1

Playwrightを活用したE2Eテストの導入

Playwrightとは

github.com

Microsoftが開発したE2Eテストツール
Chromium、WebKit、Firefoxを含むすべての最新のレンダリングエンジンをサポートしているNode.jsベースのライブラリ
PuppeteerとPlaywrightはほとんど同じチームによって開発されている

以下のブログでPuppeteerとPlaywrightの比較がまとめられていますので、興味がある方はご覧ください。

blog.logrocket.com

Playwrightの特徴的な機能

Test generator

codegenコマンドを使用してテストジェネレータを実行し、その後にテストを生成したいウェブサイトのURLを入力します。

URLなしでコマンドを実行し、代わりにブラウザウィンドウに直接URLを追加することもできます。

$ pnpm exec playwright codegen demo.playwright.dev/todomvc

この画面で任意の操作を行うと、テストコードが自動的に生成されます。

使用してみた感想としては、テストコードを書いたことがない方でも、この機能を使えばテストコードを自動生成できるので、テストコードを書くハードルが下がるのではないかと思います。

UI Mode

Playwright v1.32.0 から、UIモードが追加されました。

UIモードはテストを実行したり、デバッグするための機能を提供しています。

$ pnpm exec playwright test --ui

起動に成功すると、以下のような画面が表示されます。

ここからは、使ってみてこの機能が便利だと感じた点を紹介していきます。

Watch mode

テストコードの変更を検知して、自動的にテストを実行してくれます。

テストコードを修正して、実行結果を確認するという作業を繰り返す際に便利です。

定義したアクションごとのスナップショット

テストコードを実行すると、定義したアクションごとにスナップショットが作成されます。

どのタイミングでテストが失敗したのか・どのような操作を行ったのかなどを確認する際に便利です。

他にも、便利な機能が多数ありますので、詳しくは、公式ドキュメントを参考にしてください。

ハンズオン

ここからは、PlaywrightをNext.jsに導入してE2Eテストを実装していきます。

あくまで、一例としてNext.jsを利用していますが、その他のフレームワークでも同様の手順で導入できると思います。

Next.jsをセットアップする

Next.jsのセットアップ方法は、こちらを参考にしてください。

ここでは詳細な手順は割愛しますが、今回は ~/Documents に Next.jsをインストールしています。

# 任意のディレクトリに移動してください
$ cd ~/Documents

# プロジェクト名は任意のものを指定してください
# ここでは、playwright-next-app-sample というプロジェクト名で作成しています
$ npx create-next-app@latest

$ cd playwright-next-app-sample

# pnpm を利用していますが、npm や yarn・bunでも問題ありません。お好きなものを利用してください
$ pnpm dev

http://localhost:3000/ にアクセスして、以下のような画面が表示されれば成功です。

Playwrightをセットアップする

Playwrightをセットアップするには、以下のコマンドを実行します。

詳しくは、公式ドキュメントを参考にしてください。

$ pnpm create playwright

Choose between TypeScript or JavaScript (default is TypeScript) # TypeScript を選択
Name of your Tests folder (default is tests or e2e if you already have a tests folder in your project) # 任意のフォルダ名を入力 (今回は tests を入力)
Add a GitHub Actions workflow to easily run tests on CI
Install Playwright browsers (default is true) # true を選択

pnpm create playwright を実行すると、以下のようなディレクトリ構成が作成されます。

- tests
- tests-example
- playwright.config.ts

最後に、テストを実行して以下のような結果が表示されれば成功です。

$ pnpm exec playwright test

➜  playwright-next-app-sample git:(main) ✗     pnpm exec playwright test

Running 6 tests using 5 workers
  6 passed (4.1s)

To open last HTML report run:
  pnpm exec playwright show-report

実行結果は、playwright-report ディレクトリに保存されます。

pnpm exec playwright show-report を実行すると、実行結果をブラウザで確認できます。

$ pnpm exec playwright show-report

Next.jsのサンプルアプリケーションを起動する

今回は、Next.jsのサンプルアプリケーションを利用してテストを実装していきます。

テストコードを実装する前に、Next.jsのサンプルアプリケーションを起動しておいてください。

# Next.jsをローカルで起動
$ pnpm run dev

テストコードの作成

tests/example.spec.ts に以下のテストコードを記述します。

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

// テストコードの実行前にTOPページにアクセスする
test.beforeEach(async ({page}) => {
    await page.goto('http://localhost:3000');
});

test('Get started by editing src/app/page.tsx が表示される', async ({page}) => {
    await expect(page.getByRole('main')).toContainText('Get started by editing src/app/page.tsx');
})

test('Docページに遷移できる', async ({page}) => {
    const page7Promise = page.waitForEvent('popup');
    await page.getByRole('link', {name: 'Docs -> Find in-depth'}).click();
    const page7 = await page7Promise;
    await expect(page7.getByRole('heading', {name: 'Introduction'})).toBeVisible();
})

テストの実行

UIモードを利用してテストを実行していきます。

$ pnpm exec playwright test --ui

テストの実行結果は、以下のようになります。

コマンドライン上でテストの実行結果を確認することもできます。

$ pnpm exec playwright test

Running 6 tests using 5 workers
  6 passed (4.2s)

To open last HTML report run:

  npx playwright show-report

GitHub Actionsでテストを実行する

ここからは、オマケとして GitHub Actionsを利用したワークフローを実装していきます。

Playwright はセットアップ時に、GitHub Actionsの設定ファイルを自動で作成してくれます。

今回は、そのまま利用してテストを実行していきますが、必要に応じてカスタマイズしてください。

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: npm install -g pnpm && pnpm install
      - name: Install Playwright Browsers
        run: pnpm exec playwright install --with-deps
      - name: Run Playwright tests
        run: pnpm exec playwright test
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

playwrightの設定ファイルを変更する

playwright.config.ts を編集して、テストの実行前にローカルサーバーを起動するようにします。

複数環境で切り替えたい場合は、環境変数を利用して切り替えることもできます。

// playwright.config.ts

export default defineConfig({
    /* Run your local dev server before starting the tests */
    webServer: {
        command: 'pnpm run dev',
        url: 'http://127.0.0.1:3000',
        reuseExistingServer: !process.env.CI
    }
});

テストの結果を確認する

それでは、ここまでの差分をコミットして、GitHubにプッシュしてください。

GitHub Actionsでテストが実行されていることを確認することができます。

最後に

以上で、Playwrightの基本的な使い方を紹介しました。

Playwrightは、Puppeteerと比較しても遜色ない機能を持っているので、今後はPlaywrightを利用してE2Eテストを実装していきたいと思います。

また、Vscodeに拡張機能が用意されているので、VsCodeユーザーはぜひ利用してみてください。

この記事が、Playwrightを触ってみたい方やE2Eテストを導入したい方の参考になれば幸いです。