✅ 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 simulateNextRequest,fetch, orExpressroutes 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 forPOST(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
Nofetch, noNextRequest, 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 buildandnpm testto 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.