laravel-testing

Laravel 13 のテストを Pest 5 / PHPUnit 13（PHP 8.3 では Pest 4 / PHPUnit 12）で行う方法を扱います。フィーチャーテスト（HTTP、フルスタック）、ユニットテスト（分離されたクラス）、アーキテクチャテスト、Pest の構文（it/test/describe）、データセット、HTTP テスト（リクエスト、JSON アサーション、認証/actingAs、ステータス/リダイレクトのアサーション）、データベーステスト（RefreshDatabase、ファクトリ、DB アサーション）、モック（サービス、スパイ、Mail/Queue/Event フェイク、Http::fake、タイムトラベル）、コンソール/Artisan コマンドのテスト、PHPUnit 属性ベースのシーディング（#[Seed]、#[Seeder]）をカバーします。

Laravel テスト

エージェントワークフロー（必須）

いかなる実装の前にも、3 つのエージェントを並列で起動してください。それぞれ name を指定した Agent 呼び出し 1 回です。

1. fuse-ai-pilot:explore-codebase - 既存のテストパターンを分析
2. fuse-ai-pilot:research-expert - Context7 経由で Pest/PHPUnit のドキュメントを確認
3. mcp__context7__query-docs - アサーションとモックのパターンを確認

実装後は、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

種類	目的	場所
フィーチャー	HTTP、フルスタック	tests/Feature/
ユニット	分離されたクラス	tests/Unit/
アーキテクチャ	コードアーキテクチャ	tests/Arch.php

---

判断ガイド: テストの種類

What to test?
├── HTTP endpoint → Feature test
├── Service/Policy logic → Unit test
├── Code structure → Arch test
├── External API → Mock with Http::fake()
├── Mail/Queue/Event → Use Fakes
└── Database state → assertDatabaseHas()

---

判断ガイド: テスト戦略

Coverage strategy?
├── Feature tests (70%) → Critical flows
├── Unit tests (25%) → Business logic
├── E2E tests (5%) → User journeys
└── Arch tests → Structural rules

---

重要なルール

1. RefreshDatabase を使用する - データベースの分離のため
2. ファクトリを使用する - テストデータ用（生の insert は決して使わない）
3. 外部サービスをモックする - 実際の API を決して呼び出さない
4. エッジケースをテストする - 空、null、境界値
5. 並列実行する - 速度のために pest --parallel

---

リファレンスガイド

Pest の基本

トピック	リファレンス	参照すべきとき
Pest の構文	pest-basics.md	it()、test()、describe()
データセット	pest-datasets.md	データプロバイダー、フック
アーキテクチャ	pest-arch.md	arch() テスト

HTTP テスト

トピック	リファレンス	参照すべきとき
リクエスト	http-requests.md	GET、POST、ヘッダー
JSON API	http-json.md	API アサーション
認証	http-auth.md	actingAs、ガード
アサーション	http-assertions.md	ステータス、リダイレクト

データベーステスト

トピック	リファレンス	参照すべきとき
基本	database-basics.md	RefreshDatabase
ファクトリ	database-factories.md	ファクトリのパターン
アサーション	database-assertions.md	DB アサーション

モック

トピック	リファレンス	参照すべきとき
サービス	mocking-services.md	Mock、スパイ
フェイク	mocking-fakes.md	Mail、Queue、Event
HTTP と時間	mocking-http.md	Http::fake、travel

その他

トピック	リファレンス	参照すべきとき
コンソール	console-tests.md	Artisan テスト
トラブルシューティング	troubleshooting.md	よくあるエラー

テンプレート

テンプレート	使用すべきとき
FeatureTest.php.md	HTTP フィーチャーテスト
UnitTest.php.md	サービスのユニットテスト
ArchTest.php.md	アーキテクチャテスト
ApiTest.php.md	REST API テスト
PestConfig.php.md	Pest の設定

---

クイックリファレンス

// Feature test
it('creates a post', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->postJson('/api/posts', ['title' => 'Test'])
        ->assertCreated()
        ->assertJsonPath('data.title', 'Test');

    $this->assertDatabaseHas('posts', ['title' => 'Test']);
});

// With dataset
it('validates emails', function (string $email, bool $valid) {
    // test logic
})->with([
    ['[email protected]', true],
    ['invalid', false],
]);

// Mock facade
Mail::fake();
// ... action ...
Mail::assertSent(OrderShipped::class);

---

コマンド

# Run all tests
php artisan test

# Pest directly
./vendor/bin/pest

# Parallel execution
./vendor/bin/pest --parallel

# Filter by name
./vendor/bin/pest --filter "user can"

# Coverage
./vendor/bin/pest --coverage --min=80

# Profile slow tests
./vendor/bin/pest --profile

---

ベストプラクティス

DO

• RefreshDatabase トレイトを使用する
• AAA パターン（Arrange-Act-Assert）に従う
• 内容が分かるテスト名を付ける
• 1つのテストにつき1つのことをテストする
• データにはファクトリーを使用する

DON'T

• テストの依存関係を作成しない
• 実際の外部 API を呼び出さない
• 本番データベースを使用しない
• エッジケースを省略しない

---

Laravel 13 に関する注意事項

PHPUnit 12/13 + Pest 4/5

Laravel 13 のスケルトンには PHPUnit 12（^12.5）が含まれています。また、フレームワークは PHPUnit 13 にも対応しています。Pest 5（現行版。PHP 8.4+ と PHPUnit 13 が必要で、さらに Laravel ^13.23 が必要な pestphp/pest-plugin-laravel ^5.0 も必要です）を使用するか、アプリで PHP 8.3 を使い続ける場合は Pest 4（PHPUnit 12）を使用してください。PHP 属性が docblock アノテーションに置き換わります。

use PHPUnit\Framework\Attributes\Test;
use Illuminate\Foundation\Testing\Attributes\Seed;
use Illuminate\Foundation\Testing\Attributes\Seeder;

#[Seed]                          // runs DatabaseSeeder
#[Seeder(UserSeeder::class)]     // runs a targeted seeder
final class UserTest extends TestCase
{
    #[Test]
    public function it_creates_user(): void { /* ... */ }
}

Str ファクトリーのリセット

Laravel 13 では、テストのティアダウン時にカスタム Str ファクトリー（UUID／ULID／ランダム文字列）がリセットされます。ファクトリーがメソッド間で維持されることを前提とするテストでは、各テストまたはセットアップフックで設定してください。

#[UnitTest]（L13）

テストメソッドに Illuminate\Foundation\Testing\Attributes\UnitTest を付けると、そのテストではアプリケーションの起動がスキップされます。

Pest 3 から 4 への移行

• pestphp/pest とすべての Pest プラグインを ^4.0 にアップグレードします（PHP 8.3+、PHPUnit 12）
• スナップショット名が変更されました。./vendor/bin/pest --update-snapshots を実行します
• pest-plugin-watch と pest-plugin-faker はアーカイブ済みです

Pest 4 から 5 への移行

• PHP 8.4+ が必要です。pestphp/pest とすべての Pest プラグインを ^5.0 にアップグレードします（PHPUnit 13 ベース）
• 5 での新機能：--tia（テスト影響分析。ローカルのみ）、公式の PHPStan／Rector プラグイン、Agent および Evals プラグイン、時間均衡型シャーディング