GitHub Actionsを使ってプルリクエストのCIにPlaywrightテストを追加する方法

著者

2022年10月14日

0 分で読めます

私と同じように、コードをマージする前の安心材料として、プルリクエスト（PR）のCIにテスト自動化のステップを組み込むのはとても有効だと感じている方も多いでしょう。この記事では、PRにPlaywrightテストを追加し、GitHub ActionsのCIワークフローですべてを連携させる方法を紹介します。

Playwrightを初めて知る方のために説明すると、Playwrightテスト自動化フレームワークは2017年に初版がリリースされましたが、最近ではMicrosoftの開発者向けツール（Visual Studio Codeなど）の一つとして人気が高まっています。

Playwrightテスト自動化フレームワークを使えば、エンドツーエンド（E2E）テストを簡単に作成でき、クロスブラウザー互換性も検証できます。以前、SeleniumとCypressの両方を使ったことがありますが、同じような経験があれば、Playwrightは後者のCypressを思い起こさせるでしょう。導入もテストの作成も簡単で、テストが不安定にならないようにする仕組みも組み込まれています。

この記事では、次の内容を学びます。

Playwrightでエンドツーエンドテストを書く基本
GitHub ActionsのCIでPlaywrightテストを実行する方法
デプロイしたNetlifyプレビューURLに対してPlaywrightテストを実行する方法
Playwrightのデバッグトレースを保存し、GitHub ActionsのCIでビルド成果物として利用できるようにする方法

始める前に一点。この記事のPlaywrightチュートリアルはJavaScriptを中心にしていますが、Playwrightの高度なテストの書き方ではなく、主にCIへの統合方法を説明しているため、Playwrightを使うPythonプロジェクトなど、ほかのプロジェクトにも簡単に応用できます。Java開発者向けには、Playwright Java SDKもあります。

プロジェクトにPlaywrightを追加してテストする

既存のJavaScriptプロジェクトにPlaywrightを追加します。作業は次のとおりです。

Playwrightのnpmパッケージをインストールします。npm install @playwright/test --dev
Playwrightのエンドツーエンドテスト専用のnpmライフサイクルフックを追加します。

変更内容はpackage.jsonファイルに次のように反映されます。ほかの内容や設定と合わせて、パッケージマニフェストに以下のコードスニペットを追加してください。

“scripts”: {
  "test:e2e": "playwright test"
},
4
"devDependencies": {
  "@playwright/test": "^1.22.2",
 }

次に、新しいPlaywrightテストファイルを./e2e/home.spec.tsに追加します。まだ存在しない場合は、プロジェクトのルートに新しいe2e/ディレクトリを作成します。

以下のコードスニペットは、エンドツーエンドテストにおけるPlaywrightの簡単な例です。Playwrightのテストケースを設定してhttp://localhost:3000に移動し、ウェブサイトのタイトル（通常はHTMLの<title>要素で定義）がDogs security blogという文字列と一致することを検証します。Playwrightの例：

1import { test, expect } from '@playwright/test';
2
3test('page should have title of "Dogs security blog"', async ({ page }) => {
4  await page.goto('http://localhost:3000/');
5  const title = await page.title();
6  expect(title).toBe(“Dogs security blog”);
7});

Playwrightによる自動テストを初めて導入する場合は、上記のpackage.jsonの設定と./e2e/home.spec.tsのコードスニペットで、Playwrightを動かす準備が整います。

サーバーまたはウェブアプリケーションがリクエストを受け付けていることを確認してください。その後、npm run test:e2eコマンドを実行し、Playwrightテストが正常に実行され、完了することを確認できます。

Playwrightのテスト出力は、次のようになります。

1npm run test:e2e
2
3> the-snyk-blog@0.1.0 test:e2e
4> playwright test
5
6Running 1 test using 1 worker
7
8  ✓  e2e/home.spec.ts:3:1 › page should have title of "Dogs security blog" (4s)
9
10  1 passed (14s)

やりました！Playwrightテストが動作しました。

GitHub Actionsを使ったPlaywrightの自動テスト

次に、継続的インテグレーション（CI）を設定しましょう。自分や外部のコントリビューターがプロジェクトに新しいコードを追加したときにテストを実行すれば、変更によって既存の機能が壊れないことを確認できます。

GitHubでプロジェクトを管理している場合、GitHub Actionsはプラットフォームに組み込まれているため、CI/CDワークフローとして簡単に利用できます。PR経由で新しいコードが追加されたときにPlaywrightテストのワークフローが起動し、エンドツーエンドのCIパイプラインが実行されるように設定しましょう。

まず、定義済みの設定を使ってPlaywrightをセットアップし、バックグラウンドでコマンドを実行してサーバーを起動するようにします。先ほどのようにPlaywrightのテストコードにURLを直接記述する代わりに、設定ファイルにURLを指定できます。

JavaScriptプロジェクトのルートディレクトリ（package.jsonファイルがある場所）にplaywright.config.tsという新しいファイルを作成し、以下を追加します。

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4  webServer: {
5    command: 'npm run start',
6    url: 'http://localhost:3000',
7  },
8};
9
10export default config;

ローカルのウェブサーバーが別のポートで稼働している場合は、上記のurl設定を変更して、CI環境でPlaywrightがアクセスできるようにしてください。

また、プロジェクトのビルド方法によっては、サーバーの起動前にnpm run buildを実行するように、package.jsonのstart npmライフサイクルフックを次のように更新する必要があるかもしれません。

1    "start": "npm run build && next start",

次に、Playwright用のGitHub Actionsワークフローを作成します。

.github/workflows/e2e-ci.ymlというパスに新しいファイルを作成し、次の内容を追加します。

1name: "Tests: E2E"
2on: [pull_request]
3jobs:
tests_e2e:
  name: Run end-to-end tests
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
    - name: install dependencies
      run: npm ci
    - name: install playwright browsers
      run: npx playwright install --with-deps
    - name: npm run test:e2e
      run: npm run test:e2e=

これで完了です！

GitHubリポジトリで新しいPRを作成し、tests_e2eワークフローが想定どおりに実行され、すべてのテストがパスすることを確認してください。

Playwrightのチュートリアルや記事で、PlaywrightのGitHub Actionリポジトリ（https://github.com/microsoft/playwright-github-action）やmicrosoft/playwright-github-action@v1アクションが紹介されているのを見たことがあるかもしれません。しかし、これらはもう必要ありません。公式GitHub Actionは非推奨となっており、上記のようにnpmでインストールしたplaywright CLIを使う方法が推奨されています。

デプロイしたNetlifyプレビューURLに対してPlaywrightテストを実行する方法

Netlifyでフロントエンドプロジェクトをビルドし、クライアント側のビルドを実際のウェブサイトにデプロイしている場合、PRと連携するNetlify Previewsも活用できます。新しいプルリクエストが作成または更新されるたびに、NetlifyがプロジェクトをURLにデプロイするため、そのPRのフロントエンドビルドの状態や品質を視覚的に確認し、操作できます。

Netlify botとのネイティブなGitHub連携は、次のように表示されます。

最新のコミット、デプロイログ、プレビュー、モバイル用QRコードへのリンクが表示された、デプロイプレビューの準備完了を知らせるダークテーマのNetlifyボット通知。

Netlify PreviewのURLに対してPlaywrightテストを実行するには、次の作業が必要です。

Playwrightの設定でベースURLを動的に指定できるように更新します。開発環境やCIでローカル実行する場合は、既定のlocalhost:3000に戻せるようにします。
Netlifyがフロントエンドのビルドに一意のURLを割り当てる際に使うPR番号を取得します。
Netlify PreviewのURLが利用可能になるまで待機します。
Netlify PreviewのURLに対してPlaywrightのエンドツーエンドテストを実行します。

まず、Playwrightの設定ファイルを更新しましょう。

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4    use: {
5        baseURL: process.env.PLAYWRIGHT_TEST_BASE_URL || 'http://localhost:3000'
6    },
7    webServer: {
8        command: "npm run start"
9    }
10};
11
12export default config;

この設定により、環境変数PLAYWRIGHT_TEST_BASE_URLを環境内またはCI内で動的に設定できるようになります。

次に、Playwrightのテストケースも更新します。URLを直接記述するのではなく、上記の設定ファイルで指定したbaseURLを使うようにします。./e2e/home.spec.tsのテストファイルを次のように更新してください。

1import { test, expect } from '@playwright/test';
2
3test('page should have title of "Dogs security blog"', async ({page, baseURL}) => {
4  await page.goto(baseURL);
5  const title = await page.title();
6  expect(title).toBe(“Dogs security blog”);
7});

最後に、.github/workflows/e2e-ci.ymlファイルを更新して、新しいステップを2つ追加します。一方のGitHub Actionでデプロイ先のURLが利用可能になるまで待機し、もう一方でテストを実行します。参考として、ワークフローファイル全体を以下に示します。

1name: "Tests: E2E"
2
3on: [pull_request]
4
5env:
GITHUB_PR_NUMBER: ${{github.event.pull_request.number}}
7
8jobs:
tests_e2e:
  name: Run end-to-end tests
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
    - name: install dependencies
      run: npm ci
    - name: install playwright browsers
      run: npx playwright install --with-deps
    - name: npm run test:e2e
      run: npm run test:e2e
21
tests_e2e_netlify_prepare:
  name: Wait for deployment on Netlify
  runs-on: ubuntu-latest
  steps:
    - name: Waiting for Netlify Preview
      uses: josephduffy/wait-for-netlify-action@v1
      id: wait-for-netflify-preview
      with:
        site_name: "pull-request"
        max_timeout: 180
32
tests_e2e_netlify:
  needs: tests_e2e_netlify_prepare
  name: Run end-to-end tests on Netlify PR preview
  runs-on: ubuntu-latest
  timeout-minutes: 5
  steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
    - name: install dependencies
      run: npm ci
    - name: install playwright browsers
      run: npx playwright install --with-deps
    - name: npm run test:e2e
      run: npm run test:e2e
      env:
        PLAYWRIGHT_TEST_BASE_URL: "https://deploy-preview-${{env.GITHUB_PR_NUMBER}}--pull-request.netlify.app/"
        DEBUG: pw:api

tests_e2e_netlify_prepareという名前の2つ目のステップでは、タイムアウトを任意に設定できます。ここでは3分に設定しています。

次に、tests_e2e_netlifyという名前の3つ目のステップは、ローカルで実行するPlaywrightテスト（このワークフローの最初のステップとして残しています）と似ていますが、Netlify PreviewのデプロイURLに合わせて動的に設定する環境変数PLAYWRIGHT_TEST_BASE_URLを指定する点が異なります。

さらに、最後のワークフローステップに新しい環境変数DEBUG: pw:apiを追加し、Playwrightのデバッグ機能を明示的に有効にして、より詳細な出力が得られるようにしました。

新しいPRを作成し、エンドツーエンドテストのワークフローが正常に完了することを確認してください。

Netlifyのプルリクエストプレビューで、Playwrightのエンドツーエンドテストが2件成功したことを示すGitHub Actionsのワークフロー。

おめでとうございます。GitHub Actionsを使った継続的インテグレーションにしっかりと組み込まれた、堅牢なPlaywrightのエンドツーエンドテスト自動化を構築できました。

CIでPlaywrightのデバッグを有効にする方法

Playwrightにはテストのデバッグに役立つ機能がいくつも組み込まれており、簡単にデバッグできます。まず、HTML要素を調べ、Playwrightのテストケースをステップごとにデバッグできるグラフィカルインターフェース、Playwright Inspectorがあります。また、記録したテストを再生できるPlaywright Trace Viewerも標準搭載されています。

Playwright Trace Viewerは、テストが不安定で、再現が難しい場合に特に便利です。エンドツーエンドテストでこのような問題が起きた場合、Playwrightのデバッグ機能を有効にして、すべての操作のトレースをファイルに保存できます。そのファイルをPlaywright Trace Viewerで開けば、テストが失敗した原因を調査できます。

続いて、後からこれらのファイルにアクセスできるよう、CIワークフローでPlaywrightのトレースを有効にする設定を行います。

GitHub公式のactions/upload-artifact GitHub Actionを使うと、ビルドで生成されたファイルやディレクトリの内容を成果物として保存できます。ただし、機密情報を含む可能性のあるログファイルやほかのデータは、誰でも閲覧できる状態で公開されるため、この方法で保存しないよう注意してください。

tests_e2eというジョブIDで識別される、既存のローカルエンドツーエンドテストに次のステップを追加します。

    - name: Upload test results
      if: always()
      uses: actions/upload-artifact@v2
      with:
        name: playwright-report
        path: test-results

Netlify PreviewのURLをテストするなど、Playwrightのデバッグが必要なほかのCIワークフローステップにも追加できます。

続いて、トレースファイルがリポジトリにコミットされないよう、.gitignoreファイルを更新し、次の内容を追加します。

1test-results/

最後に、Playwrightの設定ファイルplaywright.config.tsを更新して、トレースを有効にします。更新後は次のようになります。

1import { PlaywrightTestConfig } from '@playwright/test';
2
3const config: PlaywrightTestConfig = {
4  webServer: {
5    command: 'npm run start'
6  },
7  use: {
8    trace: 'on',
9  },
10};
11
12export default config;

これで完了です。では、デバッグ用の成果物はどこで確認できるのでしょうか。

CIの成果物には、GitHub Actionsの実行結果にあるSummaryタブからアクセスできます。次のスクリーンショットでは、CIで正常に完了したジョブの下部に成果物が表示されています。

エンドツーエンドテストの成功とplaywright-reportアーティファクトを示すGitHub Actionsのワークフロー。

ここで一点お伝えしておきます。ビルドが正常に完了したかどうかにかかわらず、ビルドごとにPlaywrightのデバッグトレースファイルを生成しています。これは、上記のtests_e2eジョブのステップでif: always()ディレクティブを使い、CI設定で常に実行するよう指定しているためです。

トレースファイルを表示するには、成果物をダウンロードしてローカルフォルダに展開し、その中にアーカイブファイルとして保存されたPlaywrightのデバッグ情報を見つけます。次のようにPlaywright独自のCLIで簡単に実行できます。

1npx playwright show-trace <my-directory>/my-trace.zip

PlaywrightとCypressの比較

Cypressを使ったことがある方なら、CLI、Playwrightテストの調査やデバッグに使えるライブのグラフィカルユーザーインターフェース、全般的な言語仕様など、Playwrightの自動化ツールにも使い慣れた印象を受けるでしょう。

Playwrightの仕組み

ブラウザを制御する主な仕組みとして、ライブラリをWebページのDOMに挿入するCypressとは異なり、PlaywrightはネイティブのブラウザAPIを使用して自動化を制御します。たとえば、Chromeブラウザとの通信には、リモートデバッグプロトコルとしてChromeのCDPを使用します。また、PlaywrightはChrome、Firefox、Edge、WebKitなど主要なブラウザすべてに対応しており、要素やアクションを自動で待機して不安定なテストを防ぐテストの回復力など、Cypressと同様の機能を備えています。

Playwrightによる自動化とは？

Playwrightは、マルチブラウザに対応したエンドツーエンドテストフレームワークを提供する、Microsoftのオープンソースプロジェクトです。ネイティブのブラウザ自動化フレームワークのAPIを使用してブラウザを制御・操作し、Playwright API向けの複数言語対応SDKを提供します。オープンソースで無料で使えることに加え、不安定なテストの軽減、ブラウザの完全な自動化、トレース、デバッグに対応している点が特長です。

Playwrightのテスト自動化についてさらに学ぶ

この記事を楽しんでいただき、Playwrightについてさらに知識を深めたいと思われた方には、次のリソースをおすすめします。

https://playwright.devのPlaywrightドキュメントは非常に充実しています。Playwrightのデバッグなどの専用セクションやPlaywrightの使用例があり、このテストフレームワークを初めて使う開発者もすぐに始められます。
Playwrightのニュースやチュートリアルなど、開発者向けの情報を知りたい方は、TwitterでDebbie O'Brienをフォローすることを強くおすすめします。MicrosoftでPlaywrightのプログラムマネージャーを務め、イベントでも定期的に講演しています。