test-writer

name	test-writer
description	Use this skill when writing unit tests, integration tests, or end-to-end tests for existing or new code. Trigger phrases: 'write tests for', 'add test coverage', 'how do I test this', 'TDD this feature'. Not for running or debugging test infrastructure or CI pipelines.
version	1.0.0
author	community
tags	["coding","testing","unit-tests","tdd","jest"]
license	MIT

Test Writer

Overview

The Test Writer skill produces comprehensive, maintainable tests following established practices: the test pyramid (unit → integration → e2e), the AAA (Arrange-Act-Assert) pattern, meaningful naming conventions, and effective mocking strategies. It helps determine what to test, how to structure test files, what to mock vs. not mock, and how to set coverage targets. Good tests serve as executable documentation that catches regressions before they reach production.

When to Use

• Writing tests for a new function, class, or module
• Adding tests to untested legacy code before refactoring
• Following Test-Driven Development (TDD) — writing tests before implementation
• Evaluating test coverage and identifying what's missing
• Writing integration tests for API endpoints or database interactions

When NOT to Use

• Setting up CI/CD pipelines or test runners (infrastructure concern)
• Load testing or performance benchmarking (different tooling)
• Writing end-to-end browser automation scripts (use a Playwright/Cypress skill)
• Debugging a failing test (use the debugger skill to find the root cause)

Quick Reference

Level	Scope	Speed	Mock?	Target %
Unit	Single function/class	Fast (<1ms)	Dependencies	70–80% of tests
Integration	Multiple modules + real DB/API	Medium (10–100ms)	External services only	15–25% of tests
E2E	Full user journey through UI	Slow (1–30s)	Nothing	5–10% of tests

Concept	Description
AAA	Arrange (set up) → Act (call) → Assert (verify)
Naming	describe('unit') / it('should behavior when condition')
Mocking	Replace dependencies with controlled test doubles
Coverage target	80% line coverage; 100% on critical paths
TDD cycle	Red → Green → Refactor

Instructions

1. Identify the unit under test

   • Pick a single function, method, or class as the subject.
   • List all inputs, outputs, side effects, and error conditions.
   • Identify dependencies that need to be mocked (databases, HTTP clients, file system, clocks).

2. Choose the right test level

   • Unit test: test a function in isolation with all dependencies mocked.
   • Integration test: test multiple real components together (e.g., service + real DB).
   • E2E test: test a full user-facing workflow through the actual UI or API.

3. Identify test cases

   • Happy path: the function works correctly with valid input.
   • Edge cases: empty string, empty array, zero, null, very large numbers, boundary values.
   • Error cases: invalid input, dependency throws, timeout.
   • State variations: first-time user vs. returning user; empty list vs. full list.

4. Apply the AAA pattern to each test

   // Arrange — set up test data and mocks
   // Act — call the function under test
   // Assert — verify the output or side effects
   

5. Apply naming conventions

   • Describe block: name of the unit under test — describe('calculateDiscount')
   • It block: "should [expected behavior] when [condition]" — it('should return 0 when cart is empty')
   • Test file: co-locate with source or mirror directory structure: utils.test.ts, utils.spec.py

6. Mock strategically

   • Mock I/O boundaries: databases, HTTP calls, file system, time, random.
   • Do NOT mock the thing you're testing.
   • Do NOT mock value objects or pure functions — use real instances.
   • Prefer dependency injection over module-level patching for testability.

7. Assert precisely

   • Assert on the exact expected value, not just that "something was called."
   • Verify side effects: was the correct database method called with the correct args?
   • For error cases: assert the exact error type and message.
   • Avoid asserting on internal implementation details that could change without breaking behavior.

Examples

Example 1: Write unit tests for a utility function (JavaScript/Jest)

Input: A calculateDiscount function to test:

// discount.js
export function calculateDiscount(price, userTier) {
  if (price <= 0) throw new Error('Price must be positive');
  const rates = { silver: 0.05, gold: 0.10, platinum: 0.20 };
  const rate = rates[userTier] ?? 0;
  return Math.round(price * rate * 100) / 100;
}

Output:

// discount.test.js
import { calculateDiscount } from './discount';

describe('calculateDiscount', () => {
  describe('happy path', () => {
    it('should apply 5% discount for silver tier', () => {
      // Arrange
      const price = 100;
      const tier = 'silver';

      // Act
      const result = calculateDiscount(price, tier);

      // Assert
      expect(result).toBe(5.00);
    });

    it('should apply 10% discount for gold tier', () => {
      expect(calculateDiscount(100, 'gold')).toBe(10.00);
    });

    it('should apply 20% discount for platinum tier', () => {
      expect(calculateDiscount(100, 'platinum')).toBe(20.00);
    });

    it('should return 0 discount for unknown tier', () => {
      expect(calculateDiscount(, )).();
    });

    (,  {
      ((, )).();
    });

    (,  {
      
      ((, )).();
    });
  });

  (,  {
    (,  {
      ( (, )).();
    });

    (,  {
      ( (-, )).();
    });
  });

  (,  {
    (,  {
      ((, )).();
    });

    (,  {
      ((, )).();
    });
  });
});

---

Example 2: Write an integration test for an API endpoint (Node.js/Jest + Supertest)

Input: An Express endpoint to test:

// routes/users.js
router.post('/users', async (req, res) => {
  const { email, name } = req.body;
  if (!email) return res.status(422).json({ error: 'email is required' });
  const existing = await db.users.findByEmail(email);
  if (existing) return res.status(409).json({ error: 'email already in use' });
  const user = await db.users.create({ email, name });
  return res.status(201).json(user);
});

Output:

// routes/users.integration.test.js
import request from 'supertest';
import { app } from '../app';
import { db } from '../db';

// Use a real test database — no mocking of db layer
beforeAll(async () => { await db.migrate.latest(); });
afterAll(async () => { await db.destroy(); });
afterEach(async () => { await db.raw('DELETE FROM users'); }); // clean state

describe('POST /users', () => {
  describe('successful creation', () => {
    it('should create a user and return 201 with user data', async () => {
      // Arrange
      const payload = { email: '[e-mail]', name: 'Alice' };

      // Act
      const res = await request(app).post('/users').send(payload);

      // Assert
      (res.).();
      (res.).({
        : expect.(),
        : ,
        : ,
        : expect.(),
      });
      
       saved =  db..();
      (saved)..();
    });
  });

  (,  {
    (,  () => {
       res =  (app).().({ :  });
      (res.).();
      (res..).();
    });
  });

  (,  {
    (,  () => {
      
       db..({ : , :  });

      
       res =  (app)
        .()
        .({ : , :  });

      
      (res.).();
      (res..).();
    });
  });
});

Best Practices

• Write tests before code (TDD) to drive better API design
• One logical assertion concept per test — multiple expect() calls are fine if they verify the same behavior
• Tests should be deterministic: no random data, no time-dependent behavior (mock Date.now())
• Keep tests fast — slow tests don't get run; unit tests should complete in milliseconds
• Use test factories or builders for complex object setup to avoid repetition
• Test the contract (what), not the implementation (how) — brittle tests couple to internals

Common Mistakes

• Testing implementation details (private methods, internal state) instead of observable behavior
• Not testing error paths and edge cases — happy-path-only tests miss most bugs
• Over-mocking: mocking so much that tests pass even when real integrations are broken
• Using production database in tests without cleanup — tests pollute each other
• Testing framework code (e.g., testing that Express routing works) instead of your business logic
• Ignoring flaky tests — a flaky test is worse than no test (false confidence)

Tips & Tricks

• Use test.each (Jest) or @pytest.mark.parametrize for table-driven tests with multiple input/output pairs
• Snapshot tests for complex output structures, but review snapshots on every change
• --coverage --collectCoverageFrom to see which lines are untested
• Use faker or factory-boy to generate realistic test data instead of hand-crafting fixtures
• Jest's jest.useFakeTimers() / Python's freezegun to control time-dependent tests

Related Skills

• debugger
• code-reviewer
• api-designer
• refactorer