Download the PHP package kirschbaum-development/pest-plugin-realtime without Composer

Pest Plugin Realtime

Deterministically test realtime browser behavior, dropped events, and connection recovery with Pest.

The first driver targets Laravel Echo with its Pusher-compatible connector, including Reverb, Pusher, and Ably's Pusher protocol. It operates at the existing Echo subscription boundary, so no realtime server is required during browser tests.

The integration is tested in a real browser against Laravel Echo 2.x and pusher-js 8.x. The package does not install those JavaScript libraries in consuming applications; it uses the application's existing client.

Requirements

• PHP 8.3+
• Pest 4 or 5
• Pest Browser 4 or 5
• A page using Laravel Echo's Pusher-compatible connector

Installation

Your browser-test frontend must create its normal Echo subscriptions. It can point to a closed local port because the simulator stops the real client after the page loads.

Backend broadcasting can remain disabled. The session temporarily replaces Laravel's configured broadcast connections and restores them afterward.

Usage

There is no setup step. The browser runtime installs itself on the first realtime call, the simulated client starts connected, and inside a booted Laravel application the session captures the app's broadcasts and replays them into the page as they happen.

Model observers, event listeners, broadcastWhen(), broadcastOn(), broadcastAs(), broadcastWith(), and explicitly selected broadcast connections all run under Laravel's normal dispatcher. The plugin captures the final calls Laravel would make to its broadcaster.

ShouldBroadcast events are run inline: the queue connection is switched to sync while capturing, and restored afterward. Broadcast jobs handled later by a separate queue worker run in another process and stay outside this in-memory capture scope.

Do not wrap the application event under test in Event::fake(). Laravel cannot run observers or broadcast listeners for a suppressed event, so the session refuses to start and tells you why.

Broadcasts from the page's own requests

Pest Browser serves page requests in a separate Fiber. Replaying a broadcast from inside one would re-enter the browser while the page is still waiting for its response, so those broadcasts are held and replayed the next time the test reads the session:

Every realtime read flushes first, so assertions, channels(), status(), and capture() all pick them up. When a page assertion is the next thing that needs them, flush explicitly:

Assertions

Every assertion returns the session, so they chain. Failures name the event and list what actually happened:

A class string matches the wire name broadcastAs() would have produced, so both LotPriceChanged::class and 'lot.price.changed' work.

A closure narrows the match. It receives the CapturedBroadcast, since Laravel hands a broadcaster only the wire name and payload:

An array is the shorthand for the common case, matching the payload as a subset:

assertDeliveredInOrder() checks relative order, so unrelated broadcasts may arrive in between.

Channels

Channels accept Laravel's own vocabulary, an Eloquent model, a bare name, or the wire identifier you see in devtools:

A model resolves to the private channel Laravel's own conventions produce, which is what BroadcastsEvents and broadcast notifications use. That makes model broadcasting read directly:

assertSubscribed() waits for late subscriptions. The default timeout is Pest Browser's own assertion timeout, and can be overridden per call with assertSubscribed(..., timeoutMilliseconds: 10_000).

Encrypted private channels are delivered to directly rather than through pusher-js's decryption path, since the simulator has no shared secret to encrypt with. The page's listener runs exactly as it would for a decrypted frame.

Scoped capture

When you want the broadcasts from one specific action rather than the whole test:

$broadcasting->captured() returns the same object for everything the session has sent.

Each CapturedBroadcast exposes its wire channels, event, and payload, along with the selected Laravel connection and any socket exclusion supplied by toOthers(). Each Delivery links that capture to a normalized channel, its visibility, and an outcome:

• Delivered: the page registered the channel and its simulated connection was connected.
• Dropped: the page registered the channel but its simulated connection was not connected.
• NotSubscribed: this page did not register the channel. This is normal when an event broadcasts to several page types; replay continues to the remaining channels.
• Excluded: the broadcast excluded this page's socket through toOthers().

Emitting directly

broadcast() pushes a Laravel event, deriving channels, name, and payload from broadcastOn(), broadcastAs(), and broadcastWith():

emit() pushes a raw event at the wire boundary, for synthetic and malformed-payload tests:

Neither dispatches through Laravel, so neither evaluates broadcastWhen(). Let the application dispatch the event when its conditional broadcasting behavior is part of the test.

Anonymous events need nothing special. Broadcast::on(...)->as(...)->with(...)->send() is an ordinary ShouldBroadcast event, so capture records it like any other.

Presence channels

Membership is driven from the test, so here(), joining(), and leaving() in the page run against a roster you control:

The member array is the one a presence channel authorization callback returns, and its id becomes the member id unless you pass one. A bare name is treated as a presence channel here, so here('room.3', ...) also works.

Client events

whisper() pushes a client event into the page, as another client's whisper would:

Whispers the page itself sends are recorded, so a typing indicator can be asserted from the other side:

Each Whisper exposes its event, wire channel, payload, and whether the simulated connection was connected at the time.

Notifications

Broadcast notifications travel the same capture path, and assertions take the notifiable directly:

A notifiable resolves to its private model channel. Pass a channel explicitly when the notifiable overrides receivesBroadcastNotificationsOn(). As with Event::fake(), do not wrap the notification under test in Notification::fake(); the session refuses to start and tells you why.

Failed subscriptions

Channel authorization runs against your application's own endpoint and is out of the simulator's scope, but the client-side outcome of a refusal is not:

That fires Echo's error() callback with the same shape Pusher produces for a denied authorization.

Connection controls

The Echo/Pusher driver models Pusher's initialized, connecting, connected, unavailable, failed, and disconnected states. Every transition emits both Pusher's state_change event and the state-specific event, matching the real client's observable behavior. Echo normalizes Pusher's unavailable state to failed through Echo.connectionStatus().

Testing toOthers()

The simulated client's socket id is available, so a broadcast that excludes it can be exercised end to end:

Capture runs in the test's PHP process, so $socket is only set when the test sets it. Requests the browser itself makes carry their own X-Socket-ID and are handled in another process.

Defaults

Set once in tests/Pest.php:

What it tests

• Public, private, presence, and encrypted private subscriptions
• Exact event names and payloads
• Initialized, connecting, connected, unavailable, failed, and disconnected states
• Events delivered while connected
• Events dropped during an outage
• Application resync behavior after recovery
• Presence rosters and join/leave churn
• Client events in both directions
• Broadcast notifications
• The client-side outcome of a refused subscription

Boundary and limitations

This package is a realtime client simulator, not a WebSocket protocol emulator. It installs after navigation and deliberately centralizes version-sensitive access to Echo/Pusher's active client and channels.

It does not test:

• WebSocket handshakes or frames
• Reverb/Pusher server behavior
• TLS, proxy, or load-balancer configuration
• Channel authorization endpoints, only what the client does when one refuses

One session captures one application at a time. Starting a second session against the same Laravel application throws; call stopCapturing() on the first, or let it go out of scope. Multi-client scenarios that need two pages sharing one capture are not supported yet.

An event implementing ShouldDispatchAfterCommit is not dispatched until its transaction commits, which a transactional test never does. When nothing was captured and a transaction is open, the failure message says so.

Keep backend tests for channel authorization, event payload contracts, and broadcast failure tolerance. A future driver can use Playwright WebSocket routing when Pest Browser exposes that browser-context API publicly.

Custom drivers

Implement Pest\Realtime\Contracts\Driver and pass it to broadcasting(), or register it as the default:

Driver gained presenceScript(), membersScript(), clientEventsScript(), and subscriptionErrorScript() in 0.7.0, and BroadcastCapture gained drainPending() and hint(). Drivers and capture implementations written against 0.6 need those methods added.

License

Pest Plugin Realtime is open-source software licensed under the MIT license.