/test

name: test
description: LLM unit testing best practices checklist for testing internal logic, not API endpoints

✅ 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.