Octane Testbench Laravel Package

Getting Started

• Install as a dev dependency: composer require --dev cerbero/octane-testbench. It is test-only tooling; nothing is added to your production runtime.
• Prerequisites matter more than usual here. You need Laravel Octane installed and configured (config/octane.php), and your test environment needs whatever the selected driver requires (Swoole extension or the RoadRunner binary), because the package simulates Octane's worker lifecycle in-process rather than stubbing it out.
• Do not sprinkle the trait on every test. Create a dedicated base test case (e.g. Tests\OctaneTestCase) that pulls in the package's testing concern, and have only Octane-specific tests extend it. Regular feature tests are cheaper and less surprising without the Octane boot overhead.
• Read src/ first. The package is deliberately small — a handful of classes — and the README is terse. The source is the actual API documentation; you can read the whole thing in a few minutes.
• First useful use case: prove that a singleton or service does not leak state across Octane requests. Boot the worker once, handle a request that mutates the singleton, handle a second request, and assert the second request sees clean state. That single test catches the class of bug Octane projects actually ship.

public function test_singleton_is_reset_between_requests(): void
{
    $this->octane()->handle($this->makeRequest('/mutate'));
    $response = $this->octane()->handle($this->makeRequest('/read-state'));

    $this->assertSame('clean', $response->getContent());
}

(Check the trait for the exact method names; the package exposes worker boot, request handling, termination, and tick helpers rather than a full HTTP kernel.)

Implementation Patterns

• Worker lifecycle testing. The core value is simulating the sequence bootstrap → request → terminate → next request without a real Swoole server. Use it to test that listeners on Octane events (WorkerStarting, WorkerStopping, RequestReceived, RequestHandled, RequestTerminated, TickReceived, TaskReceived) actually fire and do what you expect.
• Listener assertions. Register listeners in config/octane.php, then handle a simulated request and assert on side effects (a log write, a cache bump, an injected header) rather than on the presence of the event itself. Combining Event::fake() with Octane bootstrapping is fragile; prefer observable effects.
• Tick callbacks. Octane::tick(...) closures are otherwise almost impossible to unit test. Use the package to invoke a tick and assert the callback ran, the interval logic is honored, and the callback is idempotent.
• State isolation as a pattern. Write one test per shared singleton/mutable global, always in the mutate-then-observe shape above. This is the single highest-value pattern for Octane applications and the reason to add the dependency.
• Request/response round-trips. Assert middleware, headers, and terminate middleware behavior under Octane semantics, where termination happens after the response is sent and the container is reused.
• Concurrent tasks. If you use Octane::concurrently(...), test that the task results merge correctly and that failures inside a task propagate the way you expect. The worker helpers let you exercise this without a live server.
• Integration tip: keep Octane tests in a separate directory (tests/Octane/) and a separate PHPUnit test suite so CI can run them only on the PHP/extension combination that matches production.

Gotchas and Tips

• Driver coupling. The package boots Octane's worker, so the test process needs the same driver and extensions as production. Running Octane tests in a plain phpunit image without Swoole will fail before your assertions run. Gate the suite in CI.
• Small package, thin API. With ~43 stars and no dependents, treat it as a utility you may need to read, patch, or vendor. Pin the version in composer.json and check compatibility with your Laravel/Octane major version before upgrading either.
• Don't fake the events you're testing. Event::fake() intercepts the very dispatch you're trying to observe. If you need to confirm a listener ran, assert the side effect; if you need to confirm an event was dispatched, use a targeted Event::fake([...]) that excludes the Octane events.
• Container reuse is the bug, not the feature. The package will happily reuse the application container between simulated requests, which is realistic but means a failing test often reflects a real leak. When debugging, add a throwaway assertion between requests to inspect the singleton's state and confirm when it changes.
• Bootstrap once per test, not per assertion. Booting the worker is the expensive part. Structure tests as a single boot followed by multiple request assertions; avoid re-booting inside data providers.
• Config quirks. Octane's config includes listener arrays and warm/flush lists. If your listener isn't firing, verify it's actually registered in the config file the test resolves — cached config in the test bootstrap is a common culprit.
• Extension points. The package resolves Octane through the container, so you can bind fakes (fake caches, fake queue connections, a spy logger) before booting the worker and assert on those. That's usually cleaner than trying to introspect Octane internals.
• Fallback plan. If a specific Octane behavior isn't covered, drop down to the underlying Octane classes directly — the package is a thin convenience layer, not a framework. Reading src/ will show you exactly which Octane primitive to call yourself.