Controller Testing

When to Apply

Activate this skill when:

Creating or updating Pest feature tests for controllers.
Testing nested resource routes at any depth.
Building CRUD action test matrices (
```
create
```
,
```
destroy
```
,
```
edit
```
,
```
index
```
,
```
show
```
,
```
store
```
,
```
update
```
) for resource-style controllers.
Adding authorization, route-binding mismatch, validation dataset, and success-path assertions.
Testing either:
- web/session controllers (
```
get
```
  ,
```
post
```
  ,
```
patch
```
  ,
```
delete
```
  ), or
- API/JSON controllers (
```
getJson
```
  ,
```
postJson
```
  ,
```
patchJson
```
  ,
```
deleteJson
```
  ).

Use this skill together with

pest-testing

for generic Pest behavior.

Quick Start

bash

# Create file only when needed
php artisan make:test --pest Http/Controllers/<Name>ControllerTest --no-interaction

# Run only the affected file
php artisan test --compact tests/Feature/Http/Controllers/<Name>ControllerTest.php

# Optional focused rerun
php artisan test --compact --filter="<test name>"

Core Workflow

Inspect sibling controller tests first.
Decide mode first from sibling tests: web/session mode or API/JSON mode.
For resource-style controllers, use
```
describe('<action>')
```
blocks in this order:
```
create
```
,
```
destroy
```
,
```
edit
```
,
```
index
```
,
```
show
```
,
```
store
```
,
```
update
```
.
For non-resource controllers, test only exposed actions and keep the same assertion patterns.
For each action, include baseline auth + forbidden + binding mismatch coverage as applicable.
Use dataset-driven validation tests for
```
store
```
and
```
update
```
.
Assert success path with transport-specific assertions plus persistence checks.

References

Load only what you need:

```
references/modes/api-json.md
```
Transport-mode guide for API/JSON controller tests, including protected-endpoint and public-endpoint patterns, plus full
```
store
```
and
```
update
```
```
describe(...)
```
examples.
```
references/route-patterns.md
```
Use for full route naming examples and complete
```
route()
```
parameter maps for flat, one-level, two-level, three-level, and N-level nested resources.
```
references/actions/create.md
```
Full
```
describe('create')
```
examples for one-level and two-level nested resources.
```
references/actions/destroy.md
```
Full
```
describe('destroy')
```
examples for one-level and two-level nested resources.
```
references/actions/edit.md
```
Full
```
describe('edit')
```
examples for one-level and two-level nested resources.
```
references/actions/index.md
```
Full
```
describe('index')
```
examples for one-level and two-level nested resources.
```
references/actions/show.md
```
Full
```
describe('show')
```
examples for one-level, two-level, and three-level nested resources.
```
references/actions/store.md
```
Full
```
describe('store')
```
examples for one-level and two-level nested resources, including baseline
```
validates fields
```
dataset examples.
```
references/actions/update.md
```
Full
```
describe('update')
```
examples for one-level and two-level nested resources, including baseline
```
validates fields
```
dataset examples and optional stored-bound validation cases.
```
references/validation/store-validates-fields.md
```
Additional
```
store
```
validation dataset snippets to merge when request rules need more coverage.
```
references/validation/update-validates-fields.md
```
Additional
```
update
```
validation dataset snippets to merge when request rules need more coverage.
Prefer the focused validation references below first when a specific rule pattern matches.

references/validation/required-with-and-array.md

Focused

validates fields

snippets for

required_with

and

array

rules in

store

and

update

references/validation/scoped-exists-and-unique.md

Focused snippets for scope-aware

exists

and

unique

rules (including

ignore(...)

update

```
references/validation/prepare-for-validation.md
```
Focused snippets for
```
prepareForValidation()
```
side-effects and stored-value dependent validation cases.
```
references/validation/api-login-validation.md
```
Focused public API auth validation snippets (
```
email request
```
and
```
email login
```
) with JSON assertions.

Action references are web/session-first templates. For API/JSON controllers, use the same action structure and adapt assertions using

references/modes/api-json.md

plus sibling API tests.

Required Baseline Assertions

Shared:

Policy denial with valid bindings ->
```
assertForbidden()
```
.
Parent-child binding mismatches (especially with
```
scopeBindings
```
) ->
```
assertNotFound()
```
.
Decide
```
403
```
vs
```
404
```
by execution path:
- binding/scope mismatch resolves first ->
```
404
```
- binding is valid but authorization fails ->
```
403
```

Web/session mode:

```
requires authentication
```
-> redirect to login route.
Validation failures ->
```
assertRedirectBackWithErrors(...)
```
.
Page actions ->
```
assertOk()
```
+
```
assertInertia(...)
```
.
Mutation actions -> redirect + persistence assertions.
Toast/flash assertions are optional and app-specific:
- if your app has
```
assertToast(...)
```
  , use it
- otherwise use your app's existing flash assertion style

API/JSON mode:

Protected endpoints:

requires authentication

assertUnauthorized()

Public endpoints: do not add
```
requires authentication
```
by default.

Validation failures ->

assertUnprocessable()

assertJsonValidationErrors(...)

Success actions ->
```
assertOk()
```
/
```
assertCreated()
```
/
```
assertNoContent()
```
+ JSON assertions + persistence assertions.

Notes

One-level, two-level, and three-level examples are not limits; apply the same pattern to deeper nesting.
Auth examples use neutral
```
login()
```
placeholders; adapt to your project helper signature and ensure the authenticated user belongs to the related scope when needed.
For
```
destroy
```
, use model-appropriate persistence assertions:
- ```
assertSoftDeleted(...)
```
  when the model uses
```
SoftDeletes
```
  .
- ```
assertModelMissing(...)
```
  when it does not.
Use the app's existing identifier shape in assertions (
```
id
```
,
```
public_id
```
, slug, route key).

controller-testing

NPX Install

Tags

SKILL.md Content