☕ 들어가며 : 테스트는 왜 항상 "나중에"가 되는가

친구야, 솔직하게 얘기해보자.
우리 PHP 개발자들은 브라우저 새로고침이 곧 테스트였던 시절을 다들 한 번씩 겪었잖아.

var_dump() 찍고, die() 박고, 화면에 배열 뿌려보고,
"오케이 나왔다!" 하고 커밋. 그리고 배포. 그리고… 장애.

사실 이건 개발자가 게을러서가 아니야.
PHP는 태생이 "요청 하나 받아서 HTML 뱉고 죽는" 언어라서,
한 번 실행하고 끝나는 구조가 너무 자연스러웠거든.
프로세스가 살아있질 않으니 "테스트를 따로 돌린다"는 개념 자체가 낯설었지.

그런데 지금은 상황이 완전히 달라졌어.
Composer, PSR 표준, Laravel·Symfony 같은 프레임워크,
그리고 PHPUnit이라는 사실상의 표준 테스트 프레임워크까지.
PHP 생태계는 이제 테스트 안 짜면 오히려 이상한 동네가 됐어.

이 글에서는 PHPUnit의 기본기부터,
테스트 주도 개발(TDD)의 Red-Green-Refactor 사이클,
그리고 실무에서 진짜 써먹는 모킹·데이터 프로바이더·커버리지까지
친구랑 카페에서 수다 떨듯 쭉 훑어볼게.

🧭 1. PHPUnit이란 무엇인가

xUnit 가문의 PHP 장남

PHPUnit은 Sebastian Bergmann이 2004년경부터 만들어온 PHP용 단위 테스트 프레임워크야.
뿌리는 Kent Beck의 SUnit / JUnit 계열, 즉 xUnit 아키텍처를 따르고 있어.

그래서 Java의 JUnit이나 Python의 unittest를 써본 사람이라면
setUp(), tearDown(), assertEquals() 같은 이름이 익숙할 거야.
용어가 거의 공용어처럼 통일돼 있거든.

버전 이야기 (중요!)

PHPUnit은 PHP 버전에 강하게 묶여 있어.
대략적인 지원 관계는 이런 식이야.

설치는 Composer 한 줄

composer require --dev phpunit/phpunit

# 실행
./vendor/bin/phpunit

# 버전 확인
./vendor/bin/phpunit --version

--dev 플래그 꼭 붙여줘.
테스트 도구를 프로덕션 의존성에 넣으면 배포 용량도 늘고,
보안 관점에서도 좋을 게 하나 없어.

🏗️ 2. 프로젝트 뼈대 잡기

테스트를 시작하려면 오토로딩이 먼저야.
PSR-4 규칙으로 composer.json을 이렇게 잡아보자.

{
  "autoload": {
    "psr-4": { "App\\": "src/" }
  },
  "autoload-dev": {
    "psr-4": { "Tests\\": "tests/" }
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0"
  }
}

그리고 composer dump-autoload 한 번 실행.

phpunit.xml 설정 파일

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
         cacheDirectory=".phpunit.cache"
         failOnWarning="true"
         failOnRisky="true">
    <testsuites>
        <testsuite name="Unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="Integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>
    <source>
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>

🔴🟢🔵 3. TDD의 심장, Red-Green-Refactor

TDD는 Kent Beck이 정리한 개발 방법론인데,
핵심은 단 하나야. "테스트를 먼저 쓴다."

말은 간단한데 처음 들으면 진짜 이상하게 느껴지지.
"아니, 없는 코드를 어떻게 테스트해?"
근데 그게 바로 포인트야. 테스트를 먼저 쓴다는 건 곧 "설계를 먼저 한다"는 뜻이거든.

단계별로 뜯어보기

1단계 · RED 🔴
아직 존재하지 않는 기능에 대한 테스트를 쓴다.
당연히 실패한다. 클래스가 없으니 Fatal Error가 날 수도 있어.
실패를 "확인"하는 게 중요해. 실패를 안 보면 그 테스트가
진짜 검증하고 있는지 알 수가 없거든.

2단계 · GREEN 🟢
테스트를 통과시키는 가장 단순한 코드를 쓴다.
심지어 상수를 그냥 return 해버려도 돼. 부끄러워할 필요 없어.
이걸 "가짜로 통과시키기(Fake It)"라고 부르는데, 정식 TDD 기법이야.

3단계 · REFACTOR 🔵
테스트가 초록불인 상태에서 코드를 정리한다.
중복 제거, 이름 개선, 메서드 추출.
테스트가 안전망이니까 마음껏 뜯어고칠 수 있어.

🛒 4. 실전 TDD : 장바구니 할인 계산기 만들기

말로만 하면 감이 안 오니까, 진짜 하나 만들어보자.
요구사항은 이래.

🔴 Step 1 : 첫 번째 실패 테스트

<?php
declare(strict_types=1);

namespace Tests\Unit;

use App\Cart;
use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;

final class CartTest extends TestCase
{
    #[Test]
    public function 빈_장바구니의_총액은_0원이다(): void
    {
        $cart = new Cart();

        $this->assertSame(0, $cart->total());
    }
}

실행하면?

Error: Class "App\Cart" not found

완벽해. 이게 정상적인 RED 상태야.
그리고 한국어 메서드명, PHP에서 아무 문제 없이 잘 돌아가.
팀 컨벤션만 맞으면 테스트 가독성이 확 올라가서 은근히 인기 있는 방식이야.

🟢 Step 2 : 최소 구현

<?php
declare(strict_types=1);

namespace App;

final class Cart
{
    public function total(): int
    {
        return 0;
    }
}

"이게 무슨 구현이야?" 싶지? 근데 이게 맞아.
현재 테스트를 통과시키는 최소 코드니까.
다음 테스트가 이 거짓말을 깨뜨려 줄 거야.

🔴 Step 3 : 다음 테스트로 압박하기

#[Test]
public function 상품을_담으면_가격의_합이_총액이_된다(): void
{
    $cart = new Cart();
    $cart->add('아메리카노', 4500, 2);
    $cart->add('크로와상', 3800, 1);

    $this->assertSame(12800, $cart->total());
}

이제 return 0;은 못 버텨. 진짜 구현을 해야 해.

<?php
declare(strict_types=1);

namespace App;

use InvalidArgumentException;

final class Cart
{
    /** @var array<int, array{name:string, price:int, qty:int}> */
    private array $items = [];

    public function add(string $name, int $price, int $qty = 1): void
    {
        if ($price < 0) {
            throw new InvalidArgumentException('가격은 음수일 수 없습니다.');
        }
        if ($qty < 1) {
            throw new InvalidArgumentException('수량은 1 이상이어야 합니다.');
        }

        $this->items[] = ['name' => $name, 'price' => $price, 'qty' => $qty];
    }

    public function total(): int
    {
        $sum = 0;
        foreach ($this->items as $item) {
            $sum += $item['price'] * $item['qty'];
        }
        return $sum;
    }
}

🟢 Step 4 : 할인 규칙 추가

이제 할인이야. 여러 케이스를 한 번에 검증하고 싶으니
Data Provider를 써보자. 이게 PHPUnit의 진짜 매력 포인트 중 하나야.

use PHPUnit\Framework\Attributes\DataProvider;

#[Test]
#[DataProvider('할인_시나리오')]
public function 총액에_따라_할인이_적용된다(
    int $원금, int $기대값
): void {
    $cart = new Cart();
    $cart->add('테스트상품', $원금, 1);

    $this->assertSame($기대값, $cart->payable());
}

public static function 할인_시나리오(): array
{
    return [
        '할인 없음 경계 아래' => [49_999, 49_999],
        '10% 할인 시작점'     => [50_000, 45_000],
        '10% 구간 상단'       => [99_999, 89_999],  // 89999.1 → 내림
        '15% 할인 시작점'     => [100_000, 85_000],
        '고액 결제'           => [250_000, 212_500],
    ];
}

이렇게 배열 키에 이름을 붙여두면
실패했을 때 총액에_따라_할인이_적용된다 with data set "10% 구간 상단"
이런 식으로 딱 집어서 알려줘. 디버깅 시간이 확 줄어들어.

public function payable(): int
{
    $total = $this->total();
    $rate = match (true) {
        $total >= 100_000 => 0.15,
        $total >=  50_000 => 0.10,
        default           => 0.0,
    };

    return (int) floor($total * (1 - $rate));
}

🔵 Step 5 : 리팩터링

지금 Cart가 "담기 + 계산 + 할인정책"까지 다 하고 있어.
단일 책임 원칙(SRP) 관점에서 할인 정책을 분리해보자.

interface DiscountPolicy
{
    public function rateFor(int $total): float;
}

final class TieredDiscountPolicy implements DiscountPolicy
{
    public function rateFor(int $total): float
    {
        return match (true) {
            $total >= 100_000 => 0.15,
            $total >=  50_000 => 0.10,
            default           => 0.0,
        };
    }
}

final class Cart
{
    public function __construct(
        private readonly DiscountPolicy $policy = new TieredDiscountPolicy()
    ) {}
    // ...
}

여기서 마법이 일어나.
리팩터링 후에도 테스트를 다시 돌리면 전부 초록불이야.
내부 구조를 통째로 바꿨는데 동작은 그대로라는 걸 1초 만에 증명한 거지.

이게 TDD를 하는 진짜 이유야.
테스트는 버그 잡는 도구이기 이전에 변경을 두려워하지 않게 해주는 안전벨트거든.

🎭 5. 테스트 더블 : 모킹의 세계

실무 코드는 순수 계산만 하지 않지.
DB에 붙고, API 호출하고, 메일 보내고, 파일 쓰고….

이런 걸 테스트에서 진짜로 실행하면?
느리고, 불안정하고, 진짜 고객한테 메일 날아가는 참사가 생겨.
그래서 테스트 더블(Test Double), 흔히 말하는 "가짜 객체"를 쓰는 거야.

PHPUnit에서 Stub 만들기

#[Test]
public function 환율_API가_실패하면_기본환율을_사용한다(): void
{
    $api = $this->createStub(ExchangeRateApi::class);
    $api->method('fetch')
        ->willThrowException(new \RuntimeException('timeout'));

    $converter = new CurrencyConverter($api, fallbackRate: 1300);

    $this->assertSame(130_000, $converter->toKrw(100));
}

Mock으로 "호출됐는지" 검증하기

#[Test]
public function 주문_완료시_알림이_정확히_한번_발송된다(): void
{
    $notifier = $this->createMock(Notifier::class);

    $notifier->expects($this->once())
             ->method('send')
             ->with(
                 $this->equalTo('user@example.com'),
                 $this->stringContains('주문이 완료')
             );

    $service = new OrderService($notifier);
    $service->complete(new Order('user@example.com'));
}

시간·랜덤 다루기

time()이나 rand()를 코드에 직접 박으면 테스트가 불가능해져.
"자정에만 실패하는 테스트" 같은 괴담이 여기서 나와.

interface Clock { public function now(): \DateTimeImmutable; }

final class FrozenClock implements Clock
{
    public function __construct(private \DateTimeImmutable $t) {}
    public function now(): \DateTimeImmutable { return $this->t; }
}

// 테스트에서
$clock = new FrozenClock(new \DateTimeImmutable('2025-01-01 00:00:00'));
$coupon = new Coupon(expiresAt: '2024-12-31', clock: $clock);
$this->assertTrue($coupon->isExpired());

참고로 PSR-20에 ClockInterface가 표준으로 정의돼 있어서,
새 프로젝트라면 그걸 그대로 쓰는 게 좋아.

🔍 6. Assertion, 제대로 골라 쓰기

PHPUnit엔 assertion이 수십 개 있어. 근데 실무에서 90%는 이 정도로 끝나.

예외 테스트

#[Test]
public function 음수_가격은_거부된다(): void
{
    $this->expectException(InvalidArgumentException::class);
    $this->expectExceptionMessage('가격은 음수일 수 없습니다.');

    (new Cart())->add('이상한상품', -1000);
}

📊 7. 코드 커버리지, 숫자에 속지 말자

커버리지는 테스트가 실행한 코드의 비율이야.
측정하려면 Xdebug(coverage 모드) 또는 PCOV 확장이 필요해.
속도만 놓고 보면 PCOV가 압도적으로 빠르니 CI에서는 PCOV를 추천할게.

# HTML 리포트 생성
XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-html build/coverage

# 터미널에서 요약만
XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-text

public function divide(int $a, int $b): float
{
    return $a / $b;   // 이 줄은 100% 커버됨
}

// 테스트
$this->assertSame(2.0, $calc->divide(4, 2));  // 통과!

현실적인 목표치는 보통 이래.

· 핵심 도메인 로직 : 85~95% 지향
· 전체 프로젝트 : 70~80%면 건강한 편
· 뷰/템플릿/설정 파일 : 커버리지 대상에서 제외

🧱 8. 테스트 피라미드와 현실

Mike Cohn이 제안한 테스트 피라미드는 이런 구조야.

PHP 프로젝트에서의 실제 구분

Unit 테스트 — DB도, 파일도, 네트워크도 안 건드림.
순수 PHP 객체만. 수천 개를 몇 초 만에 돌릴 수 있어야 해.

Integration 테스트 — 실제 DB(가능하면 SQLite in-memory나
도커로 띄운 MySQL)에 붙어서 Repository나 Query가 잘 도는지 확인.
트랜잭션으로 감싸고 테스트 끝나면 롤백하는 패턴이 국룰이야.

protected function setUp(): void
{
    $this->pdo = new PDO('sqlite::memory:');
    $this->pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $this->pdo->exec('CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT)');
}

protected function tearDown(): void
{
    $this->pdo = null;   // 인메모리 DB는 연결 끊기면 자동 소멸
}

E2E / Feature 테스트 — HTTP 요청을 실제로 쏴서
상태 코드와 응답 본문을 확인. Laravel의 $this->get('/api/users')나
Symfony의 WebTestCase가 이 영역이야.

⚙️ 9. CI에 물리고, 습관으로 만들기

테스트는 자동으로 돌아야 살아남아.
사람이 기억해서 돌리는 테스트는 결국 안 돌게 되거든.

# .github/workflows/tests.yml
name: Tests
on: [push, pull_request]

jobs:
  phpunit:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: ['8.2', '8.3', '8.4']
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          coverage: pcov
      - run: composer install --prefer-dist --no-progress
      - run: vendor/bin/phpunit --coverage-text

같이 쓰면 좋은 도구들

특히 Infection은 진짜 흥미로워.
코드를 일부러 변형(>를 >=로 바꾸는 식)시킨 뒤
테스트가 그걸 잡아내는지 확인해.
잡아내지 못하면 "그 테스트는 사실 아무것도 지키지 못하고 있다"는 뜻이지.
커버리지 숫자보다 훨씬 정직한 지표야.

🧯 10. 흔한 실수와 해결책

🌱 11. 그래서, 어떻게 시작할까

"기존 레거시 프로젝트인데 테스트가 0개예요. 어디부터 손대죠?"
가장 많이 듣는 질문이야. 답은 명확해.

전부 다 짜려고 하지 마.

1️⃣ 새로 쓰는 코드부터 테스트를 붙여. 과거는 일단 놔둬.
2️⃣ 버그가 난 지점에 테스트를 심어. 아픈 곳이 곧 중요한 곳이야.
3️⃣ 계산 로직·검증 로직처럼 입출력이 명확한 순수 함수부터. 가성비 최고.
4️⃣ 리팩터링할 코드 주변에 특성화 테스트(Characterization Test)를 먼저 깔아.
   현재 동작이 옳든 그르든 일단 "지금 이렇게 동작한다"를 고정시키는 거지.

그리고 하나 더.
TDD는 종교가 아니라 도구야.
프로토타입 만들 때, UI 만들 때, 한 번 쓰고 버릴 스크립트에는
굳이 TDD를 강요할 필요 없어.

대신 돈이 오가는 로직, 권한 검사, 복잡한 상태 전이,
여러 사람이 계속 건드릴 코어 모듈—
여기엔 반드시 테스트가 있어야 해. 그게 프로다움이야.

📌 마무리 : 초록불의 안도감

처음 TDD를 시작하면 무조건 느려.
"기능 하나 만드는 데 코드를 왜 두 배로 쓰지?" 싶고, 답답해.

근데 3개월쯤 지나서
아무도 건드리기 무서워하던 결제 모듈을 리팩터링하고,
터미널에 OK (247 tests, 891 assertions)가 초록색으로 뜨는 순간—

그 안도감은 진짜 겪어봐야 알아.
배포 버튼 누르는 손이 안 떨리는 경험, 그거 꽤 중독성 있거든. 😌

자, 이제 터미널 열고 composer require --dev phpunit/phpunit 한 줄만 쳐보자.
첫 번째 빨간불이 당신을 기다리고 있어. 🔴 → 🟢