Playwright の導入から各種実行方法について試してみた

はじめに

手軽に E2E テストを実行できる Playwright を触るために、導入から各種実行方法について、ドキュメントを見ながら実際に試してみました。基本的にはドキュメントの通り、進めることができるかと思いますが、実際に利用するであろう設定や実行方法など試してみたので、参考になれば幸いです。

Playwright をインストール

以下のコマンドを実行し、各種設定を選択することでプロジェクトの雛形が作成されます。

% npm init playwright@latest

各種パッケージがインストールされて、設定ファイル、テストのサンプルコードなどが作成されます。

├── node_modules
├── package-lock.json
├── package.json
├── playwright.config.ts
├── tests
│   └── example.spec.ts
└── tests-examples
    └── demo-todo-app.spec.ts

既存のプロジェクトに Playwright をインストール

% npm init playwright@latest
...
✔ Where to put your end-to-end tests? · tests
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true
Installing Playwright Test (npm install --save-dev @playwright/test)…

added 3 packages, and audited 219 packages in 3s
...

既存のプロジェクトにインストールした場合は、依存関係に以下の２つのパッケージが追加されました。

"devDependencies": {
    "@playwright/test": "^1.45.1",
    "@types/node": "^20.14.10",
...

ブラウザをインストール

Playwright で利用するブラウザをインストールするには、以下のコマンドを実行します。ここでインストールされるブラウザは、ホスト OS にインストールされる通常のブラウザとは異なり、Playwright がテスト実行時に使用するブラウザです。

% npx playwright install

引数で指定して、特定のブラウザを個別にインストールすることもできます。

% npx playwright install chrome

特定のブラウザで実行する

Playwright では、特定のブラウザを指定してテストを実行することができます。対象のブラウザは playwright.config.ts ファイルに定義します。以下の設定例では、WebKit と Chrome を指定しています。（設定できるデバイス一覧はこちらを参照）

projects: [
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },

    {
      name: 'chrome',
      use: { ...devices['Desktop Chrome'] },
    },
]

上記の通り設定してある場合は、webkit または chrome を project オプションに指定して実行することができます。project オプションを指定しなかった場合は、projects で定義されているブラウザで実行されます。また、ブラウザの定義が増えるとブラウザ毎に同じテストを実行するので、テストケース数が 5 件でブラウザの定義が 2 件の場合は、トータルで 10 件のテストが実行されることになります。

% npx playwright test --project webkit

ブラウザを起動しないで（ヘッドレス） またはブラウザを起動して実行する

ブラウザの起動を切り替えるオプションは、設定ファイルだとこちらのフラグで切り替えることができます。

また、実行時のオプションでブラウザで起動することもできます。

% npx playwright test --headed

テストをデバッグする

テストをデバッグする方法の１つとして、UI モードを利用してデバッグすることができます。UI モードを利用することで、テストのステップ実行や状態の表示、監視などテストケースをデバッグすることができます。
テスト実行後は、該当のソース、エラーの内容、コンソール Log 等の実行時の状態を詳細に確認することができます。

テストを UI モードで起動

% npx playwright test --ui

テストを実行

各テストが、ファイル、test コードの describe、テストケース毎に実行することができます。

ステップごとにテスト結果を確認

テスト結果をステップごとに確認することができます。これにより、アクション実行前、対象のアクション時、アクション後の DOM の状態を確認することができます。

Locator を確認

テスト実行時の DOM から Locator を確認することができます。これにより、DOM の要素がうまく操作できない場合などのデバッグがやりやすくなりそうです。

エラー内容の確認

テストがエラーとなった場合、テストケースが Failed となります。このテストケースの結果を開くと、エラーとなった処理、エラーの内容を確認することができます。

IntelliJ IDEA でテストを実行する

コマンドで実行することはできますが、IDE を使ってテストを実行することもできます。IntelliJ IDEA を利用した場合は、通常のテストランナーと同様に、テストコード上からテストやデバッグを実行することができます。VS Code の場合は Extension を利用することで実行できます。詳しくはこちらの公式ドキュメントを確認してください。

テストを実行

通常のテストコードの実行と同様に実行することができます。テスト対象のファイルを開き、対象のテストやテストグループのメニューから Run を選択するとテストが実行されます。

テストをデバッグ実行

通常のテストコードのデバッグと同様にデバッグ実行することができます。対象のテストのメニューから Debug を選択することでデバッグ実行となります。もしブレークポイントなどを設定して、DOM の状態を確認したいという場合は、ブラウザを起動して実行するように設定しておくことで、ブレークポイント時の DOM の状態も確認することができます。

失敗したテストをリトライする

不安定なテストがある場合、テスト全体が失敗し、再実行が必要になることがあります。そのような状況に備えて、リトライ設定をしておくと、失敗したテストを自動的に再試行することができます。

設定ファイルで指定

export default defineConfig({
  retries: 2,  // リトライ回数
});

コマンドで指定

% npx playwright test --retries=2

GitHub Actions で実行する

実装したテストを CI で実行できるように、GitHub Actions を設定します。その他の CI ツールでの設定方法も解説されているので、詳細は公式ドキュメントを確認してください。

ワークフローを作成

GitHub Actions のワークフローは以下のように実装しました。実行環境を構築して、テストを実行します。テスト結果を確認できるように結果レポートを GitHub Pages に配置します。なおテスト結果レポートについては公式のサンプルだとダウンロードして確認する手順となっていたので、環境に合わせて設定してください。
また、ワークフローをトリガーするイベントについても、プロジェクトな事情に合わせて、設定するのが良いと思います。

name: CI
on:
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  test:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        run: npm ci
      - name: Install Playwright Browsers
        run: npx playwright install --with-deps
      - name: Run Playwright tests
        run: npx playwright test
      - name: Setup GitHub Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: playwright-report/
      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

テストを実行

このワークフローは、workflow_dispatch イベントで手動トリガーを設定しています。手動でテストを実行し、テストが完了すると、実行結果をコンソールで確認することができます。

テスト結果レポートを確認

テスト結果のレポートが HTML で作成されるので、結果を確認してみます。テストの成否、テスト実行時間、エラー時はエラー内容などを確認することができます。

参照

ソース

試してみた実際のソースは、以下のリポジトリから確認することができます。