developing-with-turbo-tests - SKILL.md Agent Skill

name: developing-with-turbo-tests description: >- Tests Turbo Laravel features in PHPUnit or Pest. Activates when using the InteractsWithTurbo trait; simulating requests with $this->turbo(), $this->fromTurboFrame(), or $this->hotwireNative(); asserting responses with assertTurboStream(), assertNotTurboStream(), assertRedirectRecede(), assertRedirectResume(), or assertRedirectRefresh(); faking broadcasts with TurboStream::fake(), assertBroadcasted(), assertNothingWasBroadcasted(), or assertBroadcastedTimes(); writing feature tests for Turbo Stream responses; or when the user mentions testing Turbo, testing broadcasts, or Turbo test assertions.

Testing Turbo Laravel

Turbo Laravel provides the InteractsWithTurbo trait and several test response macros for asserting Turbo-specific behavior in feature tests.

Setup

Add the InteractsWithTurbo trait to your test class (or base TestCase):

@verbatim

use HotwiredLaravel\TurboLaravel\Testing\InteractsWithTurbo;

class PostTest extends TestCase { use InteractsWithTurbo; }

@endverbatim

Note: The turbo-laravel.queue config is automatically set to false during testing so broadcasts are processed synchronously.

Simulating Turbo Requests

Turbo Stream Visits

Use $this->turbo() to simulate a request that accepts Turbo Stream responses (sets the appropriate Accept header):

@verbatim

$this->turbo()->post(route('posts.store'), ['title' => 'Test']) ->assertTurboStream();

$this->turbo()->put(route('posts.update', $post), ['title' => 'Updated']) ->assertTurboStream();

$this->turbo()->delete(route('posts.destroy', $post)) ->assertTurboStream();

@endverbatim

Turbo Frame Requests

Use $this->fromTurboFrame() to simulate a request from a specific Turbo Frame (sets the Turbo-Frame header):

@verbatim

$this->fromTurboFrame(dom_id($post)) ->get(route('posts.edit', $post)) ->assertSee('', false);

$this->fromTurboFrame(dom_id($post, 'create_comment')) ->post(route('posts.comments.store', $post), ['content' => 'Hello']) ->assertOk();

@endverbatim

Hotwire Native Requests

Use $this->hotwireNative() to simulate a request from a Hotwire Native mobile client:

@verbatim

$this->hotwireNative()->post(route('comments.store'), ['content' => 'Hello']) ->assertRedirectRecede(['status' => __('Comment created.')]);

@endverbatim

Asserting Turbo Stream Responses

`assertTurboStream()`

Assert the response is a Turbo Stream. Optionally pass a callback to inspect individual streams:

@verbatim

// Simple assertion that the response is a Turbo Stream $this->turbo()->post(route('posts.store'), ['title' => 'Test']) ->assertTurboStream();

// With callback for detailed assertions $this->turbo()->post(route('posts.store'), ['title' => 'Test']) ->assertTurboStream(fn ($streams) => $streams ->has(2) // Assert exactly 2 stream elements ->hasTurboStream(fn ($s) => $s ->where('target', 'posts') ->where('action', 'append') ->see('Test') ) ->hasTurboStream(fn ($s) => $s ->where('target', 'post_count') ->where('action', 'update') ) );

@endverbatim

`assertNotTurboStream()`

Assert the response is NOT a Turbo Stream:

@verbatim

$this->get(route('posts.index')) ->assertNotTurboStream();

@endverbatim

Asserting Hotwire Native Redirects

For Hotwire Native clients, assert specific redirect path behaviors with optional flash data:

@verbatim

// Assert a "recede" redirect (go back in the native navigation stack) $this->hotwireNative()->post(route('comments.store'), ['content' => 'Hello']) ->assertRedirectRecede(['status' => __('Comment created.')]);

// Assert a "resume" redirect (stay on the current screen) $this->hotwireNative()->put(route('settings.update'), ['name' => 'New']) ->assertRedirectResume(['status' => __('Settings updated.')]);

// Assert a "refresh" redirect (reload the current screen) $this->hotwireNative()->post(route('posts.store'), ['title' => 'Test']) ->assertRedirectRefresh(['status' => __('Post created.')]);

@endverbatim

Testing Broadcasts

Faking Broadcasts

Use TurboStream::fake() to capture broadcasts without actually sending them:

@verbatim

use HotwiredLaravel\TurboLaravel\Facades\TurboStream;

public function test_creating_post_broadcasts() { TurboStream::fake();

$post = Post::create(['title' => 'Test']);

TurboStream::assertBroadcasted(fn ($broadcast) =>
    $broadcast->target === 'posts' && $broadcast->action === 'append'
);

}

@endverbatim

`assertNothingWasBroadcasted()`

Assert no broadcasts were sent:

@verbatim

TurboStream::fake();

// ... perform actions that should NOT broadcast ...

TurboStream::assertNothingWasBroadcasted();

@endverbatim

`assertBroadcastedTimes()`

Assert a broadcast matching a condition was sent a specific number of times:

@verbatim

TurboStream::fake();

Post::create(['title' => 'First']); Post::create(['title' => 'Second']);

TurboStream::assertBroadcastedTimes( fn ($broadcast) => $broadcast->action === 'append', times: 2, );

@endverbatim