GitHub Actions ではじめる Playwright E2E CI

GitHub Actions で Playwright を動かし、結果をレポート & ブランチ保護まで設定

初回公開日2025/7/17

最終更新日2025/7/17

前回のおさらい
まだ読んでいない方は
はじめての Playwright ─ “録画” で体験する E2E テスト入門
でローカル録画 → 実行を体験してみてください。
本記事はその「続編」で、ローカルで動かしたテストを GitHub Actions に載せる のがゴールです。

0. この記事で得られるもの

💡 やること	💪 得られるメリット
GitHub Actions で Playwright を自動実行	push / PR ごとに “壊れていない” を機械が保証
HTML レポートをアーティファクト添付	失敗したスクショや diff をチーム全員が確認
ブランチ保護ルールを設定	テストが緑 ✓ でないと main にマージ不可 → 品質ゲート完成

1. 前提：ローカルで E2E テストが動く状態

Next.js + shadcn/ui のフォーム例を使っている（前回記事サンプル）

簡単なフォームサンプルをGitHubに用意してありますので、そちらを利用いただくとこの記事と同様の体験が可能です。

GitHubのDELOGsリポジトリ

上記を利用する場合は下記を実行してください。

zsh

# クローン生成（本記事用のディレクトリへ）
git clone https://github.com/delogs-jp/playwright-e2e.git playwright-ci
cd playwright-ci

# 依存インストール（Playwright はまだ入っていない）
npm install 

2. Playwrightとテストファイルの準備

この節ははじめての Playwright ─ “録画” で体験する E2E テスト入門と重複する部分です。さらりと記述します。今回はテストパターンは「スクリーンショット差分でレイアウト崩れを検知」と「正常パターンだけすばやくテスト」の2パターンを用意します。

Playwrightのインストール

zsh

npm i -D @playwright/test
npx playwright install  # ブラウザバイナリを一括取得

スクリーンショット差分でレイアウト崩れを検知するテストファイルの作成

tests/contact-visual.spec.tsというファイルを下記内容で作成します。

ts : contact-visual.spec.ts

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

test("お問い合わせフォームのレイアウト", async ({ page }) => {
  await page.goto("/");  // playwright.config.tsでBaseurlを指定するのでパスだけ指定
  await page.setViewportSize({ width: 1280, height: 720 });

  await expect(page).toHaveScreenshot("contact-baseline.png", {
    threshold: 0.01, // 許容差分 1%
  });
});

フォームの正常パターンだけテストするテストファイルの作成

tests/contact-happy.spec.tsというファイルを下記内容で作成します。

ts : contact-happy.spec.ts

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

test("お問い合わせフォーム 正常送信", async ({ page }) => {
  await page.goto("/");  // playwright.config.tsでBaseurlを指定するのでパスだけ指定

  await page.getByLabel("お名前").fill("テスト太郎");
  await page.getByLabel("メールアドレス").fill("taro@example.com");
  await page.getByLabel("お問い合わせ内容").fill("Playwright の動作確認です。");

  await page.getByRole("button", { name: "選択してください" }).click();
  await page.getByRole("option", { name: "質問" }).click();

  await page.getByRole("button", { name: "送信" }).click();

  await expect(page).toHaveURL(/\/thanks/);
  await expect(
    page.getByRole("heading", { name: "送信ありがとうございました" })
  ).toBeVisible();
});

2. Playwright に “webServer” を設定

CI では 「サーバーを立てる → テスト → 自動終了」 が理想。
プロジェクト直下にplaywright.config.ts を作成して下記を記述します。

ts : playwright.config.ts

import { defineConfig } from "@playwright/test";
import path from "path";

const PORT = 3010; // ローカルと CI で共通ポート

export default defineConfig({
  testDir: "./tests",
  retries: 1,

  use: {
    baseURL: `http://localhost:${PORT}`, // テストファイルで指定するのは面倒なので
  },

// すべてのスナップショットに共通のテンプレート
  snapshotPathTemplate:
    "{testDir}/__screenshots__/{testFilePath}/{arg}{ext}",

// スナップショットの差分を検知-テストファイル側の設定が優先されるが、この設定がデフォルトに
// この設定がないと、完全一致しないとNGになってしまう
expect: {
    toHaveScreenshot: {
      /* 1.5% まで許容（必要に応じて微調整） */
      maxDiffPixelRatio: 0.015, // 0.015 = 1.5 %
    },
  },

  /* サーバーを自動起動 */
  webServer: {
    command: `npm run dev -- -p ${PORT}`, // Next.js を 3010 で起動
    port: PORT,
    reuseExistingServer: !process.env.CI,
  },
});

port … ローカルで複数のプロジェクトを立ち上げたときにポートが重複して、実行エラーになるのを避けるために使わなそうなポートを指定
baseURL … テストファイルで指定するのは面倒なのでここで指定。useブロックで指定
command … 開発ビルドでも本番ビルドでも OK
reuseExistingServer … CI 上では常に fresh、ローカルは再利用で時短

3. GitHub Actions ワークフローを作成

プロジェクト直下に

text

.github/
└─ workflows/
   └─ playwright.yml

.github/workflows/playwright.yml

`playwright.yml`（最小構成＋レポート出力）

yml : playwright.yml

name: E2E (Playwright)

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest

    steps:
      # 1) ソース取得
      - uses: actions/checkout@v4

      # 2) Node 環境
      - uses: actions/setup-node@v4
        with:
          node-version: 22.17.0

      # 3) 依存をインストール（Playwright の JS 本体もここで入る）
      - run: npm ci

      # 4)  Playwright ブラウザ & 依存ライブラリをインストール
      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      # 5) TypeScript 型チェック
      - run: npx tsc --noEmit

      # 6) Playwright テスト（HTML レポート）
      - run: npx playwright test --reporter=html

      # 7) レポートをアーティファクト化（失敗しても必ず実行）
      - uses: actions/upload-artifact@v4
        if: always()     # ← 失敗しても必ず実行
        with:
          name: playwright-report     # 名前は自由（日本語も可）
          path: playwright-report     # フォルダ or ファイルを指定
          retention-days: 3     # 保存日数（最大 90 日）

      # 8) Next.js 本番ビルド（任意だが品質ゲートに有益）
      - run: npm run build

補足：

ステップ	役割
`npx playwright install --with-deps`	Playwright ブラウザ & 依存ライブラリをインストール
`--reporter=html`	失敗スクショ & diff が HTML で閲覧可能
アーティファクト	失敗調査・デザイナー共有に便利。期限は `retention-days` で調整

アーティファクトとは？

これは今回はじめて出てきた言葉です。これは、CI の実行が終わったあとにも“手元に残しておきたいファイル” をGitHub が一時的に保管してくれる仕組みです。

GitHub Actions の “アーティファクト” に関する主な制限と動き

項目	仕様	詳細・補足
アップロードできるサイズ	1アーティファクト最大 ≈ 2 GB 1ワークフロー実行あたり総量 10 GB	これは `actions/upload-artifact` が内部で 2 GB を上限にチャンク転送しているためです（公式 README より）。巨大ファイルは分割か圧縮を推奨します。
リポジトリ／アカウントごとのストレージ枠	プライベート・リポジトリはプラン別枠に加算される例：GitHub Free は 500 MB、Team は 2 GB など	パブリック・リポジトリは課金対象外（実質無制限）。枠を超えると新しいアップロードが失敗し、枠を空けるか支払い上限を上げるまで保存できません。
保持期間 (retention)	デフォルト 90 日公開Repo：1-90 日非公開Repo：1-400 日	`upload-artifact` の `retention-days` 入力や、リポジトリ／組織設定で変更可能。
自動削除タイミング	期間を過ぎたアーティファクトは自動パージされる	削除・期限切れによる空き容量反映は 6〜12 時間ごとに更新
古いものから勝手に消えるか？	いいえ（キャッシュとは挙動が違う）	保存枠に上限があるのは総量。超過すると“最新アップロードが失敗”するだけで、古いアーティファクトは手動または retention 期限で消さない限り残ります。対して `actions/cache` は総量 10 GB を超えると最終アクセスが古い順に自動破棄される

古いものから勝手に消えるわけではないので、retention-daysでプロジェクトに合わせた適切な期間を指定する必要があります。容量を超えるとエラーになってテスト実行ができなくなってしまいます。

4. レイアウト崩れを検知用に一度テスト実行

レイアウト崩れを検知するには、ベースラインとなるキャプチャーが必要になります。これは一度ローカルでテスト実行することでキャプチャーがtests/配下に作成されるので、それを一緒にPushすることで、Git Actions でnpx playwright test --reporter=htmlを実行するだけで差分チェックが可能になります。

zsh

npx playwright test tests/contact-visual.spec.ts --reporter=html --update-snapshots

ついでに、フォームの正常終了側もあわせてテストして、テスト設定に不具合がないかチェックしておきます。

zsh

npx playwright test --reporter=html

上記のように（yamlファイルに記載したコマンドですが）テストファイルを指定しないとtests/ 配下のファイルをすべてテストしてくれます。

5. Push → Actions が走るか確認

GithubのリポジトリにPushします。下記は当サイトの環境にPushする例ですが、接続設定部分については皆さんの環境にあわせて変更してください。

zsh

# ご自分の環境に合わせてGit Hubに接続
git remote set-url origin git@github-delogs:delogs-jp/playwright-ci.git

# 全てステージしてコミット
git add .
git commit -m "ci: Add Playwright E2E workflow"

git push -u origin main

Actions タブ に “E2E (Playwright)” が生成 → ジョブ進行中
数分後に 緑 ✓ なら成功
playwright-report アーティファクトをダウンロード → index.html を開くとローカルと同じ UI

レポートのダウンロードの場所が少しわかりづらいのですが、上図の該当ワークフローをクリックして詳細を開き、詳細画面の下部にあります。下図の赤丸の場所です。

6. ブランチ保護で「緑 ✓ 以外はマージ不可」に

過去記事（GitHub設定編：最小構成 CI）と同じ手順ですが、
対象リポジトリの Settings → Branchesを開き「Add classic branch protection rule」をクリック して下図のようにします。

Branch name pattern: main
Require a pull request before mergingにチェック(任意)
Require status checks to pass before mergingにチェック
Require status checks…: e2e を選択
下部のCreateボタンをクリック

これで テストが赤 × の PR はマージできない 安全ゲートが完成。

7. 失敗を体験 → 修正フロー

はじめての Playwright ─ “録画” で体験する E2E テスト入門と同様にレイアウトのチェックでエラーを起こしてしっかり動くかを検証してみます。

過去記事（GitHub設定編：最小構成 CI）と同じ手順なので、項目だけ記述しておきます。

ブランチを作成 git switch -c feature/error-sample
フォームのボタン className="my-4" → my-[999px] に変えて、Push git push -u origin feature/error-sample
Actions が赤 × → 差分スクショ付きレポート
修正コミット → Push → 緑 ✓ → PR → マージ

チームメンバー全員が「壊したら赤 ×、直したら緑 ✓」を体験できます。