Vitest: Matchers, Mocks, Async Tests and Coverage Reference Guide

# Install (works on top of Vite or standalone)
npm i -D vitest @vitest/coverage-v8
# For DOM tests
npm i -D jsdom happy-dom @testing-library/dom @testing-library/react @testing-library/jest-dom
# For UI runner
npm i -D @vitest/ui

# vitest.config.ts  (or extend vite.config.ts)
import { defineConfig } from "vitest/config";
export default defineConfig({
  test: {
    environment: "node",          // or "jsdom" | "happy-dom" | "edge-runtime"
    globals: false,               // true = auto-inject expect, vi, test, describe
    setupFiles: ["./test/setup.ts"],
    coverage: { provider: "v8", reporter: ["text", "lcov", "html"] },
  },
});

# package.json
{
  "scripts": {
    "test":      "vitest",                   # watch by default
    "test:run":  "vitest run",               # one-shot (CI)
    "test:ui":   "vitest --ui",
    "test:cov":  "vitest run --coverage"
  }
}

# Run
npx vitest                                 # watch
npx vitest run path/to/file.test.ts        # one file, no watch
npx vitest -t "login"                      # name filter
npx vitest --reporter=verbose
npx vitest --bail=1 --no-color

import { vi, test, expect, beforeEach } from "vitest";
import * as db from "./db";

// 1. Plain mock function
const cb = vi.fn((x: number) => x * 2);
cb(3);
expect(cb).toHaveBeenCalledWith(3);

// 2. Stage return values
const fetchUser = vi
  .fn()
  .mockResolvedValueOnce({ id: 1 })
  .mockResolvedValueOnce({ id: 2 })
  .mockRejectedValue(new Error("nope"));

// 3. Spy on a real method (keeps original)
const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
// ...code under test...
spy.mockRestore();

// 4. Module mock — hoisted above imports (like Jest)
vi.mock("./db", () => ({
  getUser: vi.fn(async (id: number) => ({ id, name: "Mock" })),
}));

// 4b. Partial mock — keep real exports, swap one
vi.mock("./db", async (importOriginal) => {
  const actual = await importOriginal();
  return { ...actual, getUser: vi.fn() };
});

// 4c. Reference outer vars safely — use vi.hoisted()
const { fakeId } = vi.hoisted(() => ({ fakeId: 42 }));
vi.mock("./id", () => ({ next: () => fakeId }));

// 5. Reset between tests
beforeEach(() => {
  vi.clearAllMocks();    // call history
  // vi.resetAllMocks();  // also implementations
  // vi.restoreAllMocks();// restore spies
});

import { vi, test, expect, afterAll } from "vitest";

// Async/await — await or return the promise
test("resolves", async () => {
  await expect(getUser(1)).resolves.toEqual({ id: 1 });
  await expect(getUser(-1)).rejects.toThrow("not found");
});

// Retry a flaky test (built-in, no plugin)
test("eventually", { retry: 3, timeout: 5_000 }, async () => {
  await expect(ping()).resolves.toBe("ok");
});

// Fake timers — vi.useFakeTimers() replaces setTimeout/Date
vi.useFakeTimers();
test("debounce fires after 250ms", async () => {
  const fn = vi.fn();
  const d = debounce(fn, 250);
  d(); d(); d();
  await vi.advanceTimersByTimeAsync(249);
  expect(fn).not.toHaveBeenCalled();
  await vi.advanceTimersByTimeAsync(1);
  expect(fn).toHaveBeenCalledTimes(1);
});

// Drain all timers + microtasks
// await vi.runAllTimersAsync();
// Pin Date.now()
// vi.setSystemTime(new Date("2026-01-01"));

afterAll(() => vi.useRealTimers());

// src/cart.ts
export const total = (items: { price: number; qty: number }[]) =>
  items.reduce((s, i) => s + i.price * i.qty, 0);

export async function checkout(items, pay) {     // pay: (cents) => Promise<{ok:boolean}>
  if (!items.length) throw new Error("empty cart");
  const cents = Math.round(total(items) * 100);
  const res = await pay(cents);
  if (!res.ok) throw new Error("payment failed");
  return { paid: cents };
}

// In-source tests — same file, stripped from prod builds
if (import.meta.vitest) {
  const { test, expect } = import.meta.vitest;
  test("total sums price*qty", () => {
    expect(total([{ price: 2, qty: 3 }])).toBe(6);
  });
}

// src/cart.test.ts
import { describe, test, expect, vi } from "vitest";
import { total, checkout } from "./cart";

describe("cart", () => {
  test("checkout calls pay with cents", async () => {
    const pay = vi.fn().mockResolvedValue({ ok: true });
    await expect(checkout([{ price: 9.99, qty: 1 }], pay)).resolves.toEqual({ paid: 999 });
    expect(pay).toHaveBeenCalledWith(999);
  });

  test("rejects empty cart", async () => {
    await expect(checkout([], vi.fn())).rejects.toThrow("empty cart");
  });
});