unit-testing

Unit Testing (TypeScript / JavaScript)

This skill covers unit and component testing in the TypeScript/JavaScript ecosystem. It is the counterpart to e2e-testing (Playwright, full browser) and python-testing (pytest).

When to Use

• Writing unit tests for service logic, utility functions, or domain models
• Writing component tests with React Testing Library
• Reviewing test code for quality, coverage gaps, or brittle patterns
• Setting up a test framework from scratch in a new project
• Debugging a test that passes locally but fails in CI

When NOT to Use

• E2E tests covering full user journeys in a browser — use e2e-testing
• Python tests — use python-testing
• Visual regression testing — different toolchain (Chromatic, Percy)

Framework Choice

Vitest — preferred for new projects (especially Vite, Next.js App Router, Turborepo):

• Same config as Vite (no separate babel/transform setup)
• Faster than Jest in watch mode
• Native ESM support
• Drop-in Jest API compatibility

Jest — preferred when:

• Existing project already uses Jest
• CRA, some NestJS setups, older React Native

This skill uses Vitest syntax. Jest equivalents are identical except for vi.* → jest.*.

Test Structure

src/
├── services/
│   ├── document.service.ts
│   └── document.service.test.ts    # co-located with source
├── components/
│   ├── DocumentCard.tsx
│   └── DocumentCard.test.tsx
└── utils/
    ├── slug.ts
    └── slug.test.ts

Co-location (test next to source) is preferred over a separate __tests__ directory — easier to find, easier to maintain.

Test file naming: *.test.ts or *.spec.ts — choose one convention and apply it consistently.

Test Anatomy

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { DocumentService } from './document.service';

describe('DocumentService', () => {
  let service: DocumentService;

  beforeEach(() => {
    // Fresh instance per test — no shared state between tests
    service = new DocumentService(mockDb);
  });

  describe('create', () => {
    it('returns created document with generated id', async () => {
      // Arrange
      const input = { title: 'Test', content: 'Hello' };

      // Act
      const result = await service.create(input);

      // Assert
      expect(result.id).toBeDefined();
      expect(result.title).toBe('Test');
      expect(result.content).toBe('Hello');
    });

    it('throws ValidationError when title is empty', async () => {
      await expect(service.create({ title: '', content: 'x' }))
        .rejects.toThrow(ValidationError);
    });
  });
});