laravel-testing

Laravel 13 のテスト — Pest PHP 4 と PHPUnit 12

Pest PHP 4 と PHPUnit 12 の両方に対応しています。 以下のフレームワークの検出を参照してください。

PHPUnit のバージョンに関する注意： Laravel 13 のデフォルトの composer.json には、phpunit/phpunit: ^12.5.12 が含まれています。このスキルのすべてのパターンは、PHPUnit 11、12、13 と互換性があります。

Laravel 13 アプリケーション向けの包括的なテストガイドです。高速で読みやすく、信頼性の高いテストを書くための、6 カテゴリーにわたる 24 のルールが含まれています。Pest PHP 4 と PHPUnit 12（Laravel 13 のデフォルト）の両方に対応しています。

フレームワークの検出

テストコードを書く、またはレビューする前に、プロジェクトで使用しているテストフレームワークを検出してください。

ステップ 1 — composer.json を確認する

# Look for these in require-dev:
# "pestphp/pest" → Pest
# "phpunit/phpunit" (without pest) → PHPUnit

• pestphp/pest が含まれている場合 → Pest の構文を使用します
• phpunit/phpunit のみが含まれている場合 → PHPUnit の構文を使用します
• 両方が含まれている場合 → Pest を優先します（Pest は PHPUnit 上で動作します）

ステップ 2 — tests/Pest.php を確認する

• tests/Pest.php が存在する場合 → Pest が設定されています。Pest の構文を使用します

ステップ 3 — それでも不明な場合は、ユーザーに確認する

「テストフレームワークを検出できませんでした。このプロジェクトでは Pest PHP と PHPUnit のどちらを使用していますか？」

---

構文リファレンス

テストの宣言

	Pest	PHPUnit
テスト関数	test('...', fn() => ...)	public function test_...(): void
読みやすい名前	it('...', fn() => ...)	#[Test] public function it_...()
グループ化	describe('...', fn() => ...)	テストクラス名／ネストしたクラス
トレイトの適用	uses(RefreshDatabase::class)	クラス内で use RefreshDatabase;
各テストの前	beforeEach(fn() => ...)	protected function setUp(): void
各テストの後	afterEach(fn() => ...)	protected function tearDown(): void
パラメーター化	->with([...])	#[DataProvider] 属性
グローバル設定	Pest.php 内の uses(...)->in('Feature')	基底の TestCase クラス

基本的なアサーション（両フレームワークで共通）

assertStatus、assertJson、assertJsonPath、assertDatabaseHas、assertModelExists、actingAs、Mail::fake()、Queue::fake()、Event::fake()、Notification::fake()、Storage::fake() は、Pest と PHPUnit のどちらでも同じように動作します。

---

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• Laravel の機能テストまたはユニットテストを書く
• HTTP エンドポイントと API レスポンスをテストする
• ファクトリーとテストデータを作成する
• 操作後のデータベースの状態をアサートする
• Mail、Queue、Notification、Event ファサードをフェイクする
• 認証が必要なルートと API トークンをテストする
• describe ブロック、データセット、テストクラスを使ってテストを整理する

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	HTTP と機能テスト	重大	http-
2	モデルファクトリー	重大	factory-
3	データベースアサーション	高	db-
4	サービスのフェイク	高	fake-
5	認証テスト	高	auth-
6	テスト整理のパターン	中	pest-

クイックリファレンス

1. HTTP と機能テスト（重大）

• http-test-structure - ファクトリーを使った Arrange/Act/Assert — Pest と PHPUnit の例
• http-assert-response - assertStatus、assertJson、assertRedirect、assertJsonMissing
• http-assert-json-fluent - AssertableJson クロージャーを使った Fluent assertJson
• http-refresh-database - RefreshDatabase と DatabaseTransactions の比較 — それぞれを使う場面

2. モデルファクトリー（重大）

• factory-define - 型付きのフェイクデータと PHP 8.3 の構文を使ったファクトリーの定義
• factory-states - 個別のテストシナリオに対応するファクトリーの状態
• factory-sequences - sequence() を使った複数レコードの異なるデータ
• factory-relationships - has()、for()、recycle()、afterCreating()

3. データベースアサーション（高）

• db-assert-has - 存在確認に使う assertDatabaseHas、assertModelExists
• db-assert-missing - 削除確認に使う assertDatabaseMissing、assertModelMissing
• db-assert-soft-deletes - assertSoftDeleted、trashed() ファクトリーの状態

4. サービスのフェイク（高）

• fake-mail - Mail::fake()、assertSent と assertQueued の比較、assertNothingSent
• fake-queue - Queue::fake()、assertPushed、assertPushedOn
• fake-notification - Notification::fake()、assertSentTo、assertCount
• fake-event - Event::fake()、assertDispatched、assertNotDispatched
• fake-storage - Storage::fake()、UploadedFile::fake()、assertExists
• fake-ai-agent - Agent::fake()、assertPrompted、preventStrayPrompts（Laravel 13+）
• fake-ai-media - Image::fake()、Audio::fake()、Transcription::fake()（Laravel 13+）
• fake-ai-data - Embeddings::fake()、Reranking::fake()、Files::fake()、Stores::fake()（Laravel 13+）

5. 認証テスト（高）

• auth-acting-as - セッション／Web 認証済みテストでの actingAs()
• auth-sanctum - API トークン認証での Sanctum::actingAs()

6. テストの構成パターン（中）

• pest-describe-it - describe()/it()（Pest）またはテストクラスの構成（PHPUnit）
• pest-datasets - with() データセット（Pest）または #[DataProvider]（PHPUnit）
• pest-hooks - beforeEach/afterEach（Pest）または setUp/tearDown（PHPUnit）

基本パターン

Pest

<?php

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

uses(RefreshDatabase::class);

test('authenticated user can create a post', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])
        ->assertStatus(201)
        ->assertJsonPath('data.title', 'Hello World');

    $this->assertDatabaseHas('posts', ['title' => 'Hello World', 'user_id' => $user->id]);
});

PHPUnit

<?php

namespace Tests\Feature;

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

class PostControllerTest extends TestCase
{
    use RefreshDatabase;

    public function test_authenticated_user_can_create_a_post(): void
    {
        $user = User::factory()->create();

        $this->actingAs($user)
            ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])
            ->assertStatus(201)
            ->assertJsonPath('data.title', 'Hello World');

        $this->assertDatabaseHas('posts', ['title' => 'Hello World', 'user_id' => $user->id]);
    }
}

使用方法

詳しい説明とコード例については、各ルールファイルを参照してください。

各ルールファイルには、以下が含まれています。

• メタデータを含む YAML frontmatter（タイトル、影響度、タグ）
• 重要な理由の簡単な説明
• 解説付きの悪い例
• 構文が異なる場合は、Pest と PHPUnit の両方を使った良い例
• Laravel 13 固有のコンテキストと参考情報

コンパイル済みドキュメント全文

すべてのルールを展開した完全なガイドについては、AGENTS.md を参照してください。