shaxzodbek-uzb/laravel-guardrails

Pestテスティング規律

テストされていない、または過剰にモック化された実装詳細をアサートするだけの「テスト済み」機能は、プロダクションで静かに壊れ、リファクタリングのたびに腐敗します。このスキルは、振る舞いを証明し、異常系と認可をカバーし、リファクタリングに耐える、Pest 3/4テストを作成することを強制します。

落とし穴

2つの障害モードがあり、どちらもコストがかかります：

1. テストがない／ハッピーパスのみのテスト。 デモでは機能しますが、プロダクションでゲストがエンドポイントを叩き、テナントが別のテナントのデータを読み取り、バリデーションの抜け穴がゴミデータを許容し、404が500になります。認可の抜け穴（403/404パスがアサートされていない）は、データ漏洩が本番環境にリリースされる原因です。
2. 脆く、過剰にモック化されたテスト。 自分自身のUserRepository/サービスをshouldReceive('save')->once()でモック化すると、実際のクエリが間違っていてもテストは成功し、誰かがメソッド名を変更した瞬間に爆発します。テストスイートはグリーンで誤った自信を与え、次のリファクタリングでイライラから削除され、モード1に逆戻りします。

修正方法はどちらの場合も同じ規律です：自分が所有しない境界をフェイクし、自分が所有するコードを実行し、観測可能な結果（DB行、HTTPステータス、ディスパッチされたジョブ/メール）をアサートする — 失敗と認可の結果も含めて。

ルール

1. テストは機能と一緒に書き、「後で」ではない。 コントローラー/ジョブ/コマンド/ポリシーの変更は、Pestテストが完了するまで不完全です。機能が完了したと報告する前に、その振る舞いをアサートする対応するテストがなければなりません。
2. Pestの慣用句を使用する。 ケースはit('...')またはtest('...')で定義し、アサートは流暢なexpect(...)で行い、セットアップはbeforeEach()で共有します。ファイルが既にそのスタイルを使用している場合を除き、PHPUnitのclass FooTest extends TestCaseは記述しないでください。
3. 適切なタイプを選ぶ。 HTTP/エンドツーエンドの振る舞い → フィーチャーテスト（フレームワークを起動し、$this->get/post/...でルートを叩く）。フレームワーク/DBなしの純粋なロジック → ユニットテスト。迷ったらデフォルトでフィーチャーテストを — より多くの問題を捕捉します。
4. トレイトでデータベースをリセットする（uses()を使用）。 tests/Pest.phpでRefreshDatabase（トランザクションラップ）またはLazilyRefreshDatabase（テストがDBに触れたときのみマイグレート）をFeatureディレクトリ全体に適用するか、ファイルの先頭でuses(RefreshDatabase::class)を適用します。絶対にテストを残存状態に依存させないでください。
5. データはファクトリで構築し、手書きのインサートはしない。 User::factory()->create() / ->make()とリレーションシップファクトリを使用します。テスト内でのDB::table()->insert([...])やnew Model([...])->save()のような手書きのビルドは脆く、キャスト/デフォルトをスキップするため禁止します。
6. データセットで重複を排除し、コピーペーストはしない。 同じアサーションが多くの入力（有効/無効なペイロード、ロールマトリクス）で実行される場合は、N個のほぼ同一のテストの代わりに->with([...])（インラインまたはtests/Datasets/内の名前付きデータセット）を使用します。
7. 自分が所有しない境界をフェイクする。 外部または非同期のものについては、アクションの前にファサードフェイクを使用します：Http::fake()、Queue::fake()、Bus::fake()、Mail::fake()、Notification::fake()、Event::fake()、Storage::fake()。時間については、$this->travel(...)、$this->travelTo(...)、または$this->freezeTime()を使用します — 凍結されていないnow()に対してアサートしないでください。
8. 自分のモデル/サービスを無意味になるまでモック化しない。 テスト対象のコードに対してMockery::mock(MyService::class)->shouldReceive(...)やModel::shouldReceive(...)を避けます。実際のコードをテストDBとフェイクした境界に対して実行させます。自分のクラスをモック化するのは、実際に実行していない真の継ぎ目（例：遅いサードパーティSDKラッパー）でのみにしてください。
9. 結果をアサートし、内部実装はアサートしない。 assertDatabaseHas / assertDatabaseMissing / assertModelExists、assertStatus / assertOk / assertCreated、assertJson / assertJsonPath、assertRedirect、Mail::assertSent、Notification::assertSentTo、Queue::assertPushed、Bus::assertDispatched、Storage::disk()->assertExistsを優先します。振る舞いの代理として「メソッドXが一度呼ばれた」をアサートしないでください。
10. 常に異常系と認可をテストする。 すべてのエンドポイント/アクションには、最低限、ハッピーパス、バリデーション/失敗パス、そして認可パス — ゲスト → 401/リダイレクト、間違ったユーザー/ロール → 403、存在しない/外部リソース → 404が必要です。セキュリティに敏感な機能には、「別のユーザーがこれにアクセス/変更できない」というテストを明示的に追加します。これは、所有権やテナンシーに関わるものでは交渉の余地がありません。
11. アーキテクチャテストを安価なグローバルガードレールとして追加する。 適切なプリセットを含むtests/Arch.php（またはPest.php内のアーキテクチャケース）を維持します：arch()->preset()->php()（die/var_dump/ddスタイルのデバッグ出力と非推奨のPHP関数を禁止）、arch()->preset()->security()（eval、extract、unserialize、弱いハッシュ/md5/sha1、安全でないランダム性などを禁止）、arch()->preset()->laravel()（Laravelの規約を強制 — 設定外でのenv()も禁止）。arch('controllers')->expect('App\Http\Controllers')->toExtend('App\Http\Controllers\Controller')のようなプロジェクト不変条件を追加します。
12. テストごとに1つの振る舞い、説明的な名前。 it('blocks guests from the dashboard')と記述し、it('works')とは記述しません。テスト名に「and」が必要なら、分割します。
13. CIでカバレッジをゲートする。 ./vendor/bin/pest --coverage --min=NNを実行して最小値を強制し、./vendor/bin/pest --type-coverage（タイプカバレッジプラグインが必要）を実行して型シグネチャを強制します。新しいテストのない行を欠陥として扱います。
14. ブラウザ/E2Eは控えめに（Pest 4）。 Pest 4はvisit('/')->...->assertSee(...)（Playwrightベース）を介してブラウザテストを提供します。真のフルスタック/JSフローのために予約し、HTTP層のアサーションを遅いブラウザテストとして再実装しないでください。

良い例と悪い例

// tests/Feature/UpdatePostTest.php

use App\Models\Post;
use App\Models\User;

// ❌ 過剰モック：何が起こったかではなく、メソッドが呼ばれたことをテスト。
//    間違った投稿が更新されたり、認証が欠落していても成功する。
it('updates a post', function () {
    $service = Mockery::mock(App\Services\PostService::class);
    $service->shouldReceive('update')->once()->andReturnTrue();
    $this->app->instance(App\Services\PostService::class, $service);

    $this->put('/posts/1', ['title' => 'New'])->assertOk();
});

// ✅ 実際のコードをテストDBに対して実行し、結果と認可をアサート。
use App\Models\Post;
use App\Models\User;

it('lets the owner update their post', function () {
    $owner = User::factory()->create();
    $post  = Post::factory()->for($owner)->create(['title' => 'Old']);

    $this->actingAs($owner)
        ->put("/posts/{$post->id}", ['title' => 'New'])
        ->assertRedirect();

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

it('forbids a non-owner from updating the post', function () {
    $post     = Post::factory()->create(['title' => 'Old']);
    $attacker = User::factory()->create();

    $this->actingAs($attacker)
        ->put("/posts/{$post->id}", ['title' => 'Hacked'])
        ->assertForbidden(); // 403

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

it('blocks guests', function () {
    $post = Post::factory()->create();

    $this->put("/posts/{$post->id}", ['title' => 'New'])
        ->assertRedirect('/login'); // またはAPIの場合はassertUnauthorized()
});

// ❌ 実際のネットワークを叩く（不安定、遅い、キー漏洩の可能性あり）; 有用なものは何もアサートしない。
it('notifies slack', function () {
    $resp = (new App\Services\Slack)->ping('deploy ok');
    expect($resp)->toBeArray();
});

// ✅ 自分が所有しない境界をフェイクし、送信したリクエストをアサート。
use Illuminate\Support\Facades\Http;

it('posts the deploy message to slack', function () {
    Http::fake(['hooks.slack.com/*' => Http::response(['ok' => true])]);

    (new App\Services\Slack)->ping('deploy ok');

    Http::assertSent(fn ($request) =>
        $request->url() === 'https://hooks.slack.com/services/T/B/x'
        && $request['text'] === 'deploy ok'
    );
});

// ❌ コピーペーストされたほぼ同一のバリデーションテスト。
it('rejects empty email', function () {
    $this->post('/register', ['email' => ''])->assertSessionHasErrors('email');
});
it('rejects bad email', function () {
    $this->post('/register', ['email' => 'nope'])->assertSessionHasErrors('email');
});

// ✅ 1つのテスト、データセットによるテーブル駆動。
it('rejects invalid emails', function (string $email) {
    $this->post('/register', ['email' => $email])
        ->assertSessionHasErrors('email');
})->with([
    'empty'       => '',
    'no at-sign'  => 'nope',
    'no domain'   => 'a@',
]);

// ✅ 非同期+時間境界をフェイク; ディスパッチと副作用をアサート。
use App\Jobs\SendReminder;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Queue;

it('queues a reminder and welcomes the user on signup', function () {
    Queue::fake();
    Mail::fake();
    $this->freezeTime();

    $this->post('/register', [
        'name' => 'Ada', 'email' => '[email protected]', 'password' => 'secret-pass',
    ])->assertRedirect();

    Queue::assertPushed(SendReminder::class);
    Mail::assertSent(WelcomeMail::class, fn ($m) => $m->hasTo('[email protected]'));
    $this->assertDatabaseHas('users', ['email' => '[email protected]']);
});

// tests/Arch.php — ✅ 安価なグローバルガードレール
arch()->preset()->php();        // die/var_dump/ddスタイルのデバッグ出力と非推奨PHP関数を禁止
arch()->preset()->security();   // eval、extract、unserialize、md5/sha1、弱いランダム性などを禁止
arch()->preset()->laravel();    // Laravelの規約を強制（設定外でのenv()も禁止）

arch('controllers extend the base controller')
    ->expect('App\Http\Controllers')
    ->toExtend('App\Http\Controllers\Controller');

arch('models live in the right namespace')
    ->expect('App\Models')
    ->toExtend('Illuminate\Database\Eloquent\Model');

確認方法

機能とそのテストが完了したと主張する前に、以下を実行してください：

# 1. スイート全体がグリーンであること。
./vendor/bin/pest

# 2. イテレーション中は新しい/変更されたファイルだけを実行。
./vendor/bin/pest tests/Feature/UpdatePostTest.php

# 3. カバレッジの下限を強制（XdebugまたはPCOVが必要）。
./vendor/bin/pest --coverage --min=80

# 4. タイプカバレッジ（pestphp/pest-plugin-type-coverageが必要）。
./vendor/bin/pest --type-coverage --min=100

# 5. スタイルがきれいであること。
./vendor/bin/pint --test

次に、落とし穴を再導入していないかを監査します：

# 認可カバレッジ：保護された各フィーチャーテストは401/403/404パスをアサートするべき。
grep -rEn "assertForbidden|assertUnauthorized|assertNotFound|->assertStatus\\((401|403|404)\\)" tests/

# 過剰モックの匂い：自分のAPPクラスをモック化するのは危険信号 — 各ヒットを確認。
grep -rEn "Mockery::|->shouldReceive\(|::partialMock\(|::spy\\(" tests/

# ファクトリの代わりに手書きのインサート — ->factory()に置き換え。
grep -rEn "DB::table\(.*\)->insert|new App\\\\Models" tests/

# 外部境界はフェイクされなければならない — コードが外部を呼び出す場所にフェイクが存在することを確認。
grep -rEn "Http::fake|Queue::fake|Bus::fake|Mail::fake|Notification::fake|Storage::fake|Event::fake" tests/

# セキュリティ+PHPアーキプリセット（安価なグローバルガードレール）がどこかに存在すること。
grep -rEn "preset\(\)->(security|php|laravel)\(\)" tests/

コードだけでなくテストでアサート：新しいエンドポイントごとに、(a) ハッピーパスの結果アサーション（assertDatabaseHas/assertOk/assertJsonPath）、(b) 少なくとも1つの失敗/バリデーションアサーション、(c) ゲスト+間違ったユーザーの認可アサーションが存在することを確認します。いずれかが欠けている場合、その機能は完了していません。

ルールを曲げてもよい場合

• 真の外部の継ぎ目での自分のコードのモック化。 HTTP層でフェイクできない有料サードパーティSDK（SMS、支払いゲートウェイ）の薄いラッパーは、正当なMockeryターゲットです — テスト対象の振る舞いをフェイクするのではなく、それらの依存関係を隔離しています。
• DBなしでの純粋なロジックのユニットテスト。 値オブジェクト、フォーマッター、計算機はRefreshDatabaseもファクトリも必要としません — 直接インスタンス化してexpect()で結果をアサートします。それがより速くて正しいです。
• テストが永続化しない場合のcreate()の代わりのmake() — User::factory()->make()は純粋ロジックのアサーションのためにDB書き込みを回避します。
• レガシーコードでの低いカバレッジ閾値。 現実的な--minを設定し、すべての作業をブロックするのではなく、時間をかけて段階的に引き上げます。「100%かゼロか」がテストのリリースをゼロにする口実になってはいけません。
• 純粋にJS駆動のフロー（Livewire/Inertia/Vueのインタラクション、ファイルピッカー）のブラウザテスト — そこでは、visit()はやり過ぎではなく、適切なツールです。

参考文献

• Pest — テストの書き方、期待値、フック: https://pestphp.com/docs/writing-tests
• Pest — データセット: https://pestphp.com/docs/datasets
• Pest — アーキテクチャテストとプリセット（security、laravel、toExtend）: https://pestphp.com/docs/arch-testing
• Pest — カバレッジと--min: https://pestphp.com/docs/coverage
• Pest — タイプカバレッジプラグイン: https://pestphp.com/docs/type-coverage
• Pest v4 — ブラウザテスト（visit()、ビジュアルリグレッション）: https://pestphp.com/docs/browser-testing
• Laravel — HTTPテスト（ステータス/JSON/リダイレクトアサーション）: https://laravel.com/docs/testing
• Laravel — データベーステスト（RefreshDatabase、ファクトリ、assertDatabaseHas）: https://laravel.com/docs/database-testing
• Laravel — モッキングとファサードフェイク（Http、Queue、Bus、Mail、Notification、Event、Storage、時間）: https://laravel.com/docs/mocking