SIGNALS Docs

Testing plugins

Boot one package in Pest, fake outbound HTTP, and generate editor and PHPStan stubs.

Run a package's tests

The host must have its Pest development dependencies installed. A production deployment installed without them refuses plugin test execution; install the development dependencies in your test environment first.

Use a development framework checkout with Composer development dependencies installed. Put the package under plugins/vendor/name, or install it through Composer. Add tests/ and an autoload-dev.psr-4 map to the package's composer.json.

{
  "autoload": {"psr-4": {"Acme\\Example\\": "src/"}},
  "autoload-dev": {"psr-4": {"Acme\\Example\\Tests\\": "tests/"}}
}

Each test file opts into the framework harness:

use App\Sdk\Testing\PluginTestCase;

uses(PluginTestCase::class);

it('boots the package', function (): void {
    expect($this->manifest()->package)->toBe('acme/example');
});

Run from the framework root:

php artisan signals:plugin test acme/example --compact
php artisan signals:plugin test acme/example --filter='boots the package'

The command refuses production and cached configuration. It runs only that package's tests/ in a fresh Pest process, registers both PSR-4 maps before test files load, disables test impact analysis, streams output, and returns Pest's exit status. The temporary bootstrap and isolated runtime are removed afterwards. Keep uses(PluginTestCase::class) in each test file; package-local tests/Pest.php is not the opt-in mechanism.

The child receives SIGNALS_PLUGIN_UNDER_TEST and SIGNALS_PLUGIN_UNDER_TEST_PATH. For an independently configured test runner, override protected static function pluginPath(): string with an absolute package root. Use the framework's testing configuration and development autoloader.

Lifecycle and helpers

PluginTestCase extends the framework test case and uses RefreshDatabase. The supplied runner pins the framework testing environment, including SQLite :memory:, rather than inheriting a developer database. It scopes discovery to the selected package, reviews and grants the current capability plan through the install action, runs migrations, enables the package, then boots it with the real bootstrapper. A registration or boot error fails setup with its diagnostic message. Do not instantiate plugins in the framework's tests/Pest.php.

Helper Purpose
plugin() The instance used for registration and boot
context() The package's PluginContext
manifest() The validated PluginManifest
renderSlot($slot, $context = []) Render registered slot content with normal permission checks
callTool($name, $args, $as = null) Run a tool through authorization, argument validation and plugin scope
fireEvent($name, $payload, $version = 1, $source = []) Dispatch a published catalogue event to plugin listeners
assertHookRegistered($name, $type) Assert the package registered a hook; catalogue listeners use event: before the name
actingAsPluginUser($permissions) Create and sign in a factory user with the requested existing permissions

App\Sdk\Testing\MakesPluginManifests, FakesPluginHooks, and RecordingPluginHookDispatcher are also public test helpers. A fake records dispatches without invoking handlers. Use the real dispatcher when testing listener effects; its production failure isolation still applies, so assert the expected HTTP, database or notification effect.

Settings, hooks, slots and tools

Check settings defaults and encrypted declarations with context()->setting() and manifest()->settings. Configure values through the host's plugin settings form or settings service in host integration tests; the context exposes reads, not a settings-write method. Never commit credentials in fixtures.

Sign in with actingAsPluginUser() before rendering permission-gated slots or calling tools. Test an unauthorized user as well. Use fireEvent('invoice.issued', ['invoice' => ['id' => 42], 'subject' => ['id' => 42]]) for catalogue listeners, and assert the listener's observable result. Plugin-owned Eloquent models can verify rows in tables created by package migrations. Those migrations must work on SQLite for this harness.

Fake HTTP with the allowlist in place

use Illuminate\Support\Facades\Http;

Http::fake(['api.accounting.example/*' => Http::response([], 202)]);
$this->fireEvent('invoice.issued', ['invoice' => ['id' => 42], 'subject' => ['id' => 42]]);
Http::assertSent(fn ($request): bool => $request['invoice_id'] === 42);

Declare api.accounting.example in network and send requests through $context->http(). Faking transport does not grant access to undeclared hosts. The base case prevents stray HTTP requests. Include a disallowed-host test and a failed-response test for outbound integrations.

Jobs and CI

Use Queue::fake() or Bus::fake() around the action that dispatches a job, assert dispatch, then test the handler separately with the package enabled. Extend PluginJob, implement run(PluginContext $context): void, and dispatch through $context->dispatch(); a queue fake alone does not prove package and tenant restoration. Test eligibility, retries and side effects with the real handler as well. Declare schedules[] and register each key with schedule() for recurring work; see Jobs and schedules.

CI should run both:

php artisan signals:plugin check acme/example --wire --json
php artisan signals:plugin test acme/example --compact

Require valid: true and wire.ok: true. Wiring checks validate registration; package tests exercise behavior. Both commands are available in this release. The wiring check runs only register() in a discarded transaction and restored runtime checkpoint; it does not call boot().

Editor and PHPStan package

packages/plugin-sdk contains generated signatures for SdkSurface::STABLE_CLASSES, one stub per framework class, interface or enum, plus framework types referenced by inheritance, native signatures and PHPDoc type tags. Every supporting declaration outside STABLE_CLASSES is marked @internal; these declarations resolve types and are not supported plugin entry points. Prose and @see references do not expand the package. Third-party types come from the plugin’s installed dependencies. It has no Composer autoload map and must never supply runtime classes. Use the framework runtime for execution.

For local development, add a Composer path repository pointing at the framework's packages/plugin-sdk directory and require signals-rental/plugin-sdk as a development dependency. It is a local package until a release is published; no public registry availability is implied. Point your editor's additional indexing paths at its stubs/ directory. For PHPStan:

includes:
    - vendor/signals-rental/plugin-sdk/phpstan/extension.neon

Plain PHPStan types $this in Pest closures as Pest\PendingCalls\TestCall, so exclude tests/ from plain analysis or expect undefined-method diagnostics for test-case helpers.

Keep the generated package aligned with the framework:

php artisan signals:sdk-stubs
php artisan signals:sdk-stubs --check
composer validate packages/plugin-sdk/composer.json

The package's extra.signals.sdk_version records the framework SDK version at generation time. Stubs contain declarations, PHPDoc and throwing method bodies; they are excluded from Pint so regeneration remains deterministic. The PHPStan extension scans these declarations without loading them at runtime. Install the Laravel, PHPUnit and other third-party dependencies used by your plugin; their types are not replaced by this package.

This host release uses Laravel 13 and PHP 8.4 or 8.5. Laravel supplies its Illuminate components at the same major version. A production requirement such as illuminate/http: ^12.0 conflicts with this host even if a local plugin's wiring check succeeds. Declare runtime dependencies supported by the target host; put standalone testing and analysis tools in require-dev. The SDK contract version does not identify the Laravel version. Check Composer dependency resolution separately from check --wire, which validates registration and does not resolve Composer requirements. Do not bundle another Laravel runtime or autoload the SDK stubs into the application.

Version 2 event fixtures

Register the listener with payloadVersion: 2, create the invoice/payment fixtures, then provide the source document identity:

$this->fireEvent('payment.recorded', ['invoice' => ['id' => 42], 'subject' => ['id' => 42]], version: 2, source: ['document_id' => 991, 'revision' => 17]);

The harness uses the production envelope builder and the plugin's read declarations. Assert document()->id, revision() and data(); without read access data() is empty and the envelope carries data_omitted_reason. Fixture ids must refer to records created in the isolated test database.

Fake connections

fakeConnection(string $key, array $config = [], array $tokens = ['access_token' => 'test', 'expires_in' => 3600], ?string $organisationId = null, ?User $user = null) returns a connected SDK handle for the test plugin, without OAuth. The row still uses encrypted storage and the real package/HTTP guards. Use Http::fake() for remote responses.

Integration identity helper

actingAsIntegrationPrincipal(?array $permissions = null, ?array $warehouseIds = null) grants the plugin's declared identity and returns its user row. Optional permissions narrow the grant. Enter the identity with $this->context()->asIntegrationPrincipal(...); test both allowed reads and permission/warehouse denials. The helper uses the normal grant service and does not leave an interactive user signed in.

Typed slots, actions and refresh helpers

slotContext(string $slot, ?int $recordId = null, array $attributes = [], ?string $activeTab = null): SlotContext builds the catalogue-validated context for a host slot. Pass it to renderSlot() and assert record identity, guarded reads and denied users. For record slots create the host record through the public fixture helpers below.

submitAction(string $actionKey, array $values, ?SlotContext $record = null, ?User $as = null): PluginActionResult executes a registered action through the real core form. It applies field validation, permissions and guarded record selection, and restores the prior authenticated user afterwards. Assert the returned success/invalid/error result as well as handler effects. Use Livewire tests separately for UI-specific confirmation and snapshot checks.

refreshSection(string $page, string $sectionKey): array calls the real keyed refresh component and returns its latest data. Sign in with an authorized user first. Test permission revocation and provider failure through the component when asserting last-good-data notices and throttling.

Start with the sandbox app setup for the local checkout, CI and the limits of these checks.

Core-record fixtures (SDK 2.1.1)

Plugin tests can create records without importing internal core models or factories:

Helper Result
createRental(array $attributes = []) Rental ID
createIssuedInvoice(array $attributes = []) Issued invoice ID
createVehicle(array $attributes = [], array $warehouseIds = []) Vehicle ID; unique warehouse assignments, or unassigned when empty
createCreditNote(array $attributes = []) Credit-note ID
createPayment(array $attributes = []) Invoice-payment ID
createPurchaseOrder(array $attributes = []) Purchase-order ID
createWarehouse(array $attributes = []) Warehouse ID
createUser(array $attributes = [], array $permissions = [], array $warehouseIds = []) User for actingAs() or submitAction(as: ...); does not sign in automatically

These use host factories: attributes override factory defaults, and missing parent records are created by the factories. Finance fixtures create projections, not accounting postings or operation receipts. Pass an existing invoice_id to link a credit note or payment. createUser() gives only the requested permissions; nonempty warehouse IDs restrict a regular user's access through account assignments. An empty list retains the factory's unrestricted membership default. Owner attributes retain normal owner privileges. Vehicle fixtures with no assignments remain globally visible under the normal vehicle scope.

$warehouseId = $this->createWarehouse(['name' => 'North depot']);
$vehicleId = $this->createVehicle(['name' => 'Delivery van'], [$warehouseId]);
$user = $this->createUser(permissions: ['vehicles.view'], warehouseIds: [$warehouseId]);
$this->actingAs($user);
$slot = $this->slotContext('fleet_vehicle.detail.tabs', $vehicleId);
expect($this->renderSlot('fleet_vehicle.detail.tabs', $slot))->toContain('Delivery van');

The example assumes the plugin declares and registers that slot and declares the vehicle name read field. Test another warehouse and a user without vehicles.view to cover denied access.