Pest Plugin Laravel Package

Getting Started

This package (pestphp/pest-plugin) provides the internal API for extending Pest (e.g., building plugins like pest-plugin-laravel, pest-plugin-artisan, etc.). It is not meant for direct end-user usage — instead, it powers official and community plugins.

• First step: Understand Pest’s core concepts via the main Pest repo and official docs at pestphp.com.
• Typical use case: You’d use this only if you’re developing a Pest plugin (e.g., adding domain-specific matchers, hooks, or test extensions for your framework or library).
• To start building a plugin: install this package as a require-dev dependency in your plugin project (e.g., composer require pestphp/pest-plugin --dev), then consult its src/ structure — key interfaces include Plugin, PluginServiceProvider, and PluginContract.

Implementation Patterns

• Plugin Registration: Implement Pest\Plugin\Plugin and register your plugin via Pest\Plugins\register(YourPlugin::class) in your package’s ServiceProvider (often PestServiceProvider).
• Extending Test Context: Use addMacro() or beforeEach() hooks inside your plugin to augment global test behavior (e.g., Pest::macro('actingAsUser', fn() => $this->actingAs(User::factory()->create()))).
• Hooking into Test Lifecycle: Leverage Plugin::beforeEach(), afterEach(), beforeAll(), afterAll() to inject setup/cleanup logic globally or per group.
• Integration Tips:
  • Plugin logic should be side-effect free until registered (defer all bootstrapping to hooks or explicit method calls).
  • Use dependency injection via Laravel’s container or Symfony’s DI where applicable.
  • Plugins usually depend on pestphp/pest, not this package directly — the plugin API is bundled and exposed as part of pestphp/pest in production.

Gotchas and Tips

• Do not use directly in app tests — this package provides internal abstractions; misusing it (e.g., importing Plugin classes into your tests/Pest.php) can break compatibility.
• Version coupling: Plugin versions often require matching Pest versions (e.g., pest-plugin-laravel v2.x only works with Pest v2.x). Pin versions rigorously.
• Debugging tips:
  • If a plugin fails to load, run ./vendor/bin/pest --init to reinitialize Pest’s config.
  • Use Pest\Plugins\loaded() to list registered plugins (great for development).
• Extension points:
  • Override expectations via expect()->extend('toBeEven', fn() => $this->value % 2 === 0).
  • Add custom CLI flags with Plugin::extendConsoleOutput() (if available in your version).
• Maturity warning: Despite its name, this package’s docs are sparse — rely on inspecting official plugins (pestphp/pest-plugin-laravel, pestphp/pest-plugin-livewire) as de facto examples.