beforeSuite() hook that runs after Laravel boots

[rdehnhardt]

Problem

Currently, beforeAll() runs before the Laravel application is initialized, which means we cannot use any Laravel features (facades, models, database, etc.) in it. This creates a common pain point when developers want to seed data once for multiple tests in a file.

Current behavior

<?php

use App\Models\Product;

// ❌ This throws "A facade root has not been set"
beforeAll(fn() => Product::factory()->count(50)->create());

it('can retrieve the highlights feed', function () {
    $this->getJson(route('highlights'))
        ->assertJsonCount(5, 'data')
        ->assertStatus(200);
});

it('can filter highlights', function () {
    // Would reuse the same 50 showcases
});

Current workaround

The only way to achieve this currently is using a static variable in beforeEach():

<?php

use App\Models\Product;

beforeEach(function () {
    static $initialized = false;
    
    if (!$initialized) {
        Product::factory()->count(50)->create();
        $initialized = true;
    }
});

it('test 1', function () { /* ... */ });
it('test 2', function () { /* ... */ });

This works, but it's not intuitive and requires developers to understand the internal lifecycle.

Proposed Solution

Introduce a beforeSuite() (or similar name like beforeTests(), onceBefore()) hook that runs after Laravel boots but before all tests in a file.

Proposed API

<?php

use App\Models\Product;

beforeSuite(function () {
    // Laravel is fully booted here
    Product::factory()->count(50)->create();
});

it('test 1', function () {
    expect(Product::count())->toBe(50);
});

it('test 2', function () {
    expect(Product::count())->toBe(50); // Same data available
});

Benefits

1. More intuitive API: Developers naturally expect to be able to seed data once for all tests
2. Better performance: Avoid recreating the same data for every test when it's not necessary
3. Cleaner code: No need for static variable workarounds
4. Consistent with other frameworks: Similar hooks exist in Jest, PHPUnit, etc.

Lifecycle comparison

Current

beforeAll() → [PHP only, no Laravel]
  ↓
Laravel boots
  ↓
beforeEach() → [Test 1] → afterEach()
  ↓
beforeEach() → [Test 2] → afterEach()
  ↓
afterAll()

Proposed

beforeAll() → [PHP only, no Laravel]
  ↓
Laravel boots
  ↓
beforeSuite() → [Runs once, Laravel available] ✨
  ↓
beforeEach() → [Test 1] → afterEach()
  ↓
beforeEach() → [Test 2] → afterEach()
  ↓
afterSuite() → [Optional cleanup]
  ↓
afterAll()

Alternative names

• onceBefore() / onceAfter()
• beforeTests() / afterTests()
• setupSuite() / teardownSuite()

Notes

• This should work well with RefreshDatabase trait
• Should be scoped per test file (not globally)
• An afterSuite() counterpart would also be useful for cleanup

Use cases

• Seeding test data that doesn't need to be reset between tests
• Setting up external services or mocks once
• Creating test files or directories that persist across tests
• Any expensive setup operation that doesn't need to run per test

---

Thank you for considering this feature! Pest is an amazing testing framework, and this would make the Laravel testing experience even better. 🙏