Regenerate Boost guidelines and skills

Generated by boost:update for Boost 2.8, which replaces the pest-testing skill with testing-best-practices and adds infer-conventions. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017XYnWFt9pJEwvAmNFN38XD
2026-09-10 10:42:22 +02:00
parent 3638455167
commit 92b3b3de56
38 changed files with 1521 additions and 1001 deletions
@@ -0,0 +1,58 @@
+---
+name: testing-best-practices
+description: "Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax."
+license: MIT
+metadata:
+  author: laravel
+---
+
+# Testing Best Practices
+
+This skill provides rules for designing Laravel tests. Each rule file explains what to do and why. Use `search-docs` for Laravel and Pest API syntax.
+This project uses Pest. Follow the corresponding guidance in each rule.
+
+## Consistency First
+
+Read nearby tests before you choose syntax and organization.
+
+A pattern repeated throughout the project is a convention, and project conventions take precedence over this skill. Follow them and give new tests the same structure.
+
+These rules govern the tests you write now. An existing test that follows a project convention is not defective merely because it conflicts with this skill. Do not delete or rewrite it. If the convention has drawbacks, explain them and let the user decide.
+
+## What to Test
+
+Read this section before you write a test.
+
+- Test observable behavior and application contracts. A test must pass after an implementation change if the behavior stays the same.
+- Cover every changed decision and each applicable high-value failure mode. A decision is a branch, a validation, a calculation, or an authorization.
+- Exercise declarations through behavior instead of repeating their text.
+- Leave framework behavior to framework tests. Testing project configuration is not testing the framework. A constrained relationship, cast, scope, or validation rule belongs to this project.
+- Keep every test that can detect a distinct defect. When two tests detect the same defect, trim the higher-layer test to one case and report the duplication. Do not delete an existing test.
+- Write a feature test first. Write a unit test only for logic that does not use the framework.
+- Write a feature test for every behavior reachable through a request. Real-browser tests require `pestphp/pest-plugin-browser` and a browser download, neither of which this project installs. Mention the package only if the user asks for a real-browser test.
+- Judge an architecture test by the convention it protects, not by the rules above. An `arch()` test declares a rule for an entire directory, such as the parent class of every model, the classes that may use an enum, or the methods every factory declares. It intentionally checks declarations and fails when a new file breaks the convention.
+- Use the test tools that the project installs. Add a new test dependency, plugin, or browser only after the user asks for it.
+
+## How to Apply
+
+1. Read the code under test. Read the tests in the same directory. Identify every decision in the code.
+2. Select every applicable branch in the rule index. Read every selected rule file.
+3. Report each defect in the code before you write a test. Examples are a method with no body, a policy that no action calls, and a write action with no validation. Test the actual behavior. Report the defect to the user.
+4. Write the tests. Run the smallest set of tests that covers the change. The tests must pass.
+5. Check every applicable item in `rules/review.md` and every selected rule file. Resolve every mismatch before completion.
+
+## Rule Index
+
+Most changes need more than one rule file.
+
+| Subject | Rule File |
+| --- | --- |
+| Test framework features that may already do the work | [`rules/finding-features.md`](rules/finding-features.md) |
+| File layout, test names, and groups | [`rules/naming.md`](rules/naming.md) |
+| Arrange-act-assert and choosing the correct assertion | [`rules/assertions.md`](rules/assertions.md) |
+| Endpoint coverage, authentication, authorization, tenant isolation, validation, and browser tests | [`rules/endpoint-tests.md`](rules/endpoint-tests.md) |
+| Factories, test data ownership, and repeated input values | [`rules/test-data.md`](rules/test-data.md) |
+| Fakes, mocks, outbound HTTP, time, randomness, and databases | [`rules/isolation.md`](rules/isolation.md) |
+| Escaping, injection, cross-tenant access, and privilege checks | [`rules/security.md`](rules/security.md) |
+| Environment and CI settings for a slow suite | [`rules/performance.md`](rules/performance.md) |
+| Reviewing a test or suite | [`rules/review.md`](rules/review.md) |
@@ -0,0 +1,64 @@
+# Assertions
+
+## Arrange, Act, Assert
+
+Write each test in three parts: setup, one action, and assertions. Put one blank line between them so readers can identify each part without comments.
+
+Keep each test self-contained. Do not use values created by another test.
+
+## How to Find the Correct Assertion
+
+First identify the subject of the check, then find an assertion designed for it. A subject-specific assertion identifies the incorrect value when the test fails.
+
+1. Search Laravel's assertions for framework subjects such as responses, the database, sessions, models, queues, events, mail, and notifications.
+2. Fetch `https://pestphp.com/docs/expectations.md` for the expectations of Pest for a plain value, a type, a format, or a shape.
+3. Build the check by hand only if no assertion exists for the subject.
+4. Confirm the name in the documentation before you use it. Do not write an assertion that you did not confirm.
+
+Use the assertion in this table for each subject.
+
+| Subject | Assertion to use |
+| --- | --- |
+| A return value, the state of an object, or a transformation of a value | an `expect()` chain |
+| An HTTP status, JSON, a session, or Inertia | a Laravel response assertion |
+| The state in the database | a Laravel database assertion |
+| The existence of a model | `assertModelExists($model)` rather than `assertDatabaseHas('users', ['id' => $user->id])` |
+
+Use a PHPUnit assertion only if no Pest expectation and no Laravel assertion exists for the subject.
+
+Assert each fact once. Do not assert a 200 status before `assertSee`, because `assertSee` already shows that the page rendered.
+
+## Named Response Assertions
+
+Use a named response assertion, such as `assertNotFound()`, rather than `assertStatus(404)`. A failure then identifies the broken contract. Laravel provides named assertions for commonly tested status codes.
+
+Keep one `expect()` chain on one subject. Start a new chain when the subject changes, or when the chain is difficult to read.
+
+## Format Expectations
+
+Use Pest's format expectations rather than regular expressions because they provide clearer failure messages. Pest covers email addresses, URLs, UUIDs, IP addresses, and other common formats, and each expectation supports `not` for the negative case.
+
+## Assert a Known Value
+
+Write the expected value in the test, or calculate the expected value by a different method. Do not calculate the expected value with the logic of the implementation, because the test then passes when that logic is wrong.
+
+```php
+// The test calculates the value with the logic of the implementation...
+$expected = now()->subHours(24)->floorSeconds(30)->toJson();
+expect($from)->toBe($expected);
+
+// The test sets a fixed input and asserts a known value...
+travelTo('2025-01-01 00:00:00');
+expect($from)->toBe('2024-12-31T00:00:00.000000Z');
+```
+
+## Assert the Complete Result
+
+A status code is not the complete result of a write operation. Assert each of the following if the operation changes it:
+
+- The response or the return value.
+- The state in the database.
+- The jobs and the events that the operation dispatches.
+- The notifications and the mail that the operation sends.
+
+On the failure path, assert that the operation makes none of these changes. A test that asserts only `assertOk()` passes even when the application saves no record.
@@ -0,0 +1,47 @@
+# Endpoint Tests
+
+## How to Write the Test
+
+Fetch `https://laravel.com/framework/docs/http-tests` for the request helpers, the authentication helpers, and the response assertions. Confirm the name before you use it, and do not guess an assertion.
+
+Choose an assertion based on the subject of the check: the status, a header, a redirect, the JSON body, the session, a validation error, or the view. Laravel provides a named assertion for each subject that identifies the incorrect value.
+
+## Endpoint Coverage
+
+Write a test for each applicable case:
+
+- The request has missing or invalid authentication.
+- The request comes from a different tenant, team, or organization.
+- The user has an insufficient role or permission.
+- The request does not satisfy a route or scope constraint.
+- The request fails the validation.
+- The request is valid. Assert both the response and the persisted state.
+
+Assert the application's actual behavior rather than a generic status code. An API returns `401` for a missing or invalid token, while a browser endpoint redirects to the sign-in route.
+
+## Tenant Isolation
+
+Assert the status code returned for a cross-tenant request. Use `404` rather than `403` when one tenant must not learn that another tenant's record exists, because `403` confirms its existence.
+
+## Test Authorization at the Policy Level
+
+An HTTP test shows that the endpoint performs authorization. It cannot identify which mechanism refused the request because middleware, a policy, and a call to `abort()` can all return `403`.
+
+- Assert the complete matrix of the permissions against the policy or the gate. A failure then names the rule that is not correct.
+- Write one HTTP test for one refused role, which shows that the endpoint calls the authorization.
+- Use the helper of the project that asserts the ability and the arguments of the gate, if such a helper exists.
+
+## Testing Validation
+
+- Write one test for each validation rule when each failure represents a separate contract.
+- Write one test with an empty payload to assert several required fields together.
+- Assert the text of the message that the user gets. A message that is present but wrong is a defect.
+- Use a dataset for input values that need the same setup and the same assertions.
+
+Send an input value that is not valid through the application, and assert the error. Do not assert that an array of rules contains a string, because that assertion tests the declaration and not the behavior. Use such an assertion only for a rule that no request can reach, and write the reason in the test.
+
+### Which Layer Owns Which Case
+
+The rule-class test owns the matrix of values that pass and fail. The endpoint test proves that the endpoint applies the rule and that the user receives the message.
+
+When both tests contain the matrix, move it to the rule-class test and retain one case in the endpoint test. Never remove the last case, because the rule-class test still passes if the request omits the rule. The same division applies to policies, scopes, and other classes called by a request.
@@ -0,0 +1,37 @@
+# How to Find Test Framework Features
+
+Pest adds features faster than this skill can list them. Find an existing feature before implementing the behavior by hand.
+
+- Give `search-docs` the capability you need rather than the name of a function you remember. It returns features available in the installed version.
+- Fetch `https://pestphp.com/llms.txt` for the complete feature list and additions in each release.
+- If a search returns no results, tell the user that the installed version does not provide the feature. Do not write an API that you have not confirmed.
+
+Search for a feature in this table before you write the code by hand.
+
+| Work that you need | Term to search for |
+| --- | --- |
+| Run one test with many input values | datasets, bound datasets |
+| Assert over many values or over a collection | higher-order expectations |
+| Remove the same setup from each test in a file | hooks, higher-order tests |
+| Apply a convention to the complete codebase | architecture testing |
+| Measure if the suite finds a defect | mutation testing |
+| Find code with no types | type coverage |
+| Reduce the time of a slow suite | parallel, profiling |
+| Split the suite across CI jobs | sharding, `--update-shards` |
+| Run only the tests that a change affects | Test Impact Analysis, `--tia` |
+| Assert that a value has a known format | validation expectations |
+| Run one test while you debug | filtering, `--bail`, `--dirty` |
+
+## Built-in Laravel Assertion Methods
+
+Laravel provides assertions for each part of the framework. Fetch `https://laravel.com/framework/docs/testing` for the complete list, and search for an assertion before building a check by hand. Examples include `assertDatabaseHas()`, `assertModelExists()`, `assertSoftDeleted()`, response assertions such as `assertRedirectToRoute()` and `assertJsonPath()`, and fake assertions such as `Queue::assertPushed()` and `Notification::assertSentTo()`.
+
+A hand-built check fails with `false is not true`, which identifies nothing. A framework assertion names the incorrect table, value, or response, so the failure indicates what to fix.
+
+```php
+// The failure says that false is not true. Instead of this...
+expect(User::where('email', 'taylor@laravel.com')->exists())->toBeTrue();
+
+// Use this... the failure names the table and the attributes that it did not find...
+$this->assertDatabaseHas('users', ['email' => 'taylor@laravel.com']);
+```
@@ -0,0 +1,52 @@
+# Fakes, Mocks, and Determinism
+
+Tests that depend on actual time, randomness, sleeping, or network calls can fail for reasons unrelated to the code under test. Control all four.
+
+## How to Isolate a Dependency
+
+Fetch `https://laravel.com/framework/docs/mocking` for Laravel's fakes, facade doubles, and fake assertions. Confirm each name before using it.
+
+Identify the dependency, then choose the first applicable option. A framework fake preserves the real code path, while a mock replaces the dependency.
+
+1. Always use framework fakes for facades such as events, queues, mail, notifications, storage, the HTTP client, time, and sleep.
+2. Use a developer-defined fake implementation of a service if the application provides one.
+3. Use a mock for a container-resolved contract only when the real implementation leaves the process or is nondeterministic.
+4. Use the real implementation for everything else, including the database.
+
+## Framework Fakes
+
+- Create each fake inside the test that needs it. Do not create fakes in a file-level `beforeEach()`.
+- Pass class names to `Event::fake()` and `Queue::fake()` when you know which classes the code dispatches. A fake without class names can hide an unexpected dispatch.
+- Use a fake without class names only when the test asserts the complete result, including a call to `assertNothingPushed()`.
+- Write one assertion for each fake. The assertion states that the code dispatches the item, or that the code does not dispatch the item.
+- Assert the data of a job or of an event if that data is part of the behavior.
+- Use `Exceptions::fake()` to assert that the application reports the correct exception. Do not use `withoutExceptionHandling()`, because it changes the response under test.
+
+Create prerequisite factory records before calling `Event::fake()`. Factories use model events, such as a `creating` hook that generates a UUID, and a fake without class names suppresses those events and can produce an invalid model. Call the fake first only when a factory event is under test, and pass that event's class name.
+
+## Mocking
+
+Use `shouldReceive()` before the action to declare an expectation. Use `shouldHaveReceived()` after the action for a spy. Use `Mockery::on()` or `withArgs()` if an equality check cannot state the expected argument, such as a check of one field of a value object.
+
+Import the mock function before you use it: `use function Pest\Laravel\mock;`.
+
+## Outbound HTTP Testing
+
+Call `Http::preventStrayRequests()`. Any request without a matching fake then fails without reaching the network.
+
+Fake the exact endpoint used by each test. Do not call `Http::fake()` without an endpoint because it accepts unexpected requests and can hide defects.
+
+## Time and Randomness
+
+- Freeze the time or move the time in each test that depends on a date, a period, or a timestamp.
+- Use the framework helpers `freezeTime()`, `travelTo()`, `travel()`, and `travelBack()`. Do not call `Carbon::setTestNow()`.
+- Use `Str::createRandomStringsUsing()` to fix a generated string, if the test asserts an identifier or a slug.
+- Use `Sleep::fake()` instead of a real sleep, and assert the sleeps that the code requests.
+- Restore the time and the randomness after each test, if the suite does not restore them for every test.
+
+## Database
+
+- Run real queries against the real records in the test database. Do not mock the query builder, because the test then asserts the mock.
+- Assert the exact keys of `toArray()` if the shape of the serialized model is a contract. The test then fails when the model exposes a new attribute.
+- Test application behavior caused by the schema, such as deleting dependent records through a cascade. Do not test the database engine's cascade implementation.
+- Use `LazilyRefreshDatabase` instead of `RefreshDatabase`. A test that does not use the database then does not run the migrations.
@@ -0,0 +1,45 @@
+# Naming and Structure
+
+## File Layout
+
+- Name each test file `{ClassName}Test.php`.
+- Place each test file at the same relative path as the class under test. The class `app/Actions/DeleteTeam.php` gets the test `tests/Unit/Actions/DeleteTeamTest.php`.
+- Follow the project's convention for fixture files. If none exists, put fixtures in `tests/Fixtures/` and load them by path.
+- Move large literal values out of the test body and into fixture files.
+
+## Test Function
+
+Use the test function used by other files in the same directory. If no neighboring test files exist:
+
+- Use `it()` for the behavior of the code, and write the name as a verb phrase.
+- Use `test()` for a declarative fact, such as a grant in a policy, the labels of an enum, or the shape of a serialized model.
+
+Use one Pest declaration style in each file. Use either `it()` or `test()` consistently.
+
+## Naming Tests
+
+The name of a test is a specification. State the user-visible result and the condition that causes it.
+
+- Name the behavior, and not the method under test. The file name already gives the class.
+- Give the exact status code in the name of a test for an API error.
+- Do not write `Given`, `When`, or `Then` in the name.
+
+```php
+it('returns 401 when no token is provided', function () { ... });
+it('does not include deployments from deleted environments', function () { ... });
+it('falls back to the default region when none is configured', function () { ... });
+```
+
+Use a verb that describes a result, such as `returns`, `renders`, `creates`, `dispatches`, `rejects`, `forbids`, `falls back`, or `does not`.
+
+Do not write `it('works correctly')` or `it('returns data')`, because neither specifies a meaningful result. Do not write `it('handleMethod creates record')`, because it names a method rather than behavior.
+
+## Grouping
+
+Use `describe()` if one file covers separate actions in a lifecycle. An example is a controller with the actions `index`, `show`, `store`, `update`, and `destroy`.
+
+Do not use `describe()` in these cases:
+
+- The file covers one action or one flow.
+- The tests are different only in the input value. Use a dataset instead.
+- The group adds a level but does not make the file easier to read.
@@ -0,0 +1,58 @@
+# Test Suite Performance
+
+These settings apply to the project and CI, not to individual tests. Read `rules/isolation.md` for choices within a test.
+
+Fetch `https://pestphp.com/docs/optimizing-tests` for Pest options that make test runs faster.
+Verify each flag in the documentation before adding it to CI.
+
+Measure before changing a setting. Find the slow test first, and apply a project-wide setting only after identifying the costly work.
+
+## Test Environment
+
+- Set `BCRYPT_ROUNDS=4` in `.env.testing` or in `phpunit.xml`. The default value is 12, and the hash then takes most of the time of each test that signs a user in.
+- Disable XDebug. Disable pcov also, unless the run needs the coverage.
+- Disable packages that perform work on every request in the test environment. Examples are Pulse, Telescope, and Nightwatch.
+- Use the `WithCachedConfig` and `WithCachedRoutes` traits, so the run does not parse the configuration and the routes for every test.
+- Call `withoutVite()`, or `withoutMix()`, so the framework does not resolve a built asset.
+
+## Global Fakes
+
+Put these three calls in the base `Pest.php` of the project:
+
+- `Http::preventStrayRequests()`, because one request that reaches the network can slow the suite. This catches requests made through Laravel's HTTP client. Check direct Guzzle and cURL usage separately.
+- `Sleep::fake(syncWithCarbon: true)`, so a retry and a backoff do not sleep.
+- `Exceptions::fake()`, so the suite does not report an exception to an external service.
+
+## How to Run the Suite in Parallel
+
+Run `vendor/bin/pest --parallel` to spread tests across the machine's CPU cores. Add `--processes=N` if the default count is unsuitable for the machine or CI.
+
+A parallel run gives each process a separate database. Tests must meet these conditions; a test that fails only in parallel breaks one of them:
+
+- The test creates each record that it reads. It does not read a record that another test creates.
+- The test does not depend on the order of the run.
+- The test does not share a file, a cache key, or a queue with another test. Give each process a separate name for such a resource.
+
+## How to Run Fewer Tests
+
+Run `vendor/bin/pest --parallel --tia` to run only the tests that the recent changes affect. Pest replays the cached result of each other test.
+
+Pest replays cached results rather than skipping unaffected tests. The cache includes each produced value and the covered lines and branches. Pest finds affected Laravel, Symfony, Livewire, and Inertia tests without configuration.
+
+## How to Split Tests Across CI
+
+Run `vendor/bin/pest --update-shards` to measure the time of each test. Run `vendor/bin/pest --shard=1/4` in each CI job, and change the first number for each job.
+
+Commit `tests/.pest/shards.json` so each CI job gets the same shard and the shards remain balanced by runtime rather than test count.
+
+## How to Find a Slow Test
+
+Run `vendor/bin/pest --profile` to list the slowest tests. Start with the ten slowest tests, because the same cause often applies to the complete suite.
+
+If the cause of a slow test is unclear, add an event listener or temporary log entry to identify its work.
+
+## Common Errors
+
+- The run loads XDebug for a test that does not need it.
+- `BCRYPT_ROUNDS` keeps the default value, because the project has no `.env.testing`.
+- The code under test calls the real `sleep()`, and `Sleep::fake()` then does not help.
@@ -0,0 +1,44 @@
+# Reviewing Tests
+
+Check every item in this file. A passing test may still provide no value. For each test, identify the defect it would catch.
+
+Report each finding. Do not delete or rewrite a test without the user's approval. When an issue appears throughout the suite as a convention, report the pattern once rather than every affected file.
+
+## Test Value
+
+Apply this section to behavioral tests. An architecture test states a convention for a directory, so these items do not apply to it.
+
+- [ ] Each test covers observable behavior or an application contract, and passes after a change to the implementation that keeps the behavior.
+- [ ] Each tested declaration is exercised through behavior, and no test asserts the behavior of the framework. A test of what this project configures, such as a relation with a constraint, a cast, or a scope, belongs to this project.
+- [ ] Each test detects a distinct defect that no other test covers. A duplicate shrinks at the higher layer to the one case that proves the wiring.
+- [ ] Every changed decision and each applicable high-value failure mode has coverage.
+
+## Names and Structure
+
+- [ ] Each file has the name `{ClassName}Test.php` and the relative path of the class under test.
+- [ ] Each name states a result, the condition that causes it, and the status code for an API error.
+- [ ] Each file uses one declaration style consistently, and each `describe()` group holds separate behavior.
+
+## Coverage
+
+- [ ] HTTP tests cover authentication, authorization, role, scope, and validation when applicable.
+- [ ] A request for a record of a different tenant gets a status code that does not confirm that the record exists.
+- [ ] The complete permission matrix belongs in policy tests, not controller tests.
+- [ ] Each validation rule has one test that asserts the user-visible message. When a unit test owns a matrix, reduce duplicate higher-level coverage to one case rather than deleting it.
+- [ ] Rendered user input and each dynamic part of a query have a security test.
+
+## Data and Determinism
+
+- [ ] Each test creates its mutable records directly or through a helper that it calls, and every created record arranges the behavior or supports an assertion.
+- [ ] Each `beforeEach()` holds configuration only.
+- [ ] Each factory state and each relationship gives the meaning of the data.
+- [ ] Each call to `make()` is in a test that does not need the database.
+- [ ] Time, randomness, sleep, and outbound HTTP are controlled.
+- [ ] Each test passes alone, and passes in the complete suite in any order.
+
+## Assertions
+
+- [ ] Each expected value is a known value, and the test does not calculate the value with the logic of the implementation.
+- [ ] Each test of a write operation asserts the response, the state in the database, and the side effects.
+- [ ] Each fake has one assertion, and gives the class names unless the test asserts the complete result.
+- [ ] Each `expect()` chain stays on one subject.
@@ -0,0 +1,27 @@
+# Security Tests
+
+Test each security boundary where user input affects authorization, rendered output, or query construction. A defect at such a boundary can be difficult to detect because the feature may continue to work.
+
+Write a test for each of these cases:
+
+- **Cross-tenant access.** Request a record of a different tenant, team, or organization. Read `rules/endpoint-tests.md` for why the response should possibly be `404` rather than `403`.
+- **Each unprivileged role.** Use a dataset over the roles that the endpoint must refuse.
+- **Escaping user-provided content.** Test escaping in HTML and mail. Include names and every free-text field a template renders. Assert that dangerous characters are escaped and the raw value is absent. Do not assert an exact entity for a quote, because Markdown and mail CSS inliners may decode it.
+- **Injection into dynamic query components.** Examples include sort columns, filter fields, and sort directions.
+- **An unexpected key** in a payload or configuration array. A merge that accepts every key can set an attribute the user must not control.
+
+```php
+it('escapes dangerous content in the notification', function () {
+    $organization = Organization::factory()->make([
+        'name' => "O'Reilly <script>alert('xss')</script>",
+    ]);
+
+    $content = (new QuotaApproaching($organization, 80))->toMail()->render();
+
+    expect($content)
+        ->toContain('&lt;script&gt;')
+        ->not->toContain("<script>alert('xss')</script>");
+});
+```
+
+Laravel provides defenses against mass assignment, unauthorized access, and unescaped output. Test that the application applies the appropriate defense to each attribute, route, and template.
@@ -0,0 +1,56 @@
+# Factories and Test Data
+
+## Each Test Makes Its Own Data
+
+Create mutable records inside the test that uses them. This keeps setup visible and lets each test select its factory state.
+
+Use `beforeEach()` only for configuration that applies to every test in the file. Do not create records in it.
+
+## Record Construction
+
+- Use `create()` if the test needs the record in the database.
+- Use `make()` only if the test does not need the database. Examples include rendering a notification and testing a value object's behavior.
+- Use a named factory state instead of a raw attribute. `User::factory()->unverified()->create()` gives the state meaning; `create(['email_verified_at' => null])` gives only its value.
+- Use `for()` or the relationship helper of the project to declare the owner of a record.
+- Use `recycle()` if several records must share one parent record.
+- Use `sequence()` if several records need different attributes.
+
+```php
+$organization = Organization::factory()->onPlan(BillingPlan::PRO)->create();
+
+$environment = Environment::factory()->recycle($organization)->create();
+
+$organizations = Organization::factory()
+    ->count(3)
+    ->sequence(
+        ['created_at' => now()->setSeconds(30)],
+        ['created_at' => now()->setSeconds(1)],
+    )
+    ->create();
+```
+
+Create only the records required to arrange the behavior or support an assertion.
+
+## Datasets
+
+Use a dataset when the setup, test body, and assertions remain the same across input values.
+
+```php
+it('forbids roles other than admin', function (Role $role) {
+    actingAs(User::factory()->hasOrganization($role)->create())
+        ->post('/settings')
+        ->assertForbidden();
+})->with(collect(Role::cases())->reject(fn (Role $role) => $role === Role::ADMIN));
+```
+
+Use parameterized tests for:
+
+- enum cases
+- roles and plans
+- boundary values
+- input values that are invalid in the same way
+- input and output value pairs
+
+Write separate tests if the cases need a different setup, a different behavior, or different assertions. One test function with a branch in the body is two tests in one function.
+
+Give each dataset case a name that states the difference. A failure then identifies the case without requiring you to count positions.