testing-best-practices

Write feature tests first that cover observable behavior and application contracts, using arrange-act-assert structure with one blank line between parts. Name each test as a behavior specification stating the result and its condition, and assert the complete result including database state and side effects.

Cover missing or invalid authentication, cross-tenant access, insufficient roles, route constraints, validation failures, and the valid case. Assert the application's actual behavior such as a 401 for API tokens or a redirect for browser endpoints, plus persisted state changes.

This guidance assumes Pest, which this project uses, but the rules apply to both frameworks. Follow the conventions already present in neighboring test files, since project conventions take precedence over general rules.

Use framework fakes for events, queues, mail, HTTP, time, and sleep instead of real implementations. Set BCRYPT_ROUNDS=4 in the test environment, use LazilyRefreshDatabase, and run pest with --parallel or --tia to reduce suite time.

Always prefer framework fakes for facades like events, queues, mail, and HTTP. Use a mock only for container-resolved contracts whose real implementation leaves the process or is nondeterministic, and use the real database rather than mocking the query builder.

Parallel failures indicate tests reading records created by other tests, depending on run order, or sharing files, cache keys, or queues. Each test must create its own data and use process-specific names for shared resources.