使用 Pest 進行進階測試 - Knowledge of Laravel

什麼是 Pest

Pest 是建構於 PHPUnit 之上的測試框架，自 Laravel 11 以後於新專案中預設採用。可繼續使用 PHPUnit 豐富的斷言集，同時以 closure 為基礎的簡潔語法撰寫測試。與 PHPUnit 的主要差異：

觀點	Pest	PHPUnit
測試定義	`test()` / `it()` closure	以方法定義的類別
斷言	Expectation API（`expect()->toBe()`）	`$this->assert*()`
Dataset	`dataset()` / `with()`	`@dataProvider`
Hook	`beforeEach()` / `afterEach()`	`setUp()` / `tearDown()`
巢狀	以 `describe()` 分組	以類別分隔

Pest 的測試由 PHPUnit 執行，因此可與既有的 PHPUnit 測試共存。以 php artisan test 或 vendor/bin/pest 執行。

`describe` / `it` / `test` 的區別

`test()`

最單純的定義。將測試名稱直接作為說明文使用。

test('使用者可以使用電子郵件登入', function () {
    $user = User::factory()->create();

    $response = $this->post('/login', [
        'email' => $user->email,
        'password' => 'password',
    ]);

    $response->assertRedirect('/dashboard');
});

`it()`

可以類似「it should…」的英文文體，寫出接近自然語言的敘述。

it('將未驗證的使用者重新導向至登入頁', function () {
    $response = $this->get('/dashboard');

    $response->assertRedirect('/login');
});

`describe()`

將相關的測試分組。用於共享 beforeEach() 或於檔案內的邏輯整理。

describe('訂單管理', function () {
    beforeEach(function () {
        $this->user = User::factory()->create();
        $this->actingAs($this->user);
    });

    it('可以取得訂單列表', function () {
        Order::factory(3)->for($this->user)->create();

        $response = $this->get('/orders');

        $response->assertOk()->assertJsonCount(3, 'data');
    });

    it('無法取得其他使用者的訂單', function () {
        $other = User::factory()->create();
        Order::factory()->for($other)->create();

        $response = $this->get('/orders');

        $response->assertOk()->assertJsonCount(0, 'data');
    });
});

describe() 可以巢狀。但過深的巢狀會使測試難以閱讀，建議以 2 層為限。

Expectation API

expect() 是 Pest 特有的斷言語法。可以方法鏈累積條件。

基本斷言

expect($value)->toBe(42);               // 嚴格相等（===）
expect($value)->toEqual(['a' => 1]);    // 寬鬆相等（==）
expect($value)->toBeTrue();
expect($value)->toBeFalse();
expect($value)->toBeNull();
expect($value)->not->toBeNull();

expect($string)->toContain('Laravel');
expect($array)->toHaveCount(3);
expect($array)->toHaveKey('email');
expect($array)->toContain('admin');

expect($number)->toBeGreaterThan(0);
expect($number)->toBeLessThanOrEqual(100);

對模型的斷言

expect($user)->toBeInstanceOf(User::class);
expect($user->email)->toMatchRegex('/^.+@.+\..+$/');

// 確認資料庫的儲存
expect(User::where('email', '[email protected]')->exists())->toBeTrue();

`and()` 鏈

expect($response->status())->toBe(200)
    ->and($response->json('name'))->toBe('Laravel')
    ->and($response->json('version'))->toBeGreaterThan(12);

以 `each()` 驗證陣列各元素

$users = User::factory(3)->create();

expect($users)->each(function ($user) {
    $user->toBeInstanceOf(User::class)
        ->email->not->toBeNull();
});

使用 Dataset 的參數化測試

若要以多個輸入值測試相同邏輯，可使用 dataset() 或 inline 的 with()。

Inline Dataset

it('無效的電子郵件會產生驗證錯誤', function (string $email) {
    $response = $this->post('/register', ['email' => $email]);

    $response->assertInvalid('email');
})->with([
    '純文字' => ['not-an-email'],
    '無網域' => ['user@'],
    '空字串' => [''],
]);

具名 Dataset

於 tests/Datasets 目錄定義 Dataset。

// tests/Datasets/InvalidEmails.php
dataset('invalid_emails', [
    'plain' => ['not-an-email'],
    'no-domain' => ['user@'],
    'empty' => [''],
    'spaces' => ['user @example.com'],
]);

it('無效的電子郵件會產生驗證錯誤', function (string $email) {
    $response = $this->post('/register', ['email' => $email]);

    $response->assertInvalid('email');
})->with('invalid_emails');

使用 Closure 的動態 Dataset

it('每個使用者方案有不同的限制', function (string $plan, int $limit) {
    $user = User::factory()->create(['plan' => $plan]);

    expect($user->requestLimit())->toBe($limit);
})->with([
    ['free', 100],
    ['pro', 1000],
    ['enterprise', 10000],
]);

使用 Mockery 的單元測試

服務的 Mock

use App\Services\PaymentGateway;
use Mockery\MockInterface;

test('會呼叫支付服務', function () {
    $mock = $this->mock(PaymentGateway::class, function (MockInterface $mock) {
        $mock->expects('charge')
            ->with(1000, 'twd')
            ->andReturn(['status' => 'succeeded']);
    });

    $result = app(PaymentGateway::class)->charge(1000, 'twd');

    expect($result['status'])->toBe('succeeded');
});

Spy

Spy 與 Mock 不同，會呼叫實作並留下呼叫紀錄。

use App\Services\NotificationService;

test('確認是否呼叫了通知服務', function () {
    $spy = $this->spy(NotificationService::class);

    $this->post('/orders', ['amount' => 1000]);

    $spy->shouldHaveReceived('send')->once()->with('order.created');
});

部分 Mock

僅 mock 部分方法，其餘使用實際實作。

use App\Services\ReportService;
use Mockery\MockInterface;

test('跳過報表的檔案寫入', function () {
    $mock = $this->partialMock(ReportService::class, function (MockInterface $mock) {
        $mock->expects('writeFile')->andReturnNull();
    });

    $result = $mock->generate();

    expect($result)->not->toBeNull();
});

以 HTTP Fake 進行外部 API 呼叫的測試

使用 Http::fake() 可以不實際送出 HTTP 請求即 stub 回應。

基本 Fake

use Illuminate\Support\Facades\Http;

test('從外部 API 取得使用者資訊', function () {
    Http::fake([
        'https://api.example.com/users/*' => Http::response([
            'id' => 1,
            'name' => 'Laravel User',
        ], 200),
    ]);

    $result = app(UserApiClient::class)->find(1);

    expect($result['name'])->toBe('Laravel User');
    Http::assertSent(fn ($request) => $request->url() === 'https://api.example.com/users/1');
});

錯誤回應的測試

test('當 API 回傳錯誤時發生例外', function () {
    Http::fake([
        'api.example.com/*' => Http::response([], 503),
    ]);

    expect(fn () => app(UserApiClient::class)->find(1))
        ->toThrow(\App\Exceptions\ApiUnavailableException::class);
});

網路故障的模擬

use Illuminate\Http\Client\ConnectionException;

test('處理連線錯誤', function () {
    Http::fake(fn () => throw new ConnectionException('Connection refused'));

    $result = app(UserApiClient::class)->findWithFallback(1);

    expect($result)->toBeNull();
});

事件、Mail、Notification 的 Fake

`Event::fake()`

use Illuminate\Support\Facades\Event;
use App\Events\OrderCreated;

test('建立訂單時觸發事件', function () {
    Event::fake();

    $this->post('/orders', ['product_id' => 1, 'amount' => 1000]);

    Event::assertDispatched(OrderCreated::class, function ($event) {
        return $event->order->amount === 1000;
    });
});

亦可僅 fake 特定事件，其餘實際處理。

Event::fake([OrderCreated::class]);

`Mail::fake()`

use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

test('使用者註冊時傳送歡迎信', function () {
    Mail::fake();

    $this->post('/register', [
        'name' => 'Test User',
        'email' => '[email protected]',
        'password' => 'password',
        'password_confirmation' => 'password',
    ]);

    Mail::assertSent(WelcomeEmail::class, function ($mail) {
        return $mail->hasTo('[email protected]');
    });
});

`Notification::fake()`

use Illuminate\Support\Facades\Notification;
use App\Notifications\OrderShipped;

test('出貨時傳送通知', function () {
    Notification::fake();

    $user = User::factory()->create();
    $order = Order::factory()->for($user)->create();

    $this->post("/orders/{$order->id}/ship");

    Notification::assertSentTo($user, OrderShipped::class, function ($notification) use ($order) {
        return $notification->order->id === $order->id;
    });
});

Artisan 指令的測試

use Illuminate\Support\Facades\Artisan;

test('刪除不需資料的指令運作', function () {
    $expired = Order::factory()->create(['expires_at' => now()->subDay()]);
    $valid = Order::factory()->create(['expires_at' => now()->addDay()]);

    $this->artisan('orders:cleanup')
        ->assertSuccessful()
        ->expectsOutput('Cleaned up 1 expired order(s).');

    expect(Order::find($expired->id))->toBeNull();
    expect(Order::find($valid->id))->not->toBeNull();
});

互動式指令的測試

test('互動式指令於確認後執行處理', function () {
    $this->artisan('reports:generate')
        ->expectsQuestion('是否執行？', 'yes')
        ->expectsOutput('已產生報表。')
        ->assertExitCode(0);
});

`RefreshDatabase` 與 `LazilyRefreshDatabase`

`RefreshDatabase`

於各測試後將資料庫 rollback，保持乾淨狀態。於測試 suite 開始時執行 migration。

// tests/Pest.php
uses(RefreshDatabase::class)->in('Feature');

use Illuminate\Foundation\Testing\RefreshDatabase;

test('可以建立使用者', function () {
    $user = User::factory()->create(['name' => 'Laravel']);

    expect(User::count())->toBe(1);
    expect($user->name)->toBe('Laravel');
});

`LazilyRefreshDatabase`

RefreshDatabase 會於所有測試中確認 migration，而 LazilyRefreshDatabase 會將 migration 延遲至實際會變更資料庫的測試被執行為止。若有大量不觸及資料庫的測試，可以加速。

// tests/Pest.php
uses(LazilyRefreshDatabase::class)->in('Feature');

對大多數專案而言 RefreshDatabase 為安全的選擇。若測試 suite 龐大且有大量無資料庫操作的測試時，可考慮 LazilyRefreshDatabase。

觀點	`RefreshDatabase`	`LazilyRefreshDatabase`
Migration 執行時機	測試 suite 開始時	首次 DB 操作時
不觸及 DB 的測試額外負擔	有	無
建議情境	一般案例	測試數多且不使用 DB 的測試較多時

程式碼覆蓋率的量測

需要 Xdebug 或 PCOV。

# 於終端機顯示覆蓋率
php artisan test --coverage

# 強制最低覆蓋率（低於則 CI 失敗）
php artisan test --coverage --min=80

# 輸出 HTML 報告
vendor/bin/pest --coverage-html=coverage/

# 確認緩慢的測試
php artisan test --profile

程式碼覆蓋率的量測會大幅增加測試執行時間。於 CI 環境建議分割至專用 job，或設定為僅於 pull request 時執行。

測試入門

確認 Laravel 中測試的基本撰寫方式與 php artisan test 的使用方式。

​什麼是 Pest

​describe / it / test 的區別

​test()

​it()

​describe()

​Expectation API

​基本斷言

​對模型的斷言

​and() 鏈

​以 each() 驗證陣列各元素

​使用 Dataset 的參數化測試

​Inline Dataset

​具名 Dataset

​使用 Closure 的動態 Dataset

​使用 Mockery 的單元測試

​服務的 Mock

​Spy

​部分 Mock

​以 HTTP Fake 進行外部 API 呼叫的測試

​基本 Fake

​錯誤回應的測試

​網路故障的模擬

​事件、Mail、Notification 的 Fake

​Event::fake()

​Mail::fake()

​Notification::fake()

​Artisan 指令的測試

​互動式指令的測試

​RefreshDatabase 與 LazilyRefreshDatabase

​RefreshDatabase

​LazilyRefreshDatabase

​程式碼覆蓋率的量測

​相關頁面

測試入門

什麼是 Pest

`describe` / `it` / `test` 的區別

`test()`

`it()`

`describe()`

Expectation API

基本斷言

對模型的斷言

`and()` 鏈

以 `each()` 驗證陣列各元素

使用 Dataset 的參數化測試

Inline Dataset

具名 Dataset

使用 Closure 的動態 Dataset

使用 Mockery 的單元測試

服務的 Mock

Spy

部分 Mock

以 HTTP Fake 進行外部 API 呼叫的測試

基本 Fake

錯誤回應的測試

網路故障的模擬

事件、Mail、Notification 的 Fake

`Event::fake()`

`Mail::fake()`

`Notification::fake()`

Artisan 指令的測試

互動式指令的測試

`RefreshDatabase` 與 `LazilyRefreshDatabase`

`RefreshDatabase`

`LazilyRefreshDatabase`

程式碼覆蓋率的量測

相關頁面