Pest on ララジャパン

Pest4のE2Eテスト - セットアップ〜テストコードの実装例

Wed, 10 Dec 2025 07:22:45 +0900

Pest4からブラウザテスト機能が追加され、簡単なセットアップだけでPlaywrightを使ったE2Eテストが使えるようになりました。今回はLaravelで作成したプロジェクトを使って、セットアップからテストコード作成までの流れを実際に試してみます。

セットアップ

私の環境ではユニットテストとしてすでにPestを導入済みですが、もしPHPUnit環境の方は移行に関する以下の記事もご参照ください。

LaravelのPHPUnitテストをpest-plugin-driftでPestへ変換

ブラウザテストはPest v4系で利用できるため、まずPestを更新します。

$ composer require pestphp/pest --dev --with-all-dependencies

v4.1.4に更新されました。次にブラウザテスト用のプラグインをインストールします。

$ composer require pestphp/pest-plugin-browser --dev

そして、Playwright本体とブラウザをインストールします。

$ npm install playwright@latest
$ npx playwright install

次に、スクリーンショットの保存ディレクトリをgitignoreに追記します。ドキュメントに記載の通り、テスト実行時に生成されるスクリーンショットをGit管理から外しておくためです。

保存先はブラウザテストのディレクトリによって変わります。私の環境ではtests/Browserにテストを配置するため、以下のようになります。

.gitignore

...
tests/Browser/Screenshots

ここまでで準備は完了です。動作確認用に、画面遷移・表示確認だけの以下のようなシンプルなテストを作成しました。

tests/Browser/BrowserTest.php

it('example', function () {
    $page = visit('/');
    $page->assertSee('Laravel');
});

テストを実行します。テスト用のサーバーが自動で起動するので、php artisan serveは不要です。

$ ./vendor/bin/pest tests/Browser/BrowserTest.php

   FAIL  Tests\Browser\BrowserTest
  ⨯ it example                  0.04s  
  ────────────────────────────────────────────────  
   FAILED  Tests\Bro…  BindingResolutionException   
  Target class [config] does not exist.

テストが失敗してしまいました。新しく作成したBrowserディレクトリが、Pestの設定ファイルに追加されていないことが原因のようです。

Pest.phpを以下のように修正しました。Browserを追加しています。

tests/Pest.php

pest()->extend(Tests\TestCase::class)
・・・
    ->in('Feature', 'Browser');

もう一度テストを実行してみます。

$  ./vendor/bin/pest tests/Browser/BrowserTest.php

   PASS  Tests\Browser\BrowserTest
  ✓ it example                  1.33s  

  Tests:    1 passed (1 assertions)
  Duration: 1.99s

テストが通りました！これで準備完了です。

新規作成フロー・テストコード全体

セットアップが整ったので、ここでは実際に作成したブラウザテストのコード全体を先にご紹介します。

テスト対象は前回も使用した英語日記アプリの新規作成機能です。

新規作成は３段階の画面遷移になっており、「日本語入力画面 → 英訳を入力・AI翻訳を実行 → 確認して保存」という流れになっているので、テストでは各画面でのテキスト入力や遷移の動作を確認しています。

また１日の入力文字数には制限があるので、入力したテキストの文字数によって文字数のカウント表示が正確に更新されているか、も確認しています。

use App\Models\User;

it('日記新規作成', function () {

    User::factory()->create([
        'email' => 'test@example.com',
        'password' => bcrypt('password'),
    ]);

    // ログインページへ移動
    $page = visit('/login');

    // メールアドレスとパスワードを入力
    $page->fill('email', 'test@example.com')
        ->fill('password', 'password')
        ->click('ログイン')
        ->assertPathIs('/user/diary');

    // 新規作成ページへ移動
    $page->click('a[href*="/diary/create"]')
        ->assertPathIs('/user/diary/create');

    // 入力テキストを準備
    $japaneseText = '今日は素晴らしい一日でした。';
    $englishText = 'Today was a wonderful day.';

    // 文字数カウンター確認用に、入力前の残り文字数を取得
    $initialRemaining =  (int)$page->text('#char_count');

    $inputLength = mb_strlen($japaneseText);
    $expectedRemaining = $initialRemaining - $inputLength;

　　 // 画面１: 日本語で入力
    $page->fill('native_content', $japaneseText)
        // 文字数カウンターの確認（計算した値と一致するか）
        ->assertSee("残り文字数: {$expectedRemaining}")
        ->click('次へ！');

    // 画面２: 英訳を入力
    $page->assertSee('英語で書いてみよう！')
        ->fill('user_translation', $englishText)
        ->click('翻訳する');

    // 翻訳中の画面表示が消えるまで待機
    $page->page()->getByText('翻訳中...')->first()->waitFor(['state' => 'hidden']);

    // 画面３への遷移待機
    $page->wait(1);

    // アサートに必要なデータの取得
    $aiTranslation = $page->value('translated_content');
    expect($aiTranslation)->not->toBeEmpty('AI翻訳結果が空です');

    // 画面３: 保存
    $page->click('保存')
        ->assertSee('日記が作成されました。')
        // 詳細画面での表示確認
        ->assertSee($aiTranslation)
        ->assertSee($japaneseText);
});

複数の画面遷移を含むのでコードは少し長めですが、メソッド名はどれもシンプルで分かりやすいので流れは追いやすいかと思います。

では続いて、今回のテストで使用したメソッドをまとめます。

画面遷移・操作系メソッド

まず、画面遷移にはvisit()を使用します。pageオブジェクトが返るので、後続のコードでは$pageを元に、画面を操作したりアサートしたりする形になります。

$page = visit('/login');

入力・クリック操作は、fill()・click()を使用します。

$page->fill('email', 'test@example.com')
    ->fill('password', 'password')
    ->click('ログイン')

上記のコードでは、email・passwordというname要素に指定の文字列を入力後、ログインボタンをクリックしています。

また指定の時間待機したい時はwait()を使用し、引数に秒数を渡します。

$page->wait(1);

要素の値を取得するメソッド

次に、要素の値を取得する時は、text()・value()を使用します。

text()は、HTML要素内のテキストを取得します。以下の例では、idにchar_countを持つ要素からテキストを取得しています。

$initialRemaining = $page->text('#char_count');

またvalue()は、input・textarea・selectなどフォーム要素のvalue値を取得します。以下のコードでは、idがtranslated_contentという要素から文字列を取得しています。

$aiTranslation = $page->value('translated_content');

セレクタの指定について

ここまでの例で、セレクタの指定方法が複数混在していることに気づかれた方もいるかもしれません。

text(’#char_count’)のようにid明示するケースや、click(‘a[href*="/diary/create"]’)のようにcssセレクタを直接指定する書き方、click(‘ログイン’)のように文字列だけを渡しているケースなどがあります。

これはPestで定義されているGuessLocator機能のおかげです。GuessLocatorは、以下の優先順位で引数の情報から自動で要素を選択してくれます。

#や.で始まる場合 → CSSセレクタとしてそのまま使用
@で始まる場合 → data-testid/data-test属性として検索
通常の文字列の場合 → id、name属性として検索
上記で無い場合は文字列として要素を検索

こちらの詳細は、vendor/pestphp/pest-plugin-browser/src/Support/GuessLocator.phpに定義されています。

アサーション系

続いてアサーションです。URLの確認には、以下のようにassertPathIs()を使用します。

$page->click('ログイン')
    ->assertPathIs('/user/diary');

またassertSee()では、ページ内に引数のテキストが表示されているかを確認します。

$page->assertSee("日記が作成されました。");

使用可能なLaravelのメソッド

Pest4のブラウザテストでは、Laravelのテストヘルパーメソッドも使用できます。

先ほどのテスト内で使用しているfactory()だけでなくactingAs()・assertAuthenticated()なども使えるので、ユーザーログインの手順をスキップしたい場合は以下のように簡略化できて便利です。

    $user = User::factory()->create([
・・・
    ]);

    $this->actingAs($user);
    $this->assertAuthenticated();
・・・

Playwrightのメソッドを使いたい場合

最後に、Pestのメソッドだけでは対応できない場合についてご紹介します。

今回のテストでは「特定の要素が非表示になるまで待機」という処理が必要でしたが、Pestの標準メソッドにはPlaywrightのwaitFor()に該当する機能がありませんでした。このような場合は、page()メソッドを使ってPlaywrightオブジェクトに直接アクセスできます。

    $page->page()->getByText('翻訳中...')->first()->waitFor(['state' => 'hidden']);

このコードでは、「翻訳中…」というテキストを持つ要素を取得し、その要素がhiddenになるまで待機させる処理を、Playwrightオブジェクトを経由して実行しています。

まとめ

テストコードの書き方自体は、CypressやPlaywrightを単体で使う場合と比べても大きな違いはないかなと思いました。

ただ今回のPest4はLaravelのテストとしてブラウザテストをプロジェクトに統合できるため、factoryでのテスト用レコードの生成や、認証ヘルパーなどがそのままE2Eテストに使用できます。その点が他と比べてもとても便利だと感じました。

Pestの「dataset」活用で、見通しが良い・修正しやすいテストコードへ

Sun, 09 Mar 2025 08:39:49 +0900

テストを書くとき、テストパターンや入力値の組み合わせが増え、データの管理が煩雑になりがちです。Pestではwith()やdataset()を使って基本的なデータ整理ができますが、後から読んでも理解しやすい・修正しやすいコードを目指して、Combining DatasetsやSharing Datasetsを活用し、テストコードを整理してみます。

テスト対象

テスト対象は以下のクラスです。calculateShippingCost()は、引数として渡された温度帯と配送地域の値に応じて送料を計算する関数です。

class ShippingCalculator
{
    private static array $tempCosts = [
        '常温' => 0,
        '冷蔵' => 200,
        '冷凍' => 500,
    ];

    private static array $regionCosts = [
        '東京' => 500,
        '大阪' => 750,
        '福岡' => 1000,
    ];

    /**
     * 温度帯と配送地域から送料を計算する
     */
    public static function calculateShippingCost(string $temp, string $region): int|string
    {
        if (!array_key_exists($temp, self::$tempCosts) || !array_key_exists($region, self::$regionCosts)) {
            return '計算不可';
        }
    
        $baseCost = self::$regionCosts[$region];

        $tempCost = self::$tempCosts[$temp];
        
        return $baseCost + $tempCost;
    }
}

例えば、温度帯が「冷蔵」の場合は200円、配送地域が「大阪」の場合は750円を取得し、合計送料として950円を返します。

> ShippingCalculator::calculateShippingCost('冷蔵', '大阪');
= 950

また、定義されていない値が渡された場合は「計算不可」が返ります。

> ShippingCalculator::calculateShippingCost('でたらめ', '大阪');
= "計算不可"

テストコード

以下はcalculateShippingCost()の計算結果が正しいことを検証するテストコードです。

テストのパターンとして、温度帯と配送地域をいくつかピックアップしてテストする形でもいいかもしれませんが、今回は全ての組み合わせ（３つの温度帯×３つの配送地域 = ９パターン）をテストします。

it('全ての組み合わせパターンで送料を検証', function (string $temp, int $tempCost, string $region, int $regionCost) {

    // 期待される合計送料
    $expected = $tempCost + $regionCost;
        
    // 実際の計算結果
    $actual = ShippingCalculator::calculateShippingCost($temp, $region);
    
    expect($actual)->toBe($expected);
})
->with([
    ['常温', 0, '東京', 500],    // １回目
    ['常温', 0, '大阪', 750],    // ２回目
    ['常温', 0, '福岡', 1000],   // ３回目
    ['冷蔵', 200, '東京', 500],  // ４回目
    ['冷蔵', 200, '大阪', 750],  // ５回目
    ['冷蔵', 200, '福岡', 1000], // ６回目
    ['冷凍', 500, '東京', 500],  // ７回目
    ['冷凍', 500, '大阪', 750],  // ８回目
    ['冷凍', 500, '福岡', 1000], // ９回目
]);

Pestでは、with()を使用してデータパターンをテストに渡します。with()には複数のテストデータを配列で渡せるため、今回のように多次元配列を使うことで、各配列が1回分のテストデータとして処理されます。

まずはwith()に９パターンを直接記述しましたが、パターンが多いとテストコードと繋がって少しごちゃごちゃして見えますね。そういう場合はdataset()を使用すると、以下のようにテストとパターンを分離させて書くことができます。

it('全ての組み合わせパターンで送料を検証', function (string $temp, int $tempCost, string $region, int $regionCost) {
・・・テストコードは同じ
})
->with('shippingCosts');

dataset('shippingCosts', [
    ['常温', 0, '東京', 500],
    ['常温', 0, '大阪', 750],
    ['常温', 0, '福岡', 1000],
    ['冷蔵', 200, '東京', 500],
    ['冷蔵', 200, '大阪', 750],
    ['冷蔵', 200, '福岡', 1000],
    ['冷凍', 500, '東京', 500],
    ['冷凍', 500, '大阪', 750],
    ['冷凍', 500, '福岡', 1000],
]);

dataset()は第一引数にデータセット名を、第二引数は先ほどwith()に渡していたデータの配列を指定します。

そしてwith()の方へはデータセット名を指定するだけで良いのでテストが少しすっきりと、可読性が良くなりました。

Combining Datasetsの活用

ここまでの書き方でも問題ありませんが、９パターンが並んでいて分かりにくい点や、パターンが増減した際の修正が大変な点が気になります。

そこで、Combining Datasetsを活用します。全ての組み合わせをテストする時はCombining Datasetsを使うとコードをとても簡潔に書くことができます。

まずは９パターンあったデータセットを、「温度帯」と「配送地域」のそれぞれのデータセットに分けて作成します。

dataset('tempWithCost', [
    ['常温', 0],
    ['冷蔵', 200],
    ['冷凍', 500],
]);

dataset('regionWithCost', [
    ['東京', 500],
    ['大阪', 750],
    ['福岡', 1000],
]);

「温度帯」の３パターンはtempWithCostに、「配送地域」の３パターンはregionWithCostと定義しました。

そしてこれをテスト側でどう呼び出すかというと、以下のようにwith()を連結させるだけです。

it('全ての組み合わせパターンで送料を検証', function (string $temp, int $tempCost, string $region, int $regionCost) {
...
})
->with('tempWithCost')
->with('regionWithCost');

ちゃんと９パターン全て網羅されるのか、テストを実行して確認します。

PASS  Tests\Unit\ShippingCalculatorTest
  ✓ it 全ての組み合わせパターンで送料を検証 with ('常温', 0) / ('東京', 500)                                                                                                0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('常温', 0) / ('大阪', 750)                                                                                                0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('常温', 0) / ('福岡', 1000)                                                                                               0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('冷蔵', 200) / ('東京', 500)                                                                                              0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('冷蔵', 200) / ('大阪', 750)                                                                                              0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('冷蔵', 200) / ('福岡', 1000)                                                                                             0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('冷凍', 500) / ('東京', 500)                                                                                              0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('冷凍', 500) / ('大阪', 750)                                                                                              0.01s  
  ✓ it 全ての組み合わせパターンで送料を検証 with ('冷凍', 500) / ('福岡', 1000)                                                                                             0.01s

問題なさそうです。出力にはテスト名だけでなく、どのパターンの組み合わせかも表示してくれています。ちなみにテスト失敗時は以下のようになり、どのケースで失敗したかも分かりやすいです。

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 FAILED  Tests\Unit\ShippingCalculatorTest > it 全ての組み合わせパターンで送料を検証 with ('冷凍', 500) / ('九州', 1000)                                                         
  Failed asserting that '計算不可' is identical to 1500.

データセットの再利用

dataset()でデータセットとテストを分離しておくと、他のテストでも再利用することができます。

例としてもう１つテストを作成します。今度は、定義されていない温度帯の場合は"計算不可"が返るパターンのテストです。

it('存在しない温度帯は計算不可を検証', function (string $temp, string $region) {

    $actual = ShippingCalculator::calculateShippingCost($temp, $region);
    
    expect($actual)->toBe('計算不可');
})
->with(['cool', '　', '存在しない温度帯'])
->with('regionWithCost');

こちらもCombining Datasetsを使用しており、１つめのwith()には失敗パターンの温度帯データを直接記述しています。

そして２つ目のwith()には、すでに定義済みのregionWithCost（配送地域のデータセット）を渡しました。

このように、テストコード内でパターンを重複することなく複数のテストで共有できます。テストを実行してみましょう。

   PASS  Tests\Unit\ShippingCalculatorTest
  ✓ it 存在しない温度帯は計算不可を検証 with ('cool') / ('東京', 500)                                                                                                   0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('cool') / ('大阪', 750)                                                                                                   0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('cool') / ('福岡', 1000)                                                                                                  0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('　') / ('東京', 500)                                                                                                      0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('　') / ('大阪', 750)                                                                                                      0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('　') / ('福岡', 1000)                                                                                                     0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('存在しない温度帯') / ('東京', 500)                                                                                               0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('存在しない温度帯') / ('大阪', 750)                                                                                               0.01s  
  ✓ it 存在しない温度帯は計算不可を検証 with ('存在しない温度帯') / ('福岡', 1000)                                                                                              0.01s

こちらも問題なく全ての組み合わせでテストできました！

datasetをファイルへ切り出す

ここまでは、テストコードとデータセットが１つのファイルに共存している状態でした。Pestではデータセットをtests/Datasetsへ切り出すことで、他のテストファイルからも呼び出せるようになるSharing Datasetsという機能があります。

データセットをファイルに切り出す際、Laravel環境では前回ご紹介したプラグインををインストールしていると以下のコマンドで簡単にファイルを作成できます。もちろん手動で作成しても問題ありません。

$ php artisan pest:dataset shippingCosts

ファイル名はshippingCostsとしました。ここに、先ほどのデータセットを移行します。テストファイルに記述していたdataset()をそのままコピーすればOKです。

/tests/Datasets/ShippingCosts.php

dataset('tempWithCost', [
    ['常温', 0],
    ['冷蔵', 200],
    ['冷凍', 500],
]);

dataset('regionWithCost', [
    ['東京', 500],
    ['大阪', 750],
    ['福岡', 1000],
]);

これで、テストコードとデータセットを完全に分離できました！

最初のテストコードよりはかなりすっきりしたのではないでしょうか。Pestでテストを作成する際は、ぜひ活用してみてください。

テストがちょっとシンプルになる pest-plugin-laravel プラグイン

Thu, 13 Feb 2025 08:36:45 +0900

PestはPHPUnitの上に構築された、テストをよりシンプルに書くためのフレームワークです。そのPestが公式に推奨しているLaravelのためのプラグインpest-plugin-laravelを使って既存のテストを書き直してみました。Pestが掲げる「読みやすく理解しやすい」テストコードに、少し近づけるでしょうか。

Pest導入、基本の記述方法については以下をご参照ください。 PHPUnitテストをpest-plugin-driftでPestへ変換 Pestでモック・例外のテスト

pest-plugin-laravelをインストール・テストファイル作成

Pestはすでにインストールしてあると仮定して、以下のコマンドでプラグインをインストールします。

$ composer require pestphp/pest-plugin-laravel --dev

このプラグインをインストールしたことで、まず、新しいartisanコマンドpest:testが使えるようになっています。ファイル名をPestTestと指定して以下のコマンドを実行します。

$ php artisan pest:test PestTest

tests/Feature/PestTest.phpにテストファイルが作成されます。

tests/Feature/PestTest.php

it('has pest page', function () {
    $response = $this->get('/pest');

    $response->assertStatus(200);
});

デフォルトでは、tests/Featureのディレクトリにファイルが作成されますが、–unitオプションをつけるとtest/Unitにファイルが作成されます。

もちろん、Laravel標準のmake:testコマンドで作成しても問題ありません。

$ php artisan make:test PestTest

pest-plugin-laravelを使った記述方法

プラグインインストールでテストの記述も少し簡単になります。Laravelのテストでよく使うテストヘルパーを$this->を使わず呼び出せるようになります。例えば以下のようなユーザーログアウトのテストの場合

test('users can logout', function () {

    $this->actingAs($this->user)
        ->post('/logout')
        ->assertRedirect('/');

    $this->assertGuest();
});

プラグインの機能を使って書き直すと、こんな風になります。

use function Pest\Laravel\{actingAs, assertGuest}; // インポートする

test('users can logout', function () {

    actingAs($this->user)
        ->post('/logout')
        ->assertRedirect('/');

    assertGuest();
});

actingAsやassertGuestを直接呼び出すことができるようになるため、$this->の記述がなくなってコードが少しすっきりしました。名前空間関数のインポートが必要ですので、useをお忘れなく。

他にも、よく使われるHTTPリクエストの場合

プラグイン導入前

...
    $response = $this->get('/login');
...
    $response = $this->post('/login', [
        'email'    => 'test@example.com',
        'password' => 'password',
    ]);
...

導入後

use function Pest\Laravel\{get, post};

...
    $response = get('/login');
...
    $response = post('/login', [
        'email'    => 'test@example.com',
        'password' => 'password',
    ]);
...

データベースのアサーションは

プラグイン導入前

...
    $this->assertDatabaseHas(User::class, ['email' => 'test@example.com']);
...

導入後

use function Pest\Laravel\assertDatabaseHas;
...
    assertDatabaseHas(User::class, ['email' => 'test@example.com']);
...

他にも色々なコマンドが対応していますので、詳しくはgithubをご覧ください。

プラグインの機能を使って、以前にご紹介したパスワードリセットのテストをPest形式に書き換えたものが以下になります。（書き換え前のPHPUnitのテストコードはリンクからご確認ください）

use function Pest\Laravel\{post, assertGuest, assertAuthenticated};

test('password can be reset with valid token', function () {
    Notification::fake();

    $user = User::factory()->create();

    post('/forgot-password', ['email' => $user->email]);

    Notification::assertSentTo($user, ResetPassword::class, function ($notification) use ($user) {
        $response = post('/reset-password', [
            'token' => $notification->token,
            'email' => $user->email,
            'password' => 'new_password',
            'password_confirmation' => 'new_password',
        ]);

        $response->assertRedirect('login')
            ->assertSessionHas('status', 'パスワードをリセットしました。');

        return true;
    });

    assertGuest();

    post('/login', [
        'email' => $user->email,
        'password' => 'new_password',
    ]);

    assertAuthenticated();
});

post・assertGuest・assertAuthenticatedの箇所が、$this->を省略した形に置き換えられています。「すごく変わった！」という訳ではないものの、やはり元のテストよりは細かい部分が見やすくなっています。テストコードが増えてくるとかなり違いがあるのではないでしょうか。

データセット

もう１つ、このプラグインが提供しているコマンドpest:datasetをご紹介します。

$ php artisan pest:dataset データセット名

このコマンドはtests/Datasets/にデータセット用のファイルを作成してくれます。データセットの機能自体は元からPestにあるものですが、artisanコマンドを使ってより便利に作成できるようになりました。

例として、以下のテストからデータセットを別ファイルに切り出してみます。ログインに失敗するテストと、そのデータセットをwith()で渡しています。

test('users cannot authenticate with invalid credentials', function (string $email, string $password) {
    post('/login', [
        'email'    => $email,
        'password' => $password,
    ])->assertStatus(302);

    assertGuest();
})->with([
    '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
    '間違ったメールアドレス' => ['wrong@example.com', 'password'],
]);

まずはデータセットのファイルを作成します。ファイル名はLoginDataとて、以下のコマンドを実行します。

$ php artisan pest:dataset LoginData

これでtests/Datasetsにファイルが作成されましたので、テストからデータセットの部分をこちらに移行します。

tests/Datasets/LoginData.php

dataset('invalidLoginData', [
    '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
    '間違ったメールアドレス' => ['wrong@example.com', 'password'],
]);

データセット名はinvalidLoginDataとしました。

元のテストコードの方は、with()の引数にデータセット名であるinvalidLoginDataを渡してあげればOKです。

test('users cannot authenticate with invalid credentials', function (string $email, string $password) {
・・・
})->with('invalidLoginData');

まとめ

このプラグインを使っても劇的にテストコードが短くなる訳ではなく、「少し良くなる」というものなので、すでにテストの書き方が確立されている環境にわざわざインストールする必要はなさそうです。が、Laravelの開発コアメンバーが開発しているプラグインなので、新しいプロジェクトでPestのテストを書いてゆくという場合には導入してみるのも面白そうだなと感じました。

Laravel Pestでモック・例外のテスト

Wed, 04 Dec 2024 07:44:19 +0900

前回の記事では、LaravelプロジェクトのPHPUnitテストをプラグインを使ってPestへ自動変換しましたが、今回は自分でPestのテストを作成します。外部APIのモック、基本的なアサーションや例外が投げられたパターンなどのテストです。

テスト対象

以下が今回のテスト対象であるTestClassです。getTranslate()では引数のテキストをAPIを使って翻訳し、結果をJsonレスポンスで返却。処理に失敗した場合は例外をスローするようになっています。

ラップしているTranslationApiは外部APIなので、今回はこちらはモックとします。

class TestClass
{
    public function __construct(
        private readonly TranslationApi $translator //これをモックする
    ) {}

    public function getTranslate(string $content): JsonResponse
    {
        try {
            $translatedContent = $this->translator->translate(
                $content
            );

            return response()->json([
                'status'  => 'success',
                'message' => '操作が成功しました。',
                'data'    => $translatedContent,
            ]);

        } catch (Exception $e) {

            throw new Exception('翻訳に失敗しました: '.$e->getMessage());
        }
    }
}

Pestの構文

Pestの構文は以下のようになっており、テストをグルーピングするdescribe()メソッドと、１つ１つのテストケースを指すtest()もしくはit()メソッドで構成されています。PHPUnitで書かれているクラス宣言は不要です。

describe('グループ名', function () {
   test('テスト１', function () {
       //テスト内容
    });
 
   it('テスト２', function () {
       //テスト内容
    });
});

describe()の使用は任意なので、最小構成のtest()、it()のみで問題ありません。

またtest()とit()のどちらを使うのかという点ですが、テストの動作自体は同じなのでどちらでも大丈夫です。ただit()を使った場合、実行結果の出力で以下のようにテスト名の前にitがつくようになっています。

共通処理

ではテストを書いてゆきます。今回は成功・失敗の２パターンテストを書きますので、共通の処理をbeforeEach()を使ってまとめておきます。beforeEach()は各テストケースの実行前に呼び出される、PHPUnitのsetUp()と同じような役割です。

モック対象であるTranslationApiのモック化と、テスト対象クラスのインスタンス化の２点を以下のように共通処理としました。

beforeEach(function () {
    // モックを作成
    $this->mock = Mockery::mock(TranslationApi::class);

    // テスト対象のクラスをインスタンス化
    $this->service = new testClass($this->mock);
});

モックにはPHPUnitと同様にMockeryを使用します。ここではmock()メソッドで対象クラスをモック化するのみとして、モックの振る舞いは各テスト内でセットします。

testClassクラスのインスタンス化も、PHPUnitと記述は特に変わりません。

なお$this->mockや$this->serviceのプロパティ宣言は、Pestでは不要です。

成功パターンのテスト

「翻訳が成功して期待するレスポンスが返ってきたケース」のテストコードは以下になります。

test('翻訳 成功', function () {
    //準備
    $content = 'こんにちは';
    $expected = 'Hello';

    $this->mock
        ->shouldReceive('translate')
        ->once()
        ->with($content)
        ->andReturn($expected);

    //テスト実行
    $response = $this->testClass->getTranslate($content);

    expect($response->getData(true))
        ->toMatchArray([
            'status'  => 'success',
            'message' => '操作が成功しました。',
            'data'    => 'Hello',
        ]);
});

テストコードは大きく前半の準備部分と、後半の実行・アサーションの部分に分かれています。

まず前半では、モックの振る舞いを定義しています。shouldReceive(’translate’)は、translateメソッドが呼ばれること、once()は、呼ばれるのは１度だけという回数を、with($content)で渡される引数を、そして最後にandReturn()で、戻り値を指定しています。

次に後半の、テスト実行と戻り値のアサーションです。

受け取った$response自体はJsonResponseオブジェクトなので、$response->getData(true)でテストに必要な値だけを取り出しています。getData()はデフォルトでstdClassオブジェクトを返すので、ここでは引数にtrueを渡すことで配列として戻り値を受け取っています。

そして検証にはexpect()というPestのアサーションメソッドを使用します。expect()はそれ単体で使用することはなく、通常他のアサーション関数をチェーンします。今回はtoMatchArray()という配列比較の関数を繋ぎました。

toMatchArray()は上のテストコードのように全ての項目を比較することもできますし、以下のように、一部の項目だけといった部分一致も検証できるのでとても便利です。

    expect($response->getData(true))
        ->toMatchArray([
            'message' => '操作が成功しました。',
            'data'    => 'Hello',
        ]);

    expect($response->getData(true))
        ->toMatchArray([
            'data'    => 'Hello',
        ]);

また以下は配列比較でテストが失敗した場合のスクリーンショットですが、差分をこのようにわかりやすく出力してくれます。

失敗パターンのテスト

では次は、「翻訳が失敗し、例外を返すパターン」のテストコードです。

test('翻訳 失敗で例外が返る', function () {

    $content = 'こんにちは';
    $errorMessage = 'API error occurred';

    $this->mock
        ->shouldReceive('translate')
        ->once()
        ->with($content)
        ->andThrow(new Exception($errorMessage));

    $this->testClass->getTranslate($content);

})->throws(Exception::class, '翻訳に失敗しました: API error occurred');

先ほどの成功のテストとは少し構成が変わりました。

まずは前半のモック定義部分。ここは先ほどとほとんど同じですが、モックの戻り値の指定にandThrow(new Exception($errorMessage))として、例外を投げるように指定しています。

そして検証部分はチェーンで繋いだthrows()メソッドで行います。throws()はPestが提供しているメソッドで、第一引数に期待する例外クラスを、第二引数では例外のメッセージを渡します。

PHPUnitの場合、例外の検証時は以下のようにテストコードの冒頭に置かなければいけません。一方Pestではテスト実行後の最後にアサーションを配置できるので、テスト実行の流れと合っていてとても読みやすいと感じました。

public function test_翻訳失敗_PHPUnitの場合()
{
    $this->expectException(Exception::class);
    $this->expectExceptionMessage('翻訳に失敗しました: API error occurred');
    // ... 以下でテスト実行
}

現在LaravelでPHPUnitを使っていてPestを導入しようかなと考えている方は、よろしければ以下の移行手順もご覧ください。

LaravelのPHPUnitテストをpest-plugin-driftでPestへ変換

Sun, 10 Nov 2024 01:38:41 +0900

Laravel10から公式にテストフレームワークとしておすすめされるようになったPestですが、すでにPHPUnitで作成したテストファイルがたくさんある場合、それらを書き換えての移行は大変です。そこで、Pestが提供している変換用プラグインpestphp/pest-plugin-driftを試してみました。

Pest変換対象のLaravelプロジェクト

今回Pestへ変換するLaravelプロジェクトは以下の環境です。テスト用の小さいプロジェクトなので、テストファイルは9ファイルのみとなっています。

Laravel Framework 11.29.0 PHPUnit 11.4.2 PHP 8.2.24

Pest・Pest変換用プラグインインストール

では早速Pestからインストールします。Pest公式サイトの手順に従って進めます。

まずはPHPunitを削除。

$ composer remove phpunit/phpunit

次に、以下のコマンドでPestをインストール。

$ composer require pestphp/pest --dev --with-all-dependencies

Pestのバージョン3.5がインストールされました。続いてinitを実行します。

$ ./vendor/bin/pest --init

すると以下のファイルが作成されました。すでに存在しているファイルはパスされるので、実質Pest.phpのみが作成された形です。

これでPest本体のインストールは完了です。テストファイルの記述はまだPHPUnitのままですが、この段階でも./vendor/bin/pestが実行できます。

続いて変換用プラグインをインストールしてゆきます。こちらも公式サイトの手順に従って、以下のコマンドを実行します。

$ composer require pestphp/pest-plugin-drift --dev

バージョン3.0.0がインストールされました。最後に、以下のコマンドでPHPUnitからPestへの変換を実行します。

$ ./vendor/bin/pest --drift

既存のテストファイルが全て変換されました。

今回は小さいシンプルなプロジェクトなので各種インストールはとくに問題なく進みましたが、大きなプロジェクトの場合依存関係の問題でインストールがスムーズにいかないこともあると思います。

PHPUnit → Pest変換前後の比較

では、変換されたファイルを前後比較してみます。まず、以下が変換前のPHPUnit仕様のテストです。setUpやdataProviderも使用したよくあるテストコードです。

/tests/Feature/Auth/AuthenticationTest.php

namespace Tests\Feature\Auth;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class AuthenticationTest extends TestCase
{
    use RefreshDatabase;

    protected $user;

    protected function setUp(): void
    {
        parent::setUp();

        // 共通ユーザー作成
        $this->user = User::factory()->create([
            'email'    => 'test@example.com',
            'password' => 'password'
        ]); 
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::showLoginForm
     */
    public function test_login_screen_can_be_rendered(): void
    {
        $response = $this->get('/login');
        $response->assertStatus(200);
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::login
     */
    public function test_users_can_authenticate_with_valid_credentials(): void
    {
        $response = $this->post('/login', [
            'email'    => 'test@example.com',
            'password' => 'password',
        ]);

        $this->assertAuthenticated();
        $this->assertEquals('test@example.com', auth()->user()->email);
        
        $response->assertRedirect(route('dashboard', absolute: false));
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::login
     * @dataProvider invalidLoginDataProvider
     */
    public function test_users_cannot_authenticate_with_invalid_credentials($email, $password): void
    {
        $response = $this->post('/login', [
            'email'    => $email,
            'password' => $password,
        ]);

        $this->assertGuest();
        $response->assertStatus(302);
    }

    public static function invalidLoginDataProvider(): array
    {
        return [
            '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
            '間違ったメールアドレス' => ['wrong@example.com', 'password'],
        ];
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::logout
     */
    public function test_users_can_logout(): void
    {
        $response = $this->actingAs($this->user)->post('/logout');

        $this->assertGuest();
        $response->assertRedirect('/');
    }
}

そして、Pestに変換された後のテストがこちらです。

/tests/Feature/Auth/AuthenticationTest.php

use App\Models\User;

uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);

beforeEach(function () {
    // 共通ユーザー作成
    $this->user = User::factory()->create([
        'email'    => 'test@example.com',
        'password' => 'password'
    ]);
});

test('login screen can be rendered', function () {
    $response = $this->get('/login');
    $response->assertStatus(200);
});

test('users can authenticate with valid credentials', function () {
    $response = $this->post('/login', [
        'email'    => 'test@example.com',
        'password' => 'password',
    ]);

    $this->assertAuthenticated();
    expect(auth()->user()->email)->toEqual('test@example.com');

    $response->assertRedirect(route('dashboard', absolute: false));
});

test('users cannot authenticate with invalid credentials', function ($email, $password) {
    $response = $this->post('/login', [
        'email'    => $email,
        'password' => $password,
    ]);

    $this->assertGuest();
    $response->assertStatus(302);
})->with('invalidLoginDataProvider');

dataset('invalidLoginDataProvider', function () {
    return [
        '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
        '間違ったメールアドレス' => ['wrong@example.com', 'password'],
    ];
});

test('users can logout', function () {
    $response = $this->actingAs($this->user)->post('/logout');

    $this->assertGuest();
    $response->assertRedirect('/');
});

変換後のPest仕様のコードではクラスの定義は削除され、それぞれのテストケースは関数宣言ではなくtest()関数として記述されています。また変換前は85行あったテストコードがPest変換後は57行とかなりコンパクトになりました。Docコメントが全て削除されているのが大きいのかもしれません。

それでは、移行するにあたり気になっていた箇所をピックアップしてみてみます。

dataprovider

PHPUnitのdataProviderは、Pest変換後は以下のようになりました。Docコメントとともに@dataProviderの記述は削除されて、代わりにwith()でデータセットを紐付けしています。テストとデータセットがバラバラなので、見た目にはPHPUnitとあまり変わりがありませんね。

test('users cannot authenticate with invalid credentials', function ($email, $password) {
・・・・・
})->with('invalidLoginDataProvider');

dataset('invalidLoginDataProvider', function () {
    return [
        '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
        '間違ったメールアドレス' => ['wrong@example.com', 'password'],
    ];
});

データセットの紐付けは、以下のようにwith()内に記述される形に変換されることを期待したのですが、そうはなりませんでした。

test('users cannot authenticate with invalid credentials', function ($email, $password) {
    ・・・・・
    })->with([
        ['test@example.com', 'wrong-password'],
        ['wrong@example.com', 'password']
]);

setUp関連

PHPUnitのsetUp()は、以下のようにbeforeEach()に変換されました。beforeEach()とは、それぞれのテストメソッドの実行前に毎回呼び出されるsetUp()と同じように共通の処理を行う際に使用されるメソッドです。

beforeEach(function () {
    // 共通ユーザー作成
    $this->user = User::factory()->create([
        'email'    => 'test@example.com',
        'password' => 'password'
    ]);
});

他にも、PHPUnitで当然のように書いていたparent::setUp()やuse RefreshDatabase;はPestでは書く必要がなく、またprotected $user;といったプロパティ宣言も不要です。Pestの謳い文句の通り、テストコードはだいぶシンプルにできますね。

テスト実行

では変換後のテストを実行してみましょう。

テストはコマンドラインで、

$ ./vendor/bin/pest

あるいは、

$ php artisan test

で実行できます。

以下のようにオプションを渡して実行ファイルを指定することもできます。

$ ./vendor/bin/pest --filter=AuthenticationTest //ファイル名を指定する場合

実行結果は以下のように出力されました。

テストにかかる時間はPestに変換しても速くなるということは特になく、PHPUnitと変わりなかったです。

今回は自動で変換したためPestの記述に関しては要点のみとなりましたが、次回は手動でPestのテストコードを作成してゆきます。

Pest on ララジャパン

Pest4のE2Eテスト - セットアップ〜テストコードの実装例

セットアップ

新規作成フロー・テストコード全体

画面遷移・操作系メソッド

要素の値を取得するメソッド

セレクタの指定について

アサーション系

使用可能なLaravelのメソッド

Playwrightのメソッドを使いたい場合

まとめ

Pestの「dataset」活用で、見通しが良い・修正しやすいテストコードへ

テスト対象

テストコード

Combining Datasetsの活用

データセットの再利用

datasetをファイルへ切り出す

テストがちょっとシンプルになる pest-plugin-laravel プラグイン

pest-plugin-laravelをインストール・テストファイル作成

pest-plugin-laravelを使った記述方法

データセット

まとめ

Laravel Pestでモック・例外のテスト

テスト対象

Pestの構文

共通処理

成功パターンのテスト

失敗パターンのテスト

関連記事

LaravelのPHPUnitテストをpest-plugin-driftでPestへ変換

Pest変換対象のLaravelプロジェクト

Pest・Pest変換用プラグインインストール

PHPUnit → Pest変換前後の比較

dataprovider

setUp関連

テスト実行