testing
Testing patterns for behavior-driven tests. Use when writing tests or test factories.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for behavior-driven testing (BDT) and the Test Factory pattern. It empowers developers to create resilient, maintainable test suites by focusing on public API behavior rather than internal implementation details. By following these patterns, teams can achieve meaningful 100% code coverage that reflects business logic, eliminate 'coverage theater,' and manage complex test data through schema-validated factories.
Use Cases
- Refactoring Legacy Code: Ensure tests remain valid and passing during internal code restructuring by testing through public APIs instead of private methods.
- Scalable Test Data Management: Use the Test Factory pattern to generate fresh, type-safe, and customizable mock data for complex unit and integration tests, avoiding shared state issues.
- Eliminating Coverage Theater: Identify and replace low-value tests (like mocking the function being tested) with assertions that verify actual business outcomes and edge cases.
- Schema-Driven Validation: Integrate production schemas into test factories to ensure test data is always synchronized with real-world data structures and catch breaking changes early.
- Behavioral Coverage Analysis: Shift the focus from 'missing lines' to 'missing business behaviors' when analyzing code coverage to ensure all functional requirements are verified.
| name | testing |
|---|---|
| description | Testing patterns for behavior-driven tests. Use when writing tests or test factories. |
Testing Patterns
Core Principle
Test behavior, not implementation. 100% coverage through business behavior, not implementation details.
Example: Validation code in payment-validator.ts gets 100% coverage by testing processPayment() behavior, NOT by directly testing validator functions.
Test Through Public API Only
Never test implementation details. Test behavior through public APIs.
Why this matters:
- Tests remain valid when refactoring
- Tests document intended behavior
- Tests catch real bugs, not implementation changes
Examples
❌ WRONG - Testing implementation:
// ❌ Testing HOW (implementation detail)
it("should call validateAmount", () => {
const spy = jest.spyOn(validator, "validateAmount");
processPayment(payment);
expect(spy).toHaveBeenCalled(); // Tests HOW, not WHAT
});
// ❌ Testing private methods
it("should validate CVV format", () => {
const result = validator._validateCVV("123"); // Private method!
expect(result).toBe(true);
});
// ❌ Testing internal state
it("should set isValidated flag", () => {
processPayment(payment);
expect(processor.isValidated).toBe(true); // Internal state
});
✅ CORRECT - Testing behavior through public API:
it("should reject negative amounts", () => {
const payment = getMockPayment({ amount: -100 });
const result = processPayment(payment);
expect(result.success).toBe(false);
expect(result.error).toContain("Amount must be positive");
});
it("should reject invalid CVV", () => {
const payment = getMockPayment({ cvv: "12" }); // Only 2 digits
const result = processPayment(payment);
expect(result.success).toBe(false);
expect(result.error).toContain("Invalid CVV");
});
it("should process valid payments", () => {
const payment = getMockPayment({ amount: 100, cvv: "123" });
const result = processPayment(payment);
expect(result.success).toBe(true);
expect(result.data.transactionId).toBeDefined();
});
Coverage Through Behavior
Validation code gets 100% coverage by testing the behavior it protects:
// Tests covering validation WITHOUT testing validator directly
describe("processPayment", () => {
it("should reject negative amounts", () => {
const payment = getMockPayment({ amount: -100 });
const result = processPayment(payment);
expect(result.success).toBe(false);
});
it("should reject amounts over 10000", () => {
const payment = getMockPayment({ amount: 15000 });
const result = processPayment(payment);
expect(result.success).toBe(false);
});
it("should reject invalid CVV", () => {
const payment = getMockPayment({ cvv: "12" });
const result = processPayment(payment);
expect(result.success).toBe(false);
});
it("should process valid payments", () => {
const payment = getMockPayment({ amount: 100, cvv: "123" });
const result = processPayment(payment);
expect(result.success).toBe(true);
});
});
// ✅ Result: payment-validator.ts has 100% coverage through behavior
Key insight: When coverage drops, ask "What business behavior am I not testing?" not "What line am I missing?"
Test Factory Pattern
For test data, use factory functions with optional overrides.
Core Principles
- Return complete objects with sensible defaults
- Accept
Partial<T>overrides for customization - Validate with real schemas (don't redefine)
- NO
let/beforeEach- use factories for fresh state
Basic Pattern
const getMockUser = (overrides?: Partial<User>): User => {
return UserSchema.parse({
id: "user-123",
name: "Test User",
email: "test@example.com",
role: "user",
...overrides,
});
};
// Usage
it("creates user with custom email", () => {
const user = getMockUser({ email: "custom@example.com" });
const result = createUser(user);
expect(result.success).toBe(true);
});
Complete Factory Example
import { UserSchema } from "@/schemas"; // Import real schema
const getMockUser = (overrides?: Partial<User>): User => {
return UserSchema.parse({
id: "user-123",
name: "Test User",
email: "test@example.com",
role: "user",
isActive: true,
createdAt: new Date("2024-01-01"),
...overrides,
});
};
Why validate with schema?
- Ensures test data is valid according to production schema
- Catches breaking changes early (schema changes fail tests)
- Single source of truth (no schema redefinition)
Factory Composition
For nested objects, compose factories:
const getMockItem = (overrides?: Partial<Item>): Item => {
return ItemSchema.parse({
id: "item-1",
name: "Test Item",
price: 100,
...overrides,
});
};
const getMockOrder = (overrides?: Partial<Order>): Order => {
return OrderSchema.parse({
id: "order-1",
items: [getMockItem()], // ✅ Compose factories
customer: getMockCustomer(), // ✅ Compose factories
payment: getMockPayment(), // ✅ Compose factories
...overrides,
});
};
// Usage - override nested objects
it("calculates total with multiple items", () => {
const order = getMockOrder({
items: [getMockItem({ price: 100 }), getMockItem({ price: 200 })],
});
expect(calculateTotal(order)).toBe(300);
});
Anti-Patterns
❌ WRONG: Using let and beforeEach
let user: User;
beforeEach(() => {
user = { id: 'user-123', name: 'Test User', ... }; // Shared mutable state!
});
it('test 1', () => {
user.name = 'Modified User'; // Mutates shared state
});
it('test 2', () => {
expect(user.name).toBe('Test User'); // Fails! Modified by test 1
});
✅ CORRECT: Factory per test
it("test 1", () => {
const user = getMockUser({ name: "Modified User" }); // Fresh state
// ...
});
it("test 2", () => {
const user = getMockUser(); // Fresh state, not affected by test 1
expect(user.name).toBe("Test User"); // ✅ Passes
});
❌ WRONG: Incomplete objects
const getMockUser = () => ({
id: "user-123", // Missing name, email, role!
});
✅ CORRECT: Complete objects
const getMockUser = (overrides?: Partial<User>): User => {
return UserSchema.parse({
id: "user-123",
name: "Test User",
email: "test@example.com",
role: "user",
...overrides, // All required fields present
});
};
❌ WRONG: Redefining schemas in tests
// ❌ Schema already defined in src/schemas/user.ts!
const UserSchema = z.object({ ... });
const getMockUser = () => UserSchema.parse({ ... });
✅ CORRECT: Import real schema
import { UserSchema } from "@/schemas/user";
const getMockUser = (overrides?: Partial<User>): User => {
return UserSchema.parse({
id: "user-123",
name: "Test User",
email: "test@example.com",
...overrides,
});
};
Coverage Theater Detection
Watch for these patterns that give fake 100% coverage:
Pattern 1: Mock the function being tested
❌ WRONG - Gives 100% coverage but tests nothing:
it("calls validator", () => {
const spy = jest.spyOn(validator, "validate");
validate(payment);
expect(spy).toHaveBeenCalled(); // Meaningless assertion
});
✅ CORRECT - Test actual behavior:
it("should reject invalid payment", () => {
const payment = getMockPayment({ amount: -100 });
const result = validate(payment);
expect(result.success).toBe(false);
expect(result.error).toContain("Amount must be positive");
});
Pattern 2: Test only that function was called
❌ WRONG - No behavior validation:
it("processes payment", () => {
const spy = jest.spyOn(processor, "process");
handlePayment(payment);
expect(spy).toHaveBeenCalledWith(payment); // So what?
});
✅ CORRECT - Verify the outcome:
it("should process payment and return transaction ID", () => {
const payment = getMockPayment();
const result = handlePayment(payment);
expect(result.success).toBe(true);
expect(result.transactionId).toBeDefined();
});
Pattern 3: Test trivial getters/setters
❌ WRONG - Testing implementation, not behavior:
it("sets amount", () => {
payment.setAmount(100);
expect(payment.getAmount()).toBe(100); // Trivial
});
✅ CORRECT - Test meaningful behavior:
it("should calculate total with tax", () => {
const order = createOrder({ items: [item1, item2] });
const total = order.calculateTotal();
expect(total).toBe(230); // 200 + 15% tax
});
Pattern 4: 100% line coverage, 0% branch coverage
❌ WRONG - Missing edge cases:
it("validates payment", () => {
const result = validate(getMockPayment());
expect(result.success).toBe(true); // Only happy path!
});
// Missing: negative amounts, invalid CVV, missing fields, etc.
✅ CORRECT - Test all branches:
describe("validate payment", () => {
it("should reject negative amounts", () => {
const payment = getMockPayment({ amount: -100 });
expect(validate(payment).success).toBe(false);
});
it("should reject amounts over limit", () => {
const payment = getMockPayment({ amount: 15000 });
expect(validate(payment).success).toBe(false);
});
it("should reject invalid CVV", () => {
const payment = getMockPayment({ cvv: "12" });
expect(validate(payment).success).toBe(false);
});
it("should accept valid payments", () => {
const payment = getMockPayment();
expect(validate(payment).success).toBe(true);
});
});
No 1:1 Mapping Between Tests and Implementation
Don't create test files that mirror implementation files.
❌ WRONG:
src/
payment-validator.ts
payment-processor.ts
payment-formatter.ts
tests/
payment-validator.test.ts ← 1:1 mapping
payment-processor.test.ts ← 1:1 mapping
payment-formatter.test.ts ← 1:1 mapping
✅ CORRECT:
src/
payment-validator.ts
payment-processor.ts
payment-formatter.ts
tests/
process-payment.test.ts ← Tests behavior, not implementation files
Why: Implementation details can be refactored without changing tests. Tests verify behavior remains correct regardless of how code is organized internally.
Summary Checklist
When writing tests, verify:
- Testing behavior through public API (not implementation details)
- No mocks of the function being tested
- No tests of private methods or internal state
- Factory functions return complete, valid objects
- Factories validate with real schemas (not redefined in tests)
- Using Partial for type-safe overrides
- No
let/beforeEach- use factories for fresh state - Edge cases covered (not just happy path)
- Tests would pass even if implementation is refactored
- No 1:1 mapping between test files and implementation files