Pest Plugin Route Testing

https://github.com/spatie/pest-plugin-route-testing
Admin
Pest Plugin Route Testing is a Laravel testing plugin that makes it easy to test all GET routes in...
Tokens:4,003
Snippets:48
Trust Score:10
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Dev Dependencies

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/CONTRIBUTING.md

Run this command after cloning your fork to install necessary development dependencies.

```bash
composer install
```

--------------------------------

### Execute Custom Code Before Test

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

Use the `setUp` method to run custom code, such as logging in a user or binding models, before executing route tests. This allows for pre-test setup.

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all admin routes')
    ->setUp(function ()
    {
        $user = User::factory()->create();
        
        $this->actingAs($user);
        
        // optionally, you could also bind the model
        $this->bind('user', $user);
    })
    ->include('admin*')
    ->assertSuccessful();
```

--------------------------------

### Execute code before each route test with `setUp()`

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Use `setUp()` to run code before each route request, useful for authentication or seeding. It accepts a closure that runs within the Pest `beforeEach` context, allowing access to `$this` for actions like `actingAs()` or `bind()`.

```php
use function Spatie\RouteTesting\routeTesting;
use App\Models\User;

// Authenticate as an admin before testing admin routes
routeTesting('all admin routes')
    ->setUp(function () {
        $user = User::factory()->admin()->create();
        $this->actingAs($user);
    })
    ->include('admin*')
    ->assertSuccessful();

// Seed data AND bind the model in setUp
routeTesting('user profile routes')
    ->setUp(function () {
        $user = User::factory()->create();
        $this->actingAs($user);
        $this->bind('user', $user); // makes user/{user} resolvable
    })
    ->include('user/*')
    ->assertSuccessful();
```

--------------------------------

### routeTesting() — Entry point

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Creates a Pest test that iterates over all (or a filtered subset of) GET routes and runs the given assertions against each one. The `$description` string becomes the Pest test name.

```APIDOC
## routeTesting() — Entry point

Creates a Pest test that iterates over all (or a filtered subset of) GET routes and runs the given assertions against each one. The `$description` string becomes the Pest test name.

### Usage

```php
use function Spatie\RouteTesting\routeTesting;

// Test every GET route and expect HTTP 200
routeTesting('all GET routes return 200')
    ->assertSuccessful();

// Test every GET route and allow any 2xx or 3xx response
routeTesting('all GET routes are reachable')
    ->assertOk();
```
```

--------------------------------

### Test all GET routes for HTTP 200

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Use `routeTesting()` to test all GET routes and assert that they return a successful HTTP 200 status code. Ensure the `Spatie\RouteTesting\routeTesting` function is imported.

```php
use function Spatie\RouteTesting\routeTesting;

// Test every GET route and expect HTTP 200
routeTesting('all GET routes return 200')
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

// Test every GET route and allow any 2xx or 3xx response
routeTesting('all GET routes are reachable')
    ->assertOk();
```

--------------------------------

### Test Redirect Assertions

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

This example demonstrates how to test for redirects using the `assertRedirect` method. It includes specific patterns for both the original and target routes.

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('redirect')
    ->include('old-section/*')
    ->assertRedirect('new-section/*');
```

--------------------------------

### Test All GET Routes

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

Use this to test all GET routes in your application and assert they return a 200 status code. Any assertion from Laravel's TestResponse class can be used.

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all GET routes')
   ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all routes')
    ->assertSuccessful();
```

--------------------------------

### Run All Tests

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/CONTRIBUTING.md

Execute this command to run the complete test suite for the project.

```bash
composer test
```

--------------------------------

### Test Specific Routes with Include

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

Test specific routes by using the `include` method with wildcard support. Multiple arguments can be passed to `include` to match several patterns.

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all blog routes')
    ->include('blog*')
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all blog routes')
    ->include('blog*')
    ->assertRedirect('new-section/*');
```

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all blog routes')
    ->include('blog*', 'post*')
    ->assertSuccessful();
```

--------------------------------

### Run Unit Tests

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/CONTRIBUTING.md

Execute this command to run only the unit tests for the project.

```bash
composer test:unit
```

--------------------------------

### Check Types

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/CONTRIBUTING.md

Run this command to perform type checking on the codebase.

```bash
composer test:types
```

--------------------------------

### Test Routes with Model Bindings

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

For routes with model bindings, you can provide the model instance using the `bind` method. This ensures that routes requiring specific models are tested correctly.

```php
use function Spatie\RouteTesting\routeTesting;
use App\Models\User;

routeTesting('all blog routes')
    ->bind('user', User::factory()->create())
    ->assertSuccessful();
```

--------------------------------

### Provide route model bindings using bind()

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Use the `bind()` method to supply values for named route parameters, allowing routes with parameters like `user/{user}` to be tested. The second argument is a closure returning the bound value.

```php
use function Spatie\RouteTesting\routeTesting;
use App\Models\User;

// Provide a user model so user/{user} routes are not skipped
routeTesting('all routes with user binding')
    ->bind('user', fn () => User::factory()->create())
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

// Multiple bindings for nested resource routes: posts/{post}/comments/{comment}
routeTesting('post and comment routes')
    ->bind('post', fn () => Post::factory()->create())
    ->bind('comment', fn () => Comment::factory()->create())
    ->assertSuccessful();
```

--------------------------------

### Lint Code

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/CONTRIBUTING.md

Execute this command to ensure your code adheres to the project's coding style.

```bash
composer lint
```

--------------------------------

### Filter routes by URI pattern using include()

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Use the `include()` method to restrict tests to routes matching specific URI patterns. Supports `*` wildcards. Multiple patterns can be provided.

```php
use function Spatie\RouteTesting\routeTesting;

// Only routes starting with "blog"
routeTesting('all blog routes')
    ->include('blog*')
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

// Multiple explicit patterns
routeTesting('blog and post routes')
    ->include('blog*', 'post*')
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

// Exact match plus wildcard
routeTesting('home and all admin sub-routes')
    ->include('home', 'admin/*')
    ->assertSuccessful();
```

--------------------------------

### ->bind() — Provide route model bindings

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Supplies a value for a named route parameter so that routes like `user/{user}` are tested instead of skipped. The second argument is a closure whose return value is bound to the parameter name.

```APIDOC
## ->bind() — Provide route model bindings

Supplies a value for a named route parameter so that routes like `user/{user}` are tested instead of skipped. The second argument is a closure whose return value is bound to the parameter name.

### Usage

```php
use function Spatie\RouteTesting\routeTesting;
use App\Models\User;

// Provide a user model so user/{user} routes are not skipped
routeTesting('all routes with user binding')
    ->bind('user', fn () => User::factory()->create())
    ->assertSuccessful();

// Multiple bindings for nested resource routes: posts/{post}/comments/{comment}
routeTesting('post and comment routes')
    ->bind('post', fn () => Post::factory()->create())
    ->bind('comment', fn () => Comment::factory()->create())
    ->assertSuccessful();
```
```

--------------------------------

### Ignore Routes with Missing Bindings

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

Skip tests for routes that have missing model bindings. This is useful when you don't want to see skipped tests in your output.

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all blog routes')
    ->ignoreRoutesWithMissingBindings()
    ->assertSuccessful();
```

--------------------------------

### Skip unbound routes with ignoreRoutesWithMissingBindings()

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Use `ignoreRoutesWithMissingBindings()` to silently skip routes with unresolved URI parameters from the test dataset. This prevents them from appearing as failures or skipped tests.

```php
use function Spatie\RouteTesting\routeTesting;

// Only run routes that require no model binding (or whose bindings are already provided)
routeTesting('simple routes only')
    ->ignoreRoutesWithMissingBindings()
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

// Combine with include to narrow the scope further
routeTesting('bindingless blog routes')
    ->include('blog*')
    ->ignoreRoutesWithMissingBindings()
    ->assertSuccessful();
```

--------------------------------

### ->include() — Filter routes by URI pattern

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Restricts the test dataset to routes whose URI matches at least one of the provided patterns. Supports `*` wildcards via Laravel's `Str::is()`.

```APIDOC
## ->include() — Filter routes by URI pattern

Restricts the test dataset to routes whose URI matches at least one of the provided patterns. Supports `*` wildcards via Laravel's `Str::is()`.

### Usage

```php
use function Spatie\RouteTesting\routeTesting;

// Only routes starting with "blog"
routeTesting('all blog routes')
    ->include('blog*')
    ->assertSuccessful();

// Multiple explicit patterns
routeTesting('blog and post routes')
    ->include('blog*', 'post*')
    ->assertSuccessful();

// Exact match plus wildcard
routeTesting('home and all admin sub-routes')
    ->include('home', 'admin/*')
    ->assertSuccessful();
```
```

--------------------------------

### Exclude Routes from Testing

Source: https://github.com/spatie/pest-plugin-route-testing/blob/main/README.md

Use the `exclude` method to omit specific routes from the test run. This is useful for ignoring routes that do not need to be tested or that might cause issues.

```php
use function Spatie\RouteTesting\routeTesting;

routeTesting('all blog routes')
    ->exclude('admin*')
    ->assertSuccessful();
```

--------------------------------

### Exclude routes by URI pattern using exclude()

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Use the `exclude()` method to remove routes matching specific URI patterns from the test dataset. The plugin excludes several patterns by default.

```php
use function Spatie\RouteTesting\routeTesting;

// Skip the admin section entirely
routeTesting('all public routes')
    ->exclude('admin*')
    ->assertSuccessful();
```

```php
use function Spatie\RouteTesting\routeTesting;

// Exclude multiple patterns
routeTesting('non-auth routes')
    ->exclude('login', 'register', 'password/*')
    ->assertSuccessful();
```

--------------------------------

### ->exclude() — Exclude routes by URI pattern

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Removes routes whose URI matches any of the provided patterns from the test dataset. The plugin already pre-excludes `_ignition`, `_debugbar*`, `horizon*`, `pulse*`, and `sanctum*` by default.

```APIDOC
## ->exclude() — Exclude routes by URI pattern

Removes routes whose URI matches any of the provided patterns from the test dataset. The plugin already pre-excludes `_ignition`, `_debugbar*`, `horizon*`, `pulse*`, and `sanctum*` by default.

### Usage

```php
use function Spatie\RouteTesting\routeTesting;

// Skip the admin section entirely
routeTesting('all public routes')
    ->exclude('admin*')
    ->assertSuccessful();

// Exclude multiple patterns
routeTesting('non-auth routes')
    ->exclude('login', 'register', 'password/*')
    ->assertSuccessful();
```
```

--------------------------------

### Chain `TestResponse` assertions onto `routeTesting()`

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Any assertion available on Laravel's `TestResponse` class can be chained directly onto a `routeTesting()` call. This allows for comprehensive testing of route responses, including status codes, redirects, and snapshot comparisons.

```php
use function Spatie\RouteTesting\routeTesting;

// Assert all old-section routes redirect somewhere under new-section
routeTesting('old section redirects')
    ->include('old-section/*')
    ->assertRedirect();

// Assert the maintenance page returns 503
routeTesting('maintenance routes')
    ->include('maintenance')
    ->assertStatus(503);

// Assert certain routes are behind auth (expect 403 when not logged in)
routeTesting('protected routes are forbidden when unauthenticated')
    ->include('dashboard*', 'settings*')
    ->assertForbidden();

// Snapshot testing (requires a snapshot driver)
routeTesting('marketing pages snapshot')
    ->include('about', 'pricing', 'contact')
    ->toMatchSnapshot();
```

--------------------------------

### ->ignoreRoutesWithMissingBindings() — Silently skip unbound routes

Source: https://context7.com/spatie/pest-plugin-route-testing/llms.txt

Removes any route that has unresolved URI parameters from the dataset entirely, so they appear neither as failures nor as skipped tests in the output.

```APIDOC
## ->ignoreRoutesWithMissingBindings() — Silently skip unbound routes

Removes any route that has unresolved URI parameters from the dataset entirely, so they appear neither as failures nor as skipped tests in the output.

### Usage

```php
use function Spatie\RouteTesting\routeTesting;

// Only run routes that require no model binding (or whose bindings are already provided)
routeTesting('simple routes only')
    ->ignoreRoutesWithMissingBindings()
    ->assertSuccessful();

// Combine with include to narrow the scope further
routeTesting('bindingless blog routes')
    ->include('blog*')
    ->ignoreRoutesWithMissingBindings()
    ->assertSuccessful();
```
```
Tokens:
Raw