headroom/backend/.agents/skills/pest-testing/SKILL.md

name, description, license, metadata

name	description	license	metadata
pest-testing	Tests applications using the Pest 3 PHP framework. Activates when writing tests, creating unit or feature tests, adding assertions, testing Livewire components, architecture testing, debugging test failures, working with datasets or mocking; or when the user mentions test, spec, TDD, expects, assertion, coverage, or needs to verify functionality works.	MIT	author laravel

Pest Testing 3

When to Apply

Activate this skill when:

• Creating new tests (unit or feature)
• Modifying existing tests
• Debugging test failures
• Working with datasets, mocking, or test organization
• Writing architecture tests

Documentation

Use search-docs for detailed Pest 3 patterns and documentation.

Basic Usage

Creating Tests

All tests must be written using Pest. Use php artisan make:test --pest {name}.

Test Organization

• Tests live in the tests/Feature and tests/Unit directories.
• Do NOT remove tests without approval - these are core application code.
• Test happy paths, failure paths, and edge cases.

Basic Test Structure

it('is true', function () {
    expect(true)->toBeTrue();
});

Running Tests

• Run minimal tests with filter before finalizing: php artisan test --compact --filter=testName.
• Run all tests: php artisan test --compact.
• Run file: php artisan test --compact tests/Feature/ExampleTest.php.

Assertions

Use specific assertions (assertSuccessful(), assertNotFound()) instead of assertStatus():

it('returns all', function () {
    $this->postJson('/api/docs', [])->assertSuccessful();
});

Use	Instead of
assertSuccessful()	assertStatus(200)
assertNotFound()	assertStatus(404)
assertForbidden()	assertStatus(403)

Mocking

Import mock function before use: use function Pest\Laravel\mock;

Datasets

Use datasets for repetitive tests (validation rules, etc.):

it('has emails', function (string $email) {
    expect($email)->not->toBeEmpty();
})->with([
    'james' => 'james@laravel.com',
    'taylor' => 'taylor@laravel.com',
]);

Pest 3 Features

Architecture Testing

Pest 3 includes architecture testing to enforce code conventions:

arch('controllers')
    ->expect('App\Http\Controllers')
    ->toExtendNothing()
    ->toHaveSuffix('Controller');

arch('models')
    ->expect('App\Models')
    ->toExtend('Illuminate\Database\Eloquent\Model');

arch('no debugging')
    ->expect(['dd', 'dump', 'ray'])
    ->not->toBeUsed();

Type Coverage

Pest 3 provides improved type coverage analysis. Run with --type-coverage flag.

Common Pitfalls

• Not importing use function Pest\Laravel\mock; before using mock
• Using assertStatus(200) instead of assertSuccessful()
• Forgetting datasets for repetitive validation tests
• Deleting tests without approval