Laravel Blueprint Pestphp Addon Laravel Package

Getting Started

This addon swaps Blueprint's default PHPUnit test stubs for Pest tests, so blueprint:build emits tests/Feature/... files written in Pest's it()/test() syntax instead of class-based PHPUnit tests.

Minimum setup:

composer require --dev fidum/laravel-blueprint-pestphp-addon

Requirements as of 2.3.0: Laravel 10 and Pest 2 (PHP 8.1+). Laravel 9 support was dropped in this release — pin ^2.2 if you're still on L9. The service provider is auto-discovered; there is nothing to register manually.

Before your first generation, make sure Pest is actually wired up:

• tests/Pest.php exists and binds TestCase to your Feature/Unit directories.
• Your base TestCase is the standard Laravel one (the generated tests rely on the framework's testing helpers).

First use case — the smallest possible draft.yaml:

models:
  Post:
    title: string
    body: text
    timestamps: true

Then:

php artisan blueprint:build draft.yaml

You should get a Post model, migration, factory, and a Pest feature test covering index/store/show/update/destroy against the generated controller. That test file is the thing this package exists to produce — open it first to see whether the generated assertions match your conventions before you generate twenty more models.

Implementation Patterns

Generate-then-edit loop. Treat the draft file as the source of truth for structure and the generated Pest tests as a starting scaffold. The usual workflow is: edit draft.yaml → blueprint:build → run ./vendor/bin/pest → fill in the gaps Blueprint can't infer (authorization, business rules, validation edge cases). Regenerating overwrites the test file, so keep hand-written assertions in a separate file (e.g. PostManagementTest.php) rather than layering them into the generated one.

Per-model opt-in. Not every model needs generated tests. Blueprint's tests: key on a model lets you skip scaffolding for lookup tables and pivot-only models, which keeps the noise down:

models:
  Country:
    name: string
    tests: false

Seed the draft from an existing schema. For brownfield projects, php artisan blueprint:new + blueprint:trace (from the core Blueprint package) reverse-engineers models into a draft, then blueprint:build produces Pest tests for code you already have. This is the fastest way to get coverage on a legacy app without hand-writing test files.

Pair it with blueprint:erase carefully. erase removes generated files based on the draft; the Pest tests are in that set. Use it in throwaway branches or when re-scaffolding, never as a cleanup command on a branch with hand-edited generated tests.

CI integration. Composer-require the addon as a dev dependency and let generated tests run in the normal Pest suite. Because output is plain Pest, your existing pest.xml/phpunit.xml suites, coverage thresholds, and parallel-run config apply unchanged — no special runner needed.

Team convention enforcement. If you want different assertions (e.g. assertSuccessful() instead of assertStatus(200), or JSON-based assertions for API controllers), publish and edit the package's stubs once and commit them, rather than editing every generated file. Check the README for the vendor:publish tag — stubs are the intended extension point.

Gotchas and Tips

2.3.0 is a breaking bump for Laravel 9 users. There's no deprecation path — the release drops L9 outright. If you're mid-upgrade, keep fidum/laravel-blueprint-pestphp-addon:^2.2 until the app is on Laravel 10, otherwise Composer will fail to resolve. Conversely, on Laravel 10 you need ^2.3.

Blueprint's support policy means generated code tracks the latest conventions. The tests emitted by 2.3.0 assume Laravel 10 idioms. Don't run it against an L9 codebase "just to see" — the generated tests may reference helpers or testing APIs that don't exist on the older framework.

RefreshDatabase isn't free. Generated feature tests hit the database. Make sure uses(RefreshDatabase::class) is applied in tests/Pest.php (or the generated files do it themselves) — otherwise you'll see state leaking between generated tests, which look like flaky failures in CI but pass individually.

Route/model binding assumptions. Generated controller tests assume route-model binding and resourceful routes registered exactly as Blueprint names them. If you rename a route or add a prefix, the generated tests break on the first request. Fix the draft (routes: / controllers:) rather than the test file, so the next regeneration is clean.

Validation coverage is shallow. Expect happy-path plus a couple of required-field assertions. The tests are a starting point, not a coverage guarantee — check with --coverage before trusting the green checkmark.

Mixed PHPUnit/Pest codebases. The addon only affects Blueprint output; it won't convert your existing PHPUnit tests. Both runners coexist fine, but be aware the generated files are Pest-only and won't run under plain PHPUnit if anyone invokes it directly.

Debugging generation. If you get PHPUnit-style output instead of Pest, the provider didn't load or a stale Composer autoload is in play — composer dump-autoload and confirm the package appears in composer show. If the tests generate but fail to run, the problem is almost always tests/Pest.php bindings, not the addon.

Version-pin in CI images. Since the addon's output changes with Blueprint's conventions, pinning both laravel-shift/blueprint and this addon avoids surprise diffs in regenerated test files across team members.