테스트: 시작하기

업데이트됨

번역일: 2026년 7월 28일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 7월 28일
번역 갱신: 2026년 7월 28일

테스트: 시작하기

소개
환경 설정
테스트 생성
테스트 실행
설정 캐싱

소개

Laravel은 처음부터 테스트를 고려하여 설계되었습니다. Pest와 PHPUnit을 위한 지원이 기본 내장되어 있으며, phpunit.xml 파일도 이미 프로젝트에 포함되어 있습니다. 또한 프레임워크는 애플리케이션을 직관적으로 테스트할 수 있는 다양한 헬퍼 메서드를 제공합니다.

기본적으로 tests 디렉터리는 Feature와 Unit 두 개의 하위 디렉터리로 구성됩니다.

Unit 테스트: 코드의 아주 작은 단위(주로 메서드 하나)를 독립적으로 검증합니다. Unit 디렉터리의 테스트는 Laravel 애플리케이션을 부팅하지 않으므로 데이터베이스나 프레임워크 서비스에 접근할 수 없습니다.
Feature 테스트: 여러 객체의 상호작용이나 JSON 엔드포인트에 대한 HTTP 요청처럼 더 넓은 범위의 동작을 검증합니다. 대부분의 테스트는 Feature 테스트로 작성하는 것을 권장합니다. 시스템 전체가 의도한 대로 동작하는지 가장 높은 신뢰도로 확인할 수 있기 때문입니다.

Feature와 Unit 디렉터리에는 각각 ExampleTest.php 예제 파일이 포함되어 있습니다. 새 Laravel 프로젝트를 설치한 후 vendor/bin/pest, vendor/bin/phpunit, 또는 php artisan test 명령 중 하나를 실행하여 테스트를 바로 돌려볼 수 있습니다.

환경 설정

테스트 실행 시 Laravel은 phpunit.xml에 정의된 환경 변수를 바탕으로 설정 환경을 자동으로 testing으로 전환합니다. 또한 세션과 캐시 드라이버를 array로 자동 설정하여 테스트 중 세션·캐시 데이터가 실제로 저장되지 않도록 합니다.

추가적인 테스트 환경 설정이 필요하다면 phpunit.xml 파일에서 자유롭게 정의할 수 있습니다. 단, 설정 캐시가 남아 있으면 변경 사항이 반영되지 않을 수 있으므로 테스트 실행 전에 반드시 config:clear Artisan 명령을 실행하세요.

php artisan config:clear

`.env.testing` 파일

프로젝트 루트에 .env.testing 파일을 만들 수도 있습니다. Pest·PHPUnit 테스트를 실행하거나 --env=testing 옵션으로 Artisan 명령을 실행할 때 기존 .env 파일 대신 이 파일이 사용됩니다. 테스트 전용 데이터베이스 접속 정보나 외부 서비스 키를 분리 관리할 때 유용합니다.

테스트 생성

새 테스트 케이스는 make:test Artisan 명령으로 생성합니다. 기본적으로 tests/Feature 디렉터리에 파일이 만들어집니다.

php artisan make:test UserTest

tests/Unit 디렉터리에 생성하려면 --unit 옵션을 추가하세요.

php artisan make:test UserTest --unit

Laravel 테스트 기능을 주로 사용하는 테스트 클래스에서 특정 메서드만 프레임워크 부팅 없이 실행하고 싶다면, 해당 메서드에 #[UnitTest] 어트리뷰트를 붙이면 됩니다. 그 메서드는 애플리케이션을 부팅하지 않고 실행됩니다.

PHPUnit

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\Attributes\UnitTest;
use Tests\TestCase;

class LocationServiceTest extends TestCase
{
    public function test_get_coordinates_resolves_address(): void
    {
        // 이 테스트는 Laravel의 테스트 기능을 사용합니다...
    }

    #[UnitTest]
    public function test_get_state_returns_state_from_abbreviation(): void
    {
        // 이 테스트는 애플리케이션 부팅 없이 실행됩니다...
    }
}

NOTE

테스트 스텁은 스텁 퍼블리싱을 통해 커스터마이징할 수 있습니다.

테스트 파일이 생성되면 Pest 또는 PHPUnit 방식으로 테스트를 작성하고, vendor/bin/pest, vendor/bin/phpunit, 또는 php artisan test 명령으로 실행합니다.

Pest

<?php

test('기본 테스트', function () {
    expect(true)->toBeTrue();
});

PHPUnit

<?php

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    /**
     * 기본 테스트 예제
     */
    public function test_basic_test(): void
    {
        $this->assertTrue(true);
    }
}

WARNING

테스트 클래스에서 setUp / tearDown 메서드를 직접 정의할 경우, 반드시 부모 클래스의 parent::setUp() / parent::tearDown()을 호출해야 합니다. parent::setUp()은 setUp 메서드의 맨 처음에, parent::tearDown()은 tearDown 메서드의 맨 끝에 호출하는 것이 일반적입니다.

테스트 실행

테스트를 작성했다면 pest 또는 phpunit 명령으로 실행할 수 있습니다.

Pest

./vendor/bin/pest

PHPUnit

./vendor/bin/phpunit

Artisan의 test 명령을 사용하면 개발과 디버깅에 편리한 상세 리포트를 확인할 수 있습니다.

php artisan test

pest 또는 phpunit에 전달할 수 있는 인자는 php artisan test에도 동일하게 전달할 수 있습니다.

php artisan test --testsuite=Feature --stop-on-failure

병렬 테스트 실행

기본적으로 Laravel과 Pest / PHPUnit은 단일 프로세스에서 테스트를 순차적으로 실행합니다. 하지만 여러 프로세스를 동시에 활용하면 전체 테스트 실행 시간을 크게 단축할 수 있습니다. 먼저 brianium/paratest 패키지를 개발 의존성으로 설치하고, --parallel 옵션을 붙여 실행하세요.

composer require brianium/paratest --devphp artisan test --parallel

기본적으로 현재 머신의 CPU 코어 수만큼 프로세스가 생성됩니다. --processes 옵션으로 직접 조정할 수도 있습니다.

php artisan test --parallel --processes=4

WARNING

병렬 실행 시 --do-not-cache-result와 같은 일부 Pest / PHPUnit 옵션은 사용할 수 없을 수 있습니다.

병렬 테스트와 데이터베이스

기본 데이터베이스 연결이 설정되어 있다면, Laravel은 각 병렬 프로세스마다 테스트 데이터베이스를 자동으로 생성하고 마이그레이션을 적용합니다. 각 데이터베이스 이름 끝에는 프로세스별로 고유한 토큰이 붙습니다. 예를 들어 병렬 프로세스가 2개라면 your_db_test_1과 your_db_test_2 데이터베이스가 만들어집니다.

테스트 데이터베이스는 기본적으로 다음 test 명령 실행 시에도 재사용됩니다. 새로 만들어야 할 경우 --recreate-databases 옵션을 사용하세요.

php artisan test --parallel --recreate-databases

병렬 테스트 훅

여러 테스트 프로세스에서 안전하게 공유할 리소스를 사전에 준비해야 할 때는 ParallelTesting 파사드를 사용합니다. 프로세스나 테스트 케이스의 setUp / tearDown 시점에 실행할 클로저를 등록할 수 있으며, 클로저는 프로세스 토큰($token)과 현재 테스트 케이스($testCase)를 인자로 받습니다.

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\ParallelTesting;
use Illuminate\Support\ServiceProvider;
use PHPUnit\Framework\TestCase;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 애플리케이션 서비스를 부트스트랩합니다.
     */
    public function boot(): void
    {
        ParallelTesting::setUpProcess(function (int $token) {
            // 프로세스 시작 시 실행...
        });

        ParallelTesting::setUpTestCase(function (int $token, TestCase $testCase) {
            // 테스트 케이스 시작 시 실행...
        });

        // 테스트 데이터베이스 생성 시 실행...
        ParallelTesting::setUpTestDatabase(function (string $database, int $token) {
            Artisan::call('db:seed');
        });

        ParallelTesting::tearDownTestCase(function (int $token, TestCase $testCase) {
            // 테스트 케이스 종료 시 실행...
        });

        ParallelTesting::tearDownProcess(function (int $token) {
            // 프로세스 종료 시 실행...
        });
    }
}

병렬 테스트 토큰 접근

테스트 코드의 어느 위치에서든 현재 병렬 프로세스의 토큰이 필요하다면 token 메서드를 사용하세요. 이 토큰은 각 테스트 프로세스를 식별하는 고유한 문자열로, 프로세스 간 리소스를 구분하는 데 활용할 수 있습니다. Laravel도 내부적으로 이 토큰을 이용해 테스트 데이터베이스 이름을 구분합니다.

$token = ParallelTesting::token();

테스트 커버리지 리포트

WARNING

이 기능을 사용하려면 Xdebug 또는 PCOV가 설치되어 있어야 합니다.

테스트가 실제 애플리케이션 코드를 얼마나 커버하는지 확인하려면 --coverage 옵션을 사용하세요.

php artisan test --coverage

최소 커버리지 기준 설정

--min 옵션으로 최소 커버리지 비율을 지정할 수 있습니다. 이 기준에 미치지 못하면 테스트 스위트가 실패로 처리됩니다.

php artisan test --coverage --min=80.3

테스트 프로파일링

Artisan 테스트 러너는 가장 느린 테스트 목록을 출력하는 기능도 제공합니다. --profile 옵션을 사용하면 실행 시간이 긴 상위 10개 테스트가 표시되어, 어떤 테스트를 개선해야 전체 실행 속도를 높일 수 있는지 쉽게 파악할 수 있습니다.

php artisan test --profile

설정 캐싱

Laravel은 테스트 메서드마다 애플리케이션을 새로 부팅합니다. 설정 캐시 파일이 없으면 테스트마다 모든 설정 파일을 다시 읽어야 하므로 전체 실행 시간이 늘어날 수 있습니다. 한 번의 테스트 실행 동안 설정을 캐싱하여 재사용하려면 WithCachedConfig 트레이트를 사용하세요.

Pest

<?php

use Illuminate\Foundation\Testing\WithCachedConfig;

pest()->use(WithCachedConfig::class);

// ...

PHPUnit

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\WithCachedConfig;
use Tests\TestCase;

class ConfigTest extends TestCase
{
    use WithCachedConfig;

    // ...
}