---
title: "Pest 4のブラウザテストの使い方｜pest-plugin-browserの導入と4.3.1の落とし穴【実測】"
url: "https://www.issoh.co.jp/tech/details/10349/"
published: 2025-12-22
updated: 2026-11-10
categories: ["テスト"]
publisher: "株式会社一創"
---

# Pest 4のブラウザテストの使い方｜pest-plugin-browserの導入と4.3.1の落とし穴【実測】

Pest 4は、PHPのテストフレームワークPestの4系で、Playwrightを使ったブラウザテストをPHPのテストコードから書けるようにした版です。ブラウザテストは別パッケージのpest-plugin-browserで提供され、4系の最新はPest 4.7.8（2026年8月3日公開）とプラグイン4.3.1（2026年4月8日公開）です。現行のメジャー版はPest 5系で、Pest本体の基本と5系の新機能は[PestPHPの解説記事（Pest 5.3対応）](/tech/details/7255/)にまとめています。本記事はPest 4のブラウザテストに絞り、2026年11月10日にmacOS（Intel）、PHP 8.5.8、Playwright 1.65.0で、Pest 4.7.8＋プラグイン4.3.1とPest 5.3.5＋プラグイン5.2.0を並べて動かした結果をもとに説明します。秒数はこの環境での参考値です。

## まとめ：Pest 4のブラウザテストの要点

- **導入は3コマンド**：`composer require pestphp/pest-plugin-browser --dev`、`npm install playwright@latest`、`npx playwright install`。プラグイン4.3.1はPlaywright 1.59.1未満だと全テストが「outdated」で落ちます。上限は無く、1.65.0でも動きました。
- **要素は`@名前`でdata-test属性を指定**できます。ただし4.3.1には、同じdata-testを共有するラジオで値を指定した検査が誤って失敗する不具合が残っています。name属性で指定すれば通ります。
- **4系のプラグインは4.3.1から更新されていません。**2026年10月29日の5.2.0で入った不具合修正（スクリーンショットの許容差、a11y検査の5秒上限など）は4系に来ていません。
- **ブラウザの既定はロケールen-US・タイムゾーンUTCです。**日本時間で日付を表示する画面は`withTimezone('Asia/Tokyo')`を付けて検査します。
- **ビジュアル回帰の初回は終了コード0です。**基準画像をコミットしないとCIでは毎回素通りします。
- **PHP 8.3ならPest 4に留まります。**8.4以上で、上の不具合に当たっているならPest 5へ上げる理由になります。Pest 4のバグ修正期限は2027年7月28日です。

## Pest 4で追加された機能と4系の現状

### Pest 4.0の公式告知に並んだ新機能

[公式の告知記事「Pest v4 Is Here — Now with Browser Testing」](https://pestphp.com/docs/pest-v4-is-here-now-with-browser-testing)が挙げた主な追加は次のとおりです。中心はブラウザテストで、他はその周辺を固める機能です。

| 機能        | 使い方                            | 要点                  |
| --------- | ------------------------------ | ------------------- |
| ブラウザテスト   | `visit('/')`                   | Playwrightで実ブラウザを操作 |
| スモークテスト   | `assertNoSmoke()`              | JSエラーとコンソール出力を一括検査  |
| ビジュアル回帰   | `assertScreenshotMatches()`    | 基準画像と画面を比較          |
| シャーディング   | `--shard=1/4`                  | テストを複数ジョブへ分割        |
| 型カバレッジ高速化 | `--type-coverage`              | 別プラグインが必要           |
| 不適切語チェック  | `--profanity`                  | 本体の依存に同梱            |
| 環境別スキップ   | `skipLocally()` ／ `skipOnCi()` | ローカルかCIかで実行を分ける     |

型カバレッジはpest-plugin-type-coverageを別に入れて使います。不適切語チェックは告知では別途導入と書かれていますが、4.0.0の時点で本体のcomposer.jsonが依存に含めており、Pest 4を入れれば`--profanity`がそのまま使えます。土台はPHPUnit 12です。Pest 3からの移行で影響が大きいのはスナップショット名の付け方の変更で、[公式アップグレードガイド](https://pestphp.com/docs/upgrade-guide)は`--update-snapshots`で作り直すよう指示しています。

### Pest 4の要件とバグ修正期限

[Packagistの公開記録](https://packagist.org/packages/pestphp/pest)と[Pest公式のサポートポリシー](https://pestphp.com/docs/support-policy)を並べると、版ごとの要件は次のようになります。

| 版      | PHP   | PHPUnit            | 初回リリース     | バグ修正期限         |
| ------ | ----- | ------------------ | ---------- | -------------- |
| Pest 3 | 8.2以上 | 11                 | 2024-09-09 | 2026-08-21（終了） |
| Pest 4 | 8.3以上 | 12（4.7.8は^12.5.33） | 2025-08-21 | 2027-07-28     |
| Pest 5 | 8.4以上 | 13（5.3.5は^13.4.5）  | 2026-07-28 | 未定             |

サポートポリシーは旧版のバグ修正を「最新版のリリースから12か月」と定めており、Pest 4はPest 5の初回リリースから12か月後の2027年7月28日まで修正対象です。

### 2026年11月10日時点の4系の更新状況

期限は残っていますが、2026年8月以降は4系のリリースがありません。2026年11月10日にGitHubで確かめると、Pest本体の4.xブランチはv4.7.8以降のコミットが0件でした。pest-plugin-browserの4.xブランチはv4.3.1以降に10件のコミットがありますが、CI設定の更新などで、不具合の修正は含まれていません。

一方、5系のプラグインは[2026年10月29日の5.2.0](https://github.com/pestphp/pest-plugin-browser/releases/tag/v5.2.0)でブラウザテストの不具合をまとめて直しました。Pest 4のブラウザテストで実際に当たる3件は、次の章で回避策と一緒に扱います。4系を使い続けるなら、2026年11月10日時点ではこれらの修正が公開されていないため、回避策を適用して運用します。

## pest-plugin-browserの導入とPlaywrightの版

### composerとnpmで入れる3つのコマンド

Pest 4を導入・初期化済みのプロジェクトに、pest-plugin-browserを追加します。Playwright本体はnpmで入れるため、PHPのプロジェクトでもNode.jsが必要です。

```
composer require pestphp/pest-plugin-browser --dev
npm install playwright@latest
npx playwright install
```

Pest 4のプロジェクトでは、版を付けなくてもComposerはプラグインの4系（4.3.1）を選びます。5系のプラグインはPest 5を要求するためです。[4系の公式ドキュメント](https://github.com/pestphp/docs/blob/4.x/browser-testing.md)は、テスト失敗時に保存されるスクリーンショットの置き場`tests/Browser/Screenshots`を`.gitignore`に加えるよう求めています。ビジュアル回帰の基準画像は別の場所（`tests/.pest/snapshots`）に保存され、こちらはコミットします。

プラグインはテスト開始時に`./node_modules/.bin/playwright run-server`を起動して接続します。プロジェクト直下に`node_modules`が無いと、すべてのテストが`PlaywrightNotInstalledException`で落ちます。Playwrightの導入で止まった場合の切り分けは[Playwrightのインストール方法とできない時の対処](/tech/details/3563/)で扱っています。

### プラグイン版ごとに上がるPlaywrightの最低版

プラグインのソース（PlaywrightNpmServer.php）には定数`PLAYWRIGHT_VERSION`があり、起動時に`playwright run-server --version`の結果と比べています。[タグごとのソース](https://github.com/pestphp/pest-plugin-browser/blob/v4.3.1/src/Playwright/Servers/PlaywrightNpmServer.php)で値を確かめると、パッチ版でも下限が上がっていました。公開日は[Packagistの記録](https://packagist.org/packages/pestphp/pest-plugin-browser)です。

| pest-plugin-browser | 公開日                   | 対応Pest | Playwright下限 |
| ------------------- | --------------------- | ------ | ------------ |
| 4.0.0〜4.3.0         | 2025-08-20〜2026-02-17 | 4系     | 1.54.1       |
| 4.3.1（検証日時点の4系最新）   | 2026-04-08            | 4系     | 1.59.1       |
| 5.0.0               | 2026-07-21            | 5系     | 1.61.1       |
| 5.1.2〜5.2.0         | 2026-10-02〜10-29      | 5系     | 1.63.0       |

Playwright 1.58.2でPest 4.7.8とプラグイン4.3.1を動かすと、テストは1件も実行されずに「Playwright is outdated.」の`PlaywrightOutdatedException`で落ちました。上限の確認は無く、2026年11月5日（米国時間）公開のPlaywright 1.65.0では4.3.1でもそのまま通りました。`package-lock.json`でPlaywrightを古い版に固定していると、`composer update`でプラグインのパッチ版が上がっただけでCIが赤くなります。`composer.lock`と`package-lock.json`は同じプルリクエストで更新してください。Playwrightの現行版は[Playwrightの最新バージョンの解説](/tech/details/9257/)で追っています。

### Firefox・Safari指定で「outdated」が出る原因

既定のブラウザはChromeで、`--browser firefox`や`--browser safari`で切り替えられます。`npx playwright install chromium`だけ実行した環境に`--browser firefox`を付けると、版の下限を満たしていても上と同じ`PlaywrightOutdatedException`が出ました。

プラグインのClient.phpは、Playwrightから返るエラー文に「Playwright was just installed or updated」が含まれると、一律に「outdated」の例外へ置き換えます。ブラウザ本体が無いときのエラーにもこの文が含まれるため、実際の原因はFirefoxの未導入です。版が下限を満たしているのにこの表示が出たら、`npx playwright install firefox`を実行してください。

## ブラウザテストの書き方：要素の指定と操作

### 素のPHPアプリに対する最小のテスト

Laravel以外のアプリでも、URLを完全な形で渡せばテストできます。次の例は、`php -S 127.0.0.1:8711 -t public`で起動した注文フォームを開き、題名とJavaScriptエラーの有無を確かめます。

```
<?php
// tests/Browser/OrderTest.php
const BASE = 'http://127.0.0.1:8711';

it('注文フォームが開く', function () {
    visit(BASE.'/radio.php')
        ->assertTitle('注文フォーム')
        ->assertNoJavaScriptErrors();
});
```

`./vendor/bin/pest`で実行すると、ヘッドレスのChromiumが起動して1秒前後で通ります。

この章と次の章のテストが開く`public/radio.php`は次の最小フォームです。送信先の`done.php`は、受け取った値を「受付: 氏名 / 色 / サイズ / gift=値」の形で1行表示するだけです。

```
<!doctype html><html lang="ja"><head><meta charset="utf-8"><title>注文フォーム</title></head><body>
<form method="post" action="/done.php">
  <label for="name">氏名</label><input id="name" name="name" data-test="name">
  <label><input type="radio" name="color" value="red" data-test="color"> 赤</label>
  <label><input type="radio" name="color" value="blue" data-test="color" checked> 青</label>
  <select name="size" data-test="size"><option value="s">S</option><option value="m">M</option></select>
  <label><input type="checkbox" name="gift" value="1" data-test="gift"> ギフト包装</label>
  <button type="submit" data-test="submit">注文する</button>
</form></body></html>
```

### @名前によるdata-test属性の指定と入力・送信

要素の指定は、表示文字列、CSSセレクタ（`.btn-primary`や`#submit-button`）、`@名前`の3通りです。`@名前`は[プラグインのGuessLocator.php](https://github.com/pestphp/pest-plugin-browser/blob/v4.3.1/src/Support/GuessLocator.php)で`[data-testid=名前], [data-test=名前]`に変換されます。文言やクラス名の変更でテストが壊れないよう、操作する要素にはdata-test属性を付けておくのが堅実です。

```
it('data-test属性で入力して送信する', function () {
    visit(BASE.'/radio.php')
        ->fill('@name', '山田')
        ->radio('color', 'red')
        ->select('@size', 'm')
        ->check('@gift')
        ->click('@submit')
        ->assertSee('受付: 山田 / red / m / gift=1');
});
```

このテストはプラグイン4.3.1で0.76秒、5.2.0で0.47秒で通りました。入力欄は`fill()`で値を置き換えます。4.3.1の`type()`も内部で`fill()`を呼ぶので結果は同じで、1文字ずつ打つのは`typeSlowly()`です。セレクトボックスは`select()`、チェックボックスは`check()`／`uncheck()`、ラジオは`radio(name, 値)`で操作します。ラジオの検査だけは4.3.1で注意が要るので、次の章で扱います。

### LaravelでactingAsとファクトリを使う例

Laravelでは`visit('/dashboard')`のように相対パスで書けます。プラグインがLaravelアプリを同じPHPプロセス内のHTTPサーバーで動かすため、`actingAs()`のログイン状態や、SQLiteのインメモリDBに作ったファクトリのデータがそのままブラウザから見えます。

```
<?php
// tests/Browser/DashboardTest.php
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;

uses(RefreshDatabase::class);

it('ログイン済みユーザーにダッシュボードが表示される', function () {
    $user = User::factory()->create(['name' => '山田']);
    $this->actingAs($user);

    visit('/dashboard')
        ->assertSee('ようこそ 山田 さん')
        ->assertNoJavaScriptErrors();
});

it('未ログインならログイン画面へ送られる', function () {
    visit('/dashboard')->assertPathIs('/login');
});
```

2026年10月3日にLaravel Framework 13.34.0で動かしたとき、設定は2か所必要でした。`pest --init`が作る`tests/Pest.php`は`pest()->extend(TestCase::class)->in('Feature')`なので`->in('Feature', 'Browser')`に広げること、`phpunit.xml`に`tests/Browser`を指すtestsuiteを足すことです。どちらかが漏れると`$this->actingAs()`が使えないか、テスト自体が見つかりません。サーバー側で例外が起きると、その内容が失敗メッセージに併記されます。loginという名前のルートが無いときは「Route \[login\] not defined.」が`assertPathIs`の失敗に続けて表示され、画面だけでは分からない原因をスタックトレースで追えました。

### 失敗したテストの調べ方

手元で原因を追うときは、`--headed`でブラウザの画面を出して実行するか、`--debug`で失敗した時点のまま画面を止めます。特定のテストだけ止めたい場合は、メソッドチェーンに`->debug()`を挟むと、そのテストだけが実行されて画面が開いたまま一時停止します。CIでは画面を出せないので、`->screenshot()`（全体は`fullPage: true`）や`->screenshotElement('#my-element')`で途中の画面を保存します。失敗したテストの画面は何もしなくても`tests/Browser/Screenshots`に保存されるため、CIの成果物としてこのディレクトリを残す設定にしておくと、手元で再現しなくても原因を絞れます。

## 端末・ダークモード・ロケール・タイムゾーンの指定

### 端末・ダークモード・タイムアウト

画面サイズは`visit('/')->on()->mobile()`でモバイル表示に、`on()->iPhone14Pro()`のように機種名でも指定できます。既定はライトモードで、`inDarkMode()`を付けるとダークモードで描画します。要素が出るまでの待ち時間の既定は5秒で、全テスト共通の値は`tests/Pest.php`に`pest()->browser()->timeout(10000)`のようにミリ秒で書きます。これは待機の上限値で、条件が成立しない検査では上限近くまで待つことがあります。すべての失敗に設定値が加算されるわけではありません。

### ロケール・タイムゾーンの既定値と日本向け設定

日本語のアプリで見落としやすいのがロケールです。タイムゾーンがJSTのMacでテストを動かしても、ブラウザの中は`navigator.language`がen-US、`Intl.DateTimeFormat().resolvedOptions().timeZone`がUTCでした。[PendingAwaitablePage.php](https://github.com/pestphp/pest-plugin-browser/blob/v4.3.1/src/Api/PendingAwaitablePage.php)がブラウザの文脈を作るときに`'locale' => 'en-US'`と`'timezoneId' => 'UTC'`を固定で渡しているためです。[Playwrightのドキュメント](https://playwright.dev/docs/emulation#locale--timezone)によれば、ロケールは`navigator.language`に加えてAccept-Languageヘッダーと数値・日付の書式にも効きます。

```
it('日本時間と日本語で表示する', function () {
    visit('/orders')
        ->withLocale('ja-JP')
        ->withTimezone('Asia/Tokyo')
        ->assertScript('Intl.DateTimeFormat().resolvedOptions().timeZone', 'Asia/Tokyo');
});
```

JavaScriptで日時を整形する画面や、Accept-Languageで表示言語を切り替えるアプリは、この2つを付けないと本番と違う表示を検査することになります。`withLocale('en-US')`と`withTimezone('America/New_York')`を付けた検証では、`assertScript()`で両方の値が切り替わったことを確かめられました。位置情報は`geolocation(緯度, 経度)`で指定します。

## スモーク・ビジュアル回帰・a11y検査の実際の挙動

### assertNoSmoke失敗時のタイムアウトと実行時間

`visit()`にURLの配列を渡して`assertNoSmoke()`を付けると、全ページのJavaScriptエラーとコンソール出力をまとめて検査します。公式は`assertNoJavaScriptErrors()`と`assertNoConsoleLogs()`をまとめたものと説明しています。

```
it('全ページでJSエラーが出ない', function () {
    visit([BASE.'/', BASE.'/broken.php'])->assertNoSmoke();
});
```

未定義の関数を呼ぶページを混ぜると、エラー文（Uncaught ReferenceError: undefinedFunction is not defined）とURLを示して失敗します。注意したいのは所要時間で、既定のタイムアウト5秒では5.95秒、`timeout(10000)`では10.54〜10.60秒かかりました。成功する検査は1秒前後で終わるのに対し、JavaScriptエラーで失敗する検査はタイムアウトまで待ってから終わりました。スモークテストを全ルートへ広げるときは既定の5秒から始め、正常なページでも時間切れになる場合に限って待ち時間を調整してください。対象ページの選び方は[スモークテストのCI/CDへの組み込み方](/tech/details/16256/)を参照してください。

### assertScreenshotMatchesの初回は終了コード0

`assertScreenshotMatches()`は、初めて実行したときに基準画像を作るだけで比較はしません。結果は「Snapshot created at \[tests/.pest/snapshots/…\]」と表示されたincomplete扱いで、終了コードは0でした。基準画像をリポジトリに入れずにCIで回すと、ジョブのたびに新しい基準画像が作られ、見た目が崩れても気づけません。運用は次の順に進めます。

1. 手元で1回実行して`tests/.pest/snapshots`を作り、コミットする。
2. 画面が変わると失敗し、その時の画面が`tests/Browser/Screenshots`に保存される。
3. 意図した変更なら`./vendor/bin/pest --update-snapshots`で基準画像を更新してコミットする。

フォントの描画がOSで変わるため、基準画像はCIと同じOSで作るほうが誤検知が減ります。4.3.1では、画面の不一致はPlaywright側のエラーとして「Expect failed」で返り、[PR #251](https://github.com/pestphp/pest-plugin-browser/pull/251)の説明どおり差分画像を作る処理まで進みません。`--diff`に頼らず、失敗時に保存された画面と基準画像を見比べます。

### assertNoAccessibilityIssuesの検出水準

`assertNoAccessibilityIssues()`はaxe-coreでページを検査し、既定ではレベル1（serious）以上の問題があると失敗します。ラベルの無い検索欄を置いたページでは、次のように重大度・ルール・該当要素が並びました。

```
1 Accessibility issues found
- [critical] Form elements must have labels https://dequeuniversity.com/rules/axe/4.10/label?application=axeAPI
  Selector: #q
  HTML: <input name="q" id="q" value="">
```

`<label for="q">`を足すと通りました。レベルは0（critical）から3（minor）まで選べます。既存サイトにいきなり3を当てると細かな指摘で埋まるため、0か1から始めて段階的に上げるのが現実的です。

## プラグイン4.3.1に残る不具合と回避策

### data-testを共有するラジオの誤判定と回避策

赤・青のラジオに同じ`data-test="color"`を付け、青を選択済みにしたページで`assertRadioSelected('@color', 'blue')`を実行すると、4.3.1では5.38秒待った末に失敗しました。

```
Expected radio button [@color] with value [blue] to be selected on the page initially
with the url [http://127.0.0.1:8711/radio.php], but it was not.
```

同じテストはPest 5.3.5＋プラグイン5.2.0では0.13秒で通ります。[5.2.0に入った修正（PR #220）](https://github.com/pestphp/pest-plugin-browser/pull/220)が直したのは、`@名前`の解決処理です。4.3.1のGuessLocator.phpはdata-test属性の分岐で値を使わずに要素を返すため、同じ名前の最初の要素（赤）を検査していました。4.3.1で回避するには、ラジオとチェックボックスのグループだけはname属性で指定します。`assertRadioSelected('color', 'blue')`と`assertRadioNotSelected('color', 'red')`は4.3.1でも0.53秒で通りました。

### a11y検査の5秒上限とスクリーンショットの許容差

4.3.1のMakesConsoleAssertions.phpは、axe-coreの実行を`Playwright::usingTimeout(5_000, …)`で包んでいます。`pest()->browser()->timeout(15000)`のように全体の待ち時間を延ばしても、a11y検査だけは5秒で打ち切られます。[5.2.0の修正（PR #289）](https://github.com/pestphp/pest-plugin-browser/pull/289)は、約120件の一覧を持つページを遅いCIで検査したとき、違反が無いのに「Timeout 5000ms exceeded」で落ちた事例を挙げています。4系では、要素数の多いページのa11y検査をCIから外すか、ページを分けて検査します。

ビジュアル回帰も4.3.1では許容差が効きません。[PR #251](https://github.com/pestphp/pest-plugin-browser/pull/251)によれば、PNGのバイト列が基準画像と違うと、Playwrightのピクセル比較が一致と判定しても失敗として扱っていました。Chromiumの出力したPNGはバイト単位では再現しないため、アンチエイリアスの数ピクセルで無作為に落ちることがあると説明されています。4系でビジュアル回帰が不安定なら、対象をレイアウトの崩れが重大な数ページに絞り、失敗時は基準画像と保存したスクリーンショットを別途比較して目視判断する運用にします。

### 4系に無いoffline()と–slow-mo

5.2.0では、通信を遮断する`offline()`／`online()`と、操作ごとに待ちを入れて画面で追いやすくする`--slow-mo`が加わりました。4.3.1で`offline()`を呼ぶと「Call to undefined method Pest\\Browser\\Api\\Webpage::offline()」、Pest 4.7.8に`--slow-mo=100`を渡すと「Unknown option “–slow-mo”」になります。オフライン時の表示を検査したいなら、Pest 5へ上げる理由になります。

## CIでの並列実行とシャーディング

### ブラウザテスト3件での逐次実行と並列実行の比較

公式ドキュメントはブラウザテストを`--parallel`で走らせるよう勧めています。ただしブラウザテスト3件で比べると、逐次実行が2.5〜3.4秒、16プロセスの並列実行が3.3秒前後で、差は出ませんでした。プロセスとブラウザの起動にかかる時間が、並列化で縮む時間を打ち消したと考えられます。1回の実行が数分かかるようになってから並列化を検討しても遅くはありません。`--parallel`を付けると`--exclude-filter`は「option does not exist」で受け付けられませんでした。並列実行の内部はparatestで、使えるオプションが逐次実行と異なります。

### –shardのファイル単位分割と時間配分

`--shard=1/2`と`--shard=2/2`で実行すると、それぞれ「1 file ran, out of 2.」と表示されました。分割の単位はテストの1件ではなくテストファイルです。重いテストを1ファイルに詰め込むと、そのジョブだけが遅れます。Pest 4.6.0（2026年4月14日公開）からは`--update-shards`が加わり、テストクラスごとの所要時間を`tests/.pest/shards.json`に記録して、時間が均等になるように振り分けます。このファイルは全件が成功した実行でだけ書かれ、失敗を含む実行では作られませんでした。GitHub Actionsでは次のように書けます。

```
jobs:
  browser-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    name: Tests (Shard ${{ matrix.shard }}/4)
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - run: composer install --no-interaction
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: ./vendor/bin/pest --parallel --shard=${{ matrix.shard }}/4
```

`--with-deps`はブラウザ本体に加えて、ブラウザが必要とするOSのライブラリも入れるオプションで、Pest公式のCI手順も指定しています。ワークフロー全体の組み立ては[GitHub Actionsでビルド・自動テストを設定する方法](/tech/details/2497/)を参照してください。テストの実行基盤づくりから任せたい場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)でテスト自動化の設計を含めて相談を受けています。

## Pest 4に留まるかPest 5へ上げるかの判断

### Laravel 13のPHPUnit制約とPest 5への更新手順

Laravelの新規プロジェクトの雛形（laravel/laravelのcomposer.json）は、2026年11月10日時点でも開発用依存に`"phpunit/phpunit": "^12.5.12"`を持っています。このまま`composer require pestphp/pest pestphp/pest-plugin-browser --dev -W`と版を付けずに入れると、ComposerはPest 4.7.8とプラグイン4.3.1を選びました。PHPが8.5でも同じです。`"pestphp/pest:^5.0"`だけを指定すると、PHPUnit 12の制約と衝突して解決に失敗します。Pest 5へ上げるには、PHPUnitも同時に上げます。

```
composer require "pestphp/pest:^5.0" "pestphp/pest-plugin-browser:^5.0" "phpunit/phpunit:^13.3" --dev -W
npm install -D playwright@latest
npx playwright install
```

2026年10月3日の検証では、この3つの同時指定でLaravelのブラウザテスト2件がコードを変えずに通りました。11月10日の検証でも、data-test属性で入力して送信するテストは4.3.1と5.2.0の両方で無修正のまま通っています。プラグイン5.1.2以降のPlaywright下限は1.63.0なので、npm側も上げます。

### PHP版とPHPUnit拡張の互換性による移行判断

- **本番のPHPが8.3**：Pest 4に留めます。Pest 5はPHP 8.4以上が必須です。ラジオはname属性で指定し、a11y検査は大きなページを避けます。
- **PHP 8.4以上で、PHPUnit 12向けの拡張に依存していない**：Pest 5へ上げます。5.2.0の不具合修正と`offline()`が使え、4系の回避策が要らなくなります。Pest 5本体の新機能は[PestPHPの解説記事](/tech/details/7255/)で扱っています。
- **PHP 8.4以上でも、PHPUnit 12向けのサードパーティ拡張を使っている**：その拡張がPHPUnit 13に対応するまでPest 4に留めます。

### Laravel DuskからPest 4へ移るかの判断

[LaravelのDusk公式ドキュメント](https://laravel.com/docs/13.x/dusk)は冒頭で「Pest 4 now includes automated browser testing which offers significant performance and usability improvements compared to Laravel Dusk. For new projects, we recommend using Pest for browser testing.」と書き、新規プロジェクトにはPestのブラウザテストを勧めています。DuskはChromeDriverでブラウザを操作し、PestはPlaywrightを使います。

新規はPestで始めるのが妥当です。Duskのテストが大量に動いている既存プロジェクトで一括移行する必要はありませんが、両者を同じプロジェクトに置くときはテストのディレクトリを分けます。Pestを入れたプロジェクトで`php artisan dusk:install`を実行すると、`tests/Pest.php`の先頭に`pest()->extend(Tests\DuskTestCase::class)->in('Browser')`が追記されます。Pestのブラウザテストを同じ`tests/Browser`に置いていると、`./vendor/bin/pest`が1件も実行せずに「The folder \[…\] already uses the test case \[Tests\\DuskTestCase\].」で止まりました。Pestのブラウザテストを`tests/E2E`に移し、`tests/Pest.php`と`phpunit.xml`の指定を合わせると両方が通りました。Duskの導入とCI設定は[Laravel Duskでテスト自動化する方法](/tech/details/5648/)、E2Eテスト全体のツール選びは[E2Eテストのベストプラクティス](/tech/details/5470/)で解説しています。

## よくある質問

### Pest 4とPest 5のブラウザテストの違いは何ですか？

書き方は共通で、今回検証したテストはPest 5でもコードを変えずに動きました。違いは要件と不具合修正です。Pest 4はPHP 8.3以上・PHPUnit 12、Pest 5はPHP 8.4以上・PHPUnit 13が必要です。ブラウザテストのプラグインは4系が4.3.1で止まっており、2026年10月29日の5.2.0で直ったラジオの検査、a11y検査の5秒上限、スクリーンショットの許容差の不具合は4系に残っています。

### Pest 4のサポートはいつまでですか？

Pest公式のサポートポリシーでは、Pest 4のバグ修正期限は2027年7月28日です。ただし2026年11月10日時点で、4系の最新リリースは本体が2026年8月3日の4.7.8、ブラウザテストのプラグインが2026年4月8日の4.3.1で、それ以降の公開はありません。

### pest-plugin-browserとPlaywrightの対応版はどう確かめますか？

プラグインのソースにある定数`PLAYWRIGHT_VERSION`が下限です。4.3.1は1.59.1、5.1.2と5.2.0は1.63.0でした。上限は無く、Playwright 1.65.0は4.3.1でも動きました。手元の版は`npx playwright --version`で確認できます。

### Laravel DuskからPest 4のブラウザテストへ移行すべきですか？

新規プロジェクトならPestを選びます。Laravel公式のDuskドキュメントも新規ではPestを推奨しています。動いている既存のDuskテストは書き直しを急がず、Pestのブラウザテストを`tests/E2E`のような別ディレクトリに置いて共存させます。

### PHPUnitで書いた既存のテストはPest 4でも動きますか？

PHPUnit 12に対応する既存テストなら動きます。PestはPHPUnitの上で動くため、`PHPUnit\Framework\TestCase`を継承したクラス形式のテストも`./vendor/bin/pest`でそのまま実行されます。Laravel 13の新規プロジェクトでは、標準のクラス形式のテスト2件とPestで書いたブラウザテスト2件が同じ実行で4件とも通りました。

## 関連記事

- [PestPHPとは？PHPUnitとの違い・導入手順と使い方｜Pest 5.3を実測で解説](/tech/details/7255/)
- [Laravel Duskでテスト自動化する方法｜導入・書き方・CI実行【8.7.2実測】](/tech/details/5648/)
- [Playwrightの最新バージョンは1.65｜確認・更新方法とリリース履歴【2026年11月】](/tech/details/9257/)
- [Playwrightのインストール方法とできない時の対処｜バージョン確認・Windows・Python](/tech/details/3563/)
- [E2Eテストとは？結合テストとの違いとエンドツーエンドテストのベストプラクティス【Playwright 1.64で実測】](/tech/details/5470/)

---

出典: [Pest 4のブラウザテストの使い方｜pest-plugin-browserの導入と4.3.1の落とし穴【実測】](<https://www.issoh.co.jp/tech/details/10349/>)（株式会社一創）
