jest-vitest

When this skill is activated, always start your first response with the 🧢 emoji.

Jest / Vitest

Jest and Vitest are the dominant unit testing frameworks for JavaScript and TypeScript. Jest is the battle-tested choice bundled with Create React App and widely adopted across Node.js ecosystems. Vitest is the modern successor - it reuses Vite's transform pipeline, offers a compatible API, and is significantly faster for projects already on Vite. Both share the same describe/it/expect vocabulary, making knowledge transferable. This skill covers writing well-structured tests, mocking strategies, async patterns, snapshot testing, React component testing, and coverage analysis.

When to use this skill

Trigger this skill when the user:

• Asks to write, review, or improve unit tests in JavaScript or TypeScript
• Mentions Jest, Vitest, describe, it, test, expect, or beforeEach
• Needs to mock a module, function, or dependency (vi.fn, jest.fn, vi.mock)
• Asks about snapshot testing or updating snapshots
• Wants to configure a test runner for a new or existing project
• Needs to test React (or other UI) components with @testing-library
• Asks about test coverage - thresholds, gaps, or measuring it
• Is migrating a test suite from Jest to Vitest

Do NOT trigger this skill for:

• End-to-end or browser automation testing (use Playwright / Cypress skills instead)
• Static analysis or linting - these are not tests

Key principles

1. Test behavior, not implementation - Tests should verify what a unit does

from the outside, not how it does it internally. Tests that reach into private state or assert on internal call sequences break during refactoring even when behavior is unchanged.

1. Arrange-Act-Assert - Every test has three clear sections: set up the

preconditions, perform the action under test, then assert the outcome. Keep each section small. Long Arrange sections signal the API is too complex.

1. One assertion concept per test - A test should fail for exactly one

reason. Multiple expect calls are fine when they all verify the same behavioral concept. Tests that verify two unrelated concepts hide which behavior broke.

1. Mock at boundaries, not internals - Mock I/O and external services

(HTTP clients, databases, file system, timers) at their entry point. Do not mock internal helper functions within the same module - that tests the wiring, not the behavior.

1. Fast tests run more often - A suite that completes in under 10 seconds

gets run on every save. One that takes 2 minutes gets run before commits only. Keep unit tests in-memory: no real network, no real filesystem, no real clocks.

Core concepts

Test lifecycle

beforeAll  → runs once before all tests in a describe block
beforeEach → runs before each individual test
afterEach  → runs after each individual test (cleanup)
afterAll   → runs once after all tests in a describe block

Prefer beforeEach / afterEach over beforeAll / afterAll. Shared state across tests causes order-dependent failures that are painful to debug.

Matchers

| Matcher | Use for | |---|---| | toBe(value) | Strict equality (===) for primitives | | toEqual(value) | Deep equality for objects and arrays | | toStrictEqual(value) | Deep equality including undefined properties and class instances | | toMatchObject(partial) | Object contains at least these keys/values | | toContain(item) | Array contains item, string contains substring | | toThrow(error?) | Function throws (wrap in () => fn()) | | toHaveBeenCalledWith(...args) | Mock was called with specific arguments | | toHaveBeenCalledTimes(n) | Mock call count | | resolves / rejects | Chain on Promises: await expect(p).resolves.toBe(x) |

Mock types

| Type | API | Purpose | |---|---|---| | Function mock | vi.fn() / jest.fn() | Replaces a function, records calls | | Spy | vi.spyOn(obj, 'method') | Wraps an existing method, records calls, can restore | | Module mock | vi.mock('module') / jest.mock('module') | Replaces an entire module's exports |

Snapshot testing

Snapshots serialize a value to a .snap file on first run, then assert the value matches that serialization on subsequent runs. Use snapshots for stable, complex output (serialized data structures, CLI output). Avoid snapshots for UI components rendered to HTML - they become noisy and get blindly updated.

Update stale snapshots intentionally with --updateSnapshot (-u) after reviewing the diff.

Coverage metrics

| Metric | What it measures | |---|---| | Statements | Percentage of executable statements run | | Branches | Percentage of if/else/ternary paths taken | | Functions | Percentage of functions called at least once | | Lines | Percentage of source lines executed |

Branch coverage is the most meaningful metric. A function with 100% statement coverage but 60% branch coverage has untested if paths that can fail in production. Aim for 80%+ branch coverage on business logic.

Common tasks

Write well-structured tests with AAA

// src/cart.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  let cart: Cart;

  beforeEach(() => {
    // Arrange - fresh cart for each test, no shared state
    cart = new Cart();
  });

  it('starts empty', () => {
    // Assert only - trivial arrange already done
    expect(cart.itemCount()).toBe(0);
    expect(cart.total()).toBe(0);
  });

  it('adds items and updates total', () => {
    // Act
    cart.add({ id: '1', name: 'Widget', price: 9.99, quantity: 2 });

    // Assert
    expect(cart.itemCount()).toBe(2);
    expect(cart.total()).toBeCloseTo(19.98);
  });

  it('throws when adding an item with zero quantity', () => {
    expect(() =>
      cart.add({ id: '1', name: 'Widget', price: 9.99, quantity: 0 })
    ).toThrow('Quantity must be positive');
  });
});

Mock modules and dependencies

// src/order-service.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';

// Module mock hoisted to top of file by Vitest/Jest
vi.mock('./payment-gateway', () => ({
  charge: vi.fn(),
}));
vi.mock('./mailer', () => ({
  sendConfirmation: vi.fn(),
}));

import { placeOrder } from './order-service';
import { charge } from './payment-gateway';
import { sendConfirmation } from './mailer';

describe('placeOrder', () => {
  beforeEach(() => {
    vi.resetAllMocks();
  });

  it('charges the customer and sends a confirmation on success', async () => {
    // Arrange
    vi.mocked(charge).mockResolvedValue({ success: true, transactionId: 'txn_123' });
    const order = { id: 'ord_1', total: 49.99, customer: { email: 'a@b.com' } };

    // Act
    await placeOrder(order);

    // Assert
    expect(charge).toHaveBeenCalledWith({ amount: 49.99, orderId: 'ord_1' });
    expect(sendConfirmation).toHaveBeenCalledWith('a@b.com', 'ord_1');
  });

  it('throws OrderFailedError when payment is declined', async () => {
    vi.mocked(charge).mockResolvedValue({ success: false, error: 'Insufficient funds' });
    const order = { id: 'ord_2', total: 200, customer: { email: 'a@b.com' } };

    await expect(placeOrder(order)).rejects.toThrow('OrderFailedError');
    expect(sendConfirmation).not.toHaveBeenCalled();
  });
});

Test async code - promises, timers, and events

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { fetchUser } from './user-api';

// --- Promises ---
it('resolves with user data', async () => {
  const user = await fetchUser('user-1');
  expect(user).toMatchObject({ id: 'user-1', name: expect.any(String) });
});

it('rejects when user is not found', async () => {
  await expect(fetchUser('nonexistent')).rejects.toThrow('User not found');
});

// --- Fake timers (debounce, throttle, setTimeout) ---
describe('d