testing-best-practices
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.
git clone --depth 1 https://github.com/relaticle/relaticle /tmp/testing-best-practices && cp -r /tmp/testing-best-practices/.claude/skills/testing-best-practices ~/.claude/skills/testing-best-practicesSKILL.md
# 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. Use the project convention for each item that follows: - the use of `it()` or `test()` - the construction of a factory - the setup of the authentication - the layout of the files ## 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 browser test only for behavior in JavaScript that a feature test cannot reach. Put a browser test in `tests/Browser`, and call `assertNoJavaScriptErrors()` in it. - 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 | | --- | --- | | A feature of the test framework that can already do the work | [`rules/finding-features.md`](rules/finding-features.md) | | The layout of the files, the names of the tests, and the groups | [`rules/naming.md`](rules/naming.md) | | Arrange-act-assert, and the correct assertion for each subject | [`rules/assertions.md`](rules/assertions.md) | | The coverage of an endpoint, the authentication, the authorization, the isolation of a tenant, the validation, and the tests in a browser | [`rules/endpoint-tests.md`](rules/endpoint-tests.md) | | The factories, the owner of the test data, and the repeated input values | [`rules/test-data.md`](rules/test-data.md) | | The fakes, the mocks, the outbound HTTP, the time, the randomness, and the database | [`rules/isolation.md`](rules/isolation.md) | | The escaping, the injection, the access across tenants, and the checks of privilege | [`rules/security.md`](rules/security.md) | | The settings of the environment and of the CI for a slow suite | [`rules/performance.md`](rules/performance.md) | | The review of a test or of a suite | [`rules/review.md`](rules/review.md) |
Use whenever driving agent-browser against the local Relaticle app (relaticle.test and its panels) for testing, QA, business review, or UI automation. Covers Filament v5 + Livewire v4 quirks specific to this codebase: panel URL derivation (domain-routed vs path-routed, never assumed), login flows for the app and sysadmin panels, seeded credentials, Select/date-picker interaction, the $wire.mountAction gold pattern, tenant switching, Reverb/queue hazards, and session isolation. Every hard fact here is a DATED CACHED HINT. When one fails, re-derive from the running app and update this file (self-heal). Not for other sites or generic browser automation.
TRIGGER when working with ai-sdk which is Laravel official first-party AI SDK. Activate when building, editing AI agents, chatbots, text generation, image generation, audio/TTS, transcription/STT, embeddings, RAG, vector stores, reranking, structured output, streaming, conversation memory, tools, queueing, broadcasting, and provider failover across OpenAI, Anthropic, Gemini, Azure, Groq, xAI, DeepSeek, Mistral, Ollama, ElevenLabs, Cohere, Jina, and VoyageAI. Invoke when the user references ai-sdk, the `Laravel\Ai\` namespace, or this project's AI features — not for other AI packages used directly.
Use when the user asks to business-review their work (local mode default, via 'business-review' or 'review my branch'), a Relaticle pull request ('--pr <N>' or a bare PR number), or a described change (--describe). v3 is a panel-of-QAs engine. It resolves the live environment first (URLs/creds/queue/Redis/Reverb are DISCOVERED from the running app, never assumed), runs a browser-capability preflight, auto-tiers by blast radius, synthesizes journeys from the diff plus Relaticle CRM priors, walks them happy AND sad through the real browser, sweeps the regression ledger, adversarially cold-reproduces every bug, and emits a substance-gated verdict (ai-approved / ai-rejected / ai-needs-human, or blocked on a degraded channel). Browser-truth only: never tinker or hit the DB to fix or fake a result. On request ('fix all issues', --fix) enters fix mode: fix → re-verify each finding against its original repro → re-gate. Publishing to the PR is opt-in and hard-disabled on a degraded run. Does NOT do code/security/scope review; for that use /code-review, /review, /deep-review.
Handles Laravel Cashier Stripe integration including subscriptions, webhooks, Stripe Checkout, invoices, charges, refunds, trials, coupons, metered billing, and payment failure handling. Triggered when a user mentions Cashier, Billable, IncompletePayment, stripe_id, newSubscription, Stripe subscriptions, or billing. Also applies when setting up webhooks, handling SCA/3DS payment failures, testing with Stripe test cards, or troubleshooting incomplete subscriptions, CSRF webhook errors, or migration publish issues.
Use this skill whenever the user mentions Horizon by name in a Laravel context. Covers the full Horizon lifecycle: installing Horizon (horizon:install, Sail setup), configuring config/horizon.php (supervisor blocks, queue assignments, balancing strategies, minProcesses/maxProcesses), fixing the dashboard (authorization via Gate::define viewHorizon, blank metrics, horizon:snapshot scheduling), and troubleshooting production issues (worker crashes, timeout chain ordering, LongWaitDetected notifications, waits config). Also covers job tagging and silencing. Do not use for generic Laravel queues without Horizon, SQS or database drivers, standalone Redis setup, Linux supervisord, Telescope, or job batching.
Develops real-time broadcasting with Laravel Echo. Activates when setting up broadcasting (Reverb, Pusher, Ably); creating ShouldBroadcast events; defining broadcast channels (public, private, presence, encrypted); authorizing channels; configuring Echo; listening for events; implementing client events (whisper); setting up model broadcasting; broadcasting notifications; or when the user mentions broadcasting, Echo, WebSockets, real-time events, Reverb, or presence channels.
ACTIVATE when the user works on authentication in Laravel. This includes login, registration, password reset, email verification, two-factor authentication (2FA/TOTP/QR codes/recovery codes), passkeys, profile updates, password confirmation, or any auth-related routes and controllers. Activate when the user mentions Fortify, auth, authentication, login, register, signup, forgot password, verify email, 2FA, passkeys, WebAuthn, or references app/Actions/Fortify/, CreateNewUser, UpdateUserProfileInformation, FortifyServiceProvider, config/fortify.php, or auth guards. Fortify is the frontend-agnostic authentication backend for Laravel that registers all auth routes and controllers. Also activate when building SPA or headless authentication, customizing login redirects, overriding response contracts like LoginResponse, or configuring login throttling. Do NOT activate for Laravel Passport (OAuth2 API tokens), Socialite (OAuth social login), or non-auth Laravel features.
Use this skill to analyze how a Laravel application is actually written and record its conventions as shared rules. Trigger when the user wants to detect, infer, document, or standardize project conventions or coding style, set up or grow `.ai/rules`, resolve mixed or conflicting patterns (e.g. \"are we using Form Requests or inline validation?\"), or onboard agents and teammates to \"how we do things here\". Covers: a systematic sweep of ~49 Laravel convention dimensions (validation, models, architecture, testing, frontend, database, console), open-ended house-pattern discovery, conflict reporting, and recording rules scoped to the right paths via the Boost `record-rule` MCP tool. Do not use for one-off code review, enforcing formatting a linter already handles, or editing `.ai/rules` files by hand.