✅ LLM Unit Testing Best Practices Checklist Focused on testing internal logic, not API endpoints --- ## 🔍 Context Verification - [ ] Understand the Purpose of the Component Do not infer from names. Derive intent from behavior and direct usage. - [ ] Identify Critical Inputs and Outputs Cover expected, edge, malformed, and unexpected scenarios. - [ ] Determine the True Unit Under Test Target the logic layer (e.g., services, classes, helpers):not API routes or request handlers. - [ ] Avoid API Testing Patterns Do not simulate NextRequest, fetch, or Express routes unless explicitly instructed. - [ ] Apply Strict Scope Discipline Don’t touch other modules, files, or features unless clearly necessary. - [ ] Always Tend to Simplify Clear, modular tests beat overly clever ones. - [ ] Avoid Adding Dependencies Unless Justified Don't install libraries unless there's a strong, test-specific reason. - [ ] Preserve Test Configuration Do not alter global setups, environments, or shared mocks unless explicitly asked. - [ ] Use Subagents for Complex Flows When testing decision trees or workflows, spawn helpers to aid decomposition and reliability. --- ## ⚙️ Test Structure - [ ] Test Core Behavior, Not Wiring The unit under test must not include route handlers, HTTP abstractions, or serialization logic. - [ ] Follow the Given:When:Then Format Reinforces clarity and intention behind test actions. - [ ] Name Tests Clearly Prefer: should_<action>_when_<condition>_given_<context> --- ## 🧪 Test Cases - [ ] Focus on Internal Logic Units Classes, methods, services, pure functions:these are the test targets. - [ ] Cover Valid and Invalid Inputs Ensure the unit responds correctly to correct and incorrect usage. - [ ] Avoid Over-Mocking Only mock I/O or external services:never mock the unit’s own logic. - [ ] Don’t Test API Response Codes or Routing Behavior This is not the place for POST(req) or handler-level simulation. - [ ] Test Error Handling at Logic Level Use exceptions or return contracts to test failure modes. - [ ] Ensure Side Effects Are Observable Mock or spy on dependencies like loggers, DBs, and queues. - [ ] Concurrency or Timing Logic? Test resolution order, error propagation, and safe retries where applicable. --- ## 🧼 Cleanliness & Isolation - [ ] Mock All I/O DBs, APIs, file systems, message queues:never call real ones. - [ ] Keep Internal Logic Real Do not mock: - Business rules - Validation logic - Pure functions or deterministic workflows - [ ] No Magic Values Prefer named constants or well-described literals. - [ ] Clean Test State Between Runs All tests must be deterministic, stateless, and safe for parallel execution. - [ ] No Real HTTP or Framework Bindings No fetch, no NextRequest, no server context. --- ## 🧠 Deep Assertions - [ ] Check Real Output Contracts Assert on return values, thrown errors, and logged events. - [ ] Test for Type and Shape Use TS-aware assertions to verify runtime matches compile-time contracts. - [ ] Guard Against Silent Changes Test behavior boundaries, not just return values. --- ## 📦 Maintainability - [ ] Avoid Duplicated Test Code Use factories, builders, and setup helpers. - [ ] Mock via Public Interfaces Never mock private internals:only what the consumer sees. - [ ] Don’t Lock In Behavior That Can Change Safely Test business outcomes, not private steps (unless debugging a regression). --- ## 📣 Final Prompt Guidance for the LLM > You are writing a unit test for $FEATURE, focusing exclusively on internal logic (e.g., services, helpers, pure functions). > > 🔒 You must not simulate API requests, handlers, routers, or HTTP layers. > 🔍 Test business logic, validation rules, branching paths, and error cases. > ✅ Ensure all assertions are observable, meaningful, and test contracts, not internals. > 🧪 Prefer clean test design over full coverage. Quality > quantity. > > Always run npm run build and npm test to confirm test correctness and build integrity. > Be precise, focused, and insightful. Your job is to ensure the logic is future-proof. > Ultrathink. > Alway Span 4 sub-agents at least to help you accelerate the work completion.