Laravel Guardrails (안전 난간)

Pest 테스트 규율

테스트되지 않은 기능, 혹은 과도하게 모킹(mocking)되어 구현 세부 사항을 단언(assert)하는 테스트 스위트는 프로덕션에서 조용히 망가지고 모든 리팩토링 때마다 썩어갑니다. 이 스킬은 행동을 증명하고, 실패 경로(unhappy path)와 권한 부여(authorization)를 다루며, 리팩토링에도 살아남는 Pest 3/4 테스트를 작성하도록 합니다.

함정 (The footgun)

두 가지 실패 모드가 있으며, 둘 다 비용이 많이 듭니다:

1. 테스트 없음 / 해피 패스(happy-path) 전용 테스트. 데모에서는 기능이 작동하지만, 프로덕션에서 게스트가 엔드포인트에 접근하거나, 테넌트가 다른 테넌트의 데이터를 읽거나, 검증 공백으로 쓰레기 데이터가 들어가거나, 404가 500이 됩니다. 권한 부여 구멍(403/404 경로가 단언되지 않음)은 데이터 누출이 프로덕션으로 배송되는 방식입니다.
2. 취약하고 과도하게 모킹된 테스트. 자체 UserRepository/서비스를 shouldReceive('save')->once()로 모킹하면 실제 쿼리가 잘못되어도 테스트는 통과하고, 누군가 메서드 이름을 바꾸는 즉시 폭발합니다. 스위트는 녹색이고 거짓된 자신감을 주며, 다음 리팩토링에서 좌절감에 삭제됩니다 — 다시 모드 1로 돌아갑니다.

어느 쪽이든 해결책은 동일한 규율입니다: 소유하지 않은 경계는 가짜로(fake) 만들고, 소유한 코드는 실제로 실행하며, 관찰 가능한 결과(DB 행, HTTP 상태, 디스패치된 작업/메일)를 단언하세요 — 실패 및 권한 부여 결과를 포함하여.

규칙 (Rules)

1. 기능과 함께 테스트를 작성하고, "나중에" 하지 마세요. 컨트롤러/작업/명령/정책 변경은 Pest 테스트가 있을 때까지 완료되지 않은 것입니다. 기능에 해당 동작을 단언하는 테스트 없이 완료되었다고 보고하지 마세요.
2. Pest 관용구를 사용하세요. 케이스를 it('...') 또는 test('...')로 정의하고, expect(...)로 유창하게 단언하며, beforeEach()로 설정을 공유하세요. 파일이 이미 PHPUnit 스타일이 아니라면 class FooTest extends TestCase를 작성하지 마세요.
3. 올바른 유형을 선택하세요. HTTP/엔드 투 엔드 동작 → 기능 테스트(Feature test, 프레임워크를 부팅하고 $this->get/post/...로 라우트를 호출). 프레임워크/DB가 없는 순수 로직 → 단위 테스트(Unit test). 의심스러우면 기본값으로 기능 테스트를 사용하세요 — 더 많은 것을 잡아냅니다.
4. 트레이트(trait)와 uses()로 데이터베이스를 리셋하세요. 전체 Feature 디렉토리에 대해 tests/Pest.php에서 RefreshDatabase(트랜잭션 래핑) 또는 LazilyRefreshDatabase(테스트가 DB에 닿을 때만 마이그레이션)를 적용하거나, 파일 상단에 uses(RefreshDatabase::class)를 사용하세요. 절대 DB 테스트를 잔여 상태( leftover state)에 의존하게 두지 마세요.
5. 데이터를 팩토리(factory)로 구축하고, 수동 삽입은 절대 사용하지 마세요. User::factory()->create() / ->make() 및 관계 팩토리를 사용하세요. 테스트에서 수동으로 DB::table()->insert([...]) 또는 new Model([...])->save()를 사용하는 것은 취약하고 캐스트/기본값을 건너뜁니다 — 금지합니다.
6. 데이터셋(datasets)으로 중복 제거하고, 복사-붙여넣기하지 마세요. 동일한 단언이 많은 입력(유효/무효 페이로드, 역할 매트릭스)에 대해 실행될 때는 N개의 거의 동일한 테스트 대신 ->with([...])(인라인 또는 tests/Datasets/의 명명된 데이터셋)을 사용하세요.
7. 소유하지 않은 경계는 가짜로 만드세요(fake). 외부 또는 비동기적인 것에 대해, 작업 전에 파사드 페이크를 사용하세요: Http::fake(), Queue::fake(), Bus::fake(), Mail::fake(), Notification::fake(), Event::fake(), Storage::fake(). 시간(time)에 대해서는 $this->travel(...), $this->travelTo(...), 또는 $this->freezeTime()을 사용하세요 — 절대 고정되지 않은 now()를 단언하지 마세요.
8. 자체 모델/서비스를 무의미하게 모킹하지 마세요. 테스트 대상 코드에 대해 Mockery::mock(MyService::class)->shouldReceive(...) 및 Model::shouldReceive(...)를 피하세요. 실제 코드가 테스트 DB와 가짜 경계에 대해 실행되도록 두세요. 자체 클래스를 모킹하는 것은 실제로 실행하지 않는 진정한 접합점(예: 느린 타사 SDK 래퍼)에서만 가능합니다.
9. 결과(outcome)를 단언하고, 내부(internals)를 단언하지 마세요. assertDatabaseHas / assertDatabaseMissing / assertModelExists, assertStatus / assertOk / assertCreated, assertJson / assertJsonPath, assertRedirect, Mail::assertSent, Notification::assertSentTo, Queue::assertPushed, Bus::assertDispatched, Storage::disk()->assertExists를 선호하세요. 행동의 대리자로서 "메서드 X가 한 번 호출되었다"를 단언하지 마세요.
10. 항상 실패 경로(unhappy path)와 권한 부여(authorization)를 테스트하세요. 모든 엔드포인트/작업에는 최소한 다음이 필요합니다: 해피 패스, 검증/실패 경로, 및 인증 경로 — 게스트 → 401/리다이렉트, 잘못된 사용자/역할 → 403, 누락된/외부 리소스 → 404. 보안에 민감한 기능에는 명시적인 "다른 사용자가 이에 접근/수정할 수 없음" 테스트를 추가하세요. 이는 소유권 또는 테넌시와 관련된 모든 것에 대해 양보할 수 없습니다.
11. 저렴한 전역 안전 난간으로 아키텍처 테스트를 추가하세요. tests/Arch.php(또는 Pest.php의 arch 케이스)에 적합한 프리셋을 유지하세요: 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')와 같은 프로젝트 불변 조건(invariants)을 추가하세요.
12. 테스트당 하나의 동작, 설명적인 이름. it('blocks guests from the dashboard'), 절대 it('works')가 아닙니다. 테스트 이름에 "and"가 필요하면 분할하세요.
13. CI에서 게이트 커버리지(gate coverage). ./vendor/bin/pest --coverage --min=NN을 실행하여 최소값을 강제하고, ./vendor/bin/pest --type-coverage (type-coverage 플러그인 필요)를 실행하여 타입 시그니처를 강제하세요. 새로운 테스트되지 않은 줄은 결함으로 처리하세요.
14. 브라우저/E2E는 드물게 사용하세요 (Pest 4). Pest 4는 브라우저 테스트를 visit('/')->...->assertSee(...) (Playwright 기반)로 제공합니다. 진정한 풀스택/JS 흐름을 위해 예약하세요; HTTP 레이어 단언을 느린 브라우저 테스트로 다시 구현하지 마세요.

좋은 예 vs 나쁜 예

// 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');
});

// ✅ 하나의 테스트, 데이터셋을 사용한 테이블 기반.
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');

확인 방법 (How to verify)

기능과 테스트가 완료되었다고 주장하기 전에 다음을 실행하세요:

# 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

그런 다음 함정을 다시 도입하지 않았는지 감사하세요:

# Authz 커버리지: 각 보호된 기능 테스트는 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) 최소 하나의 실패/검증 단언, (c) 게스트 + 잘못된 사용자 권한 부여 단언이 있는지 확인하세요. 하나라도 빠지면 기능이 완료된 것이 아닙니다.

규칙을 예외적으로 적용할 수 있는 경우 (When it's OK to bend the rule)

• 진정한 외부 접합점에서 자체 코드 모킹. HTTP 계층에서 가짜로 만들 수 없는 유료 타사 SDK(SMS, 결제 게이트웨이)를 감싼 얇은 래퍼는 합법적인 Mockery 대상입니다 — 테스트 대상 동작을 가짜로 만드는 것이 아니라 그들의 의존성을 격리하는 것입니다.
• DB 없이 순수 로직 단위 테스트. 값 객체, 포맷터, 계산기는 RefreshDatabase와 팩토리가 필요 없습니다 — 직접 인스턴스화하고 expect() 결과를 사용하세요; 더 빠르고 정확합니다.
• 테스트가 지속되지 않을 때 create() 대신 make() — User::factory()->make()는 순수 로직 단언을 위해 DB 쓰기를 피합니다.
• 레거시 코드에 대한 낮은 커버리지 임계값. 현실적인 --min을 설정하고 시간이 지남에 따라 점차 높여 작업을 차단하지 마세요; "100% 아니면 안 된다"가 테스트를 전혀 배송하지 않는 핑계가 되어서는 안 됩니다.
• 진정한 JS 기반 흐름( Livewire/Inertia/Vue 상호작용, 파일 선택기)에 대한 브라우저 테스트 — 여기서는 visit()이 올바른 도구이며, 과도한 사용이 아닙니다.

참고 자료 (References)

• Pest — Writing Tests, expectations, hooks: https://pestphp.com/docs/writing-tests
• Pest — Datasets: https://pestphp.com/docs/datasets
• Pest — Architecture Testing & presets (security, laravel, toExtend): https://pestphp.com/docs/arch-testing
• Pest — Coverage & --min: https://pestphp.com/docs/coverage
• Pest — Type Coverage plugin: https://pestphp.com/docs/type-coverage
• Pest v4 — Browser Testing (visit(), visual regression): https://pestphp.com/docs/browser-testing
• Laravel — HTTP Tests (status/JSON/redirect assertions): https://laravel.com/docs/testing
• Laravel — Database Testing (RefreshDatabase, factories, assertDatabaseHas): https://laravel.com/docs/database-testing
• Laravel — Mocking & facade fakes (Http, Queue, Bus, Mail, Notification, Event, Storage, time): https://laravel.com/docs/mocking