Vitest TypeScript Testing

Core Testing Principles

Follow these fundamental patterns when writing Vitest tests:

Imports: Explicitly import all testing functions:

import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";

Test Structure: Use test() instead of it(). Organize with describe() blocks (max 4 levels). Structure tests using the Given-When-Then pattern (setup, execution, assertion) but do not write Given/When/Then comments in the actual code:

describe("ComponentName", () => {
  describe("method name", () => {
    test("does something specific", () => {
      const input = createTestData();

      const result = methodName(input);

      expect(result).toStrictEqual(expected);
    });
  });
});

Assertions: Prefer single comprehensive assertions over multiple partial assertions:

// ✅ Good - single comprehensive assertion
expect(result).toStrictEqual({ id: 1, name: "test", active: true });

// ❌ Avoid - multiple partial assertions
expect(result.id).toBe(1);
expect(result.name).toBe("test");
expect(result.active).toBe(true);

Snapshots: Use toMatchInlineSnapshot() to verify values should not change unexpectedly:

expect(computed).toMatchInlineSnapshot(`
  {
    "key": "value",
  }
`);

Update snapshots when values intentionally change:

vitest --update

File Location: Place test files next to implementation:

• render.ts → render.test.ts in same directory

Prohibited: Never use test.skip(), test.only(), or test.todo() in test modifications. Tests must always run completely.

Unit Testing Patterns

Basic Unit Test Structure

import { describe, test, expect } from "vitest";
import { functionToTest } from "./module";

describe("functionToTest", () => {
  test("returns expected result", () => {
    const result = functionToTest("input");
    expect(result).toStrictEqual({ output: "expected" });
  });
});

Async Testing

Use resolves and rejects for promise assertions:

import { describe, test, expect } from "vitest";

describe("async function", () => {
  test("resolves with correct value", async () => {
    await expect(asyncFunction()).resolves.toEqual({ data: "value" });
  });

  test("rejects with error", async () => {
    await expect(failingFunction()).rejects.toThrow("message");
  });
});

Type Narrowing with Discriminated Unions

Use assert() to narrow types safely:

import { describe, test, expect, assert } from "vitest";

type Result =
  | { type: "success"; data: string }
  | { type: "error"; message: string };

describe("handleResult", () => {
  test("handles success case", () => {
    const result: Result = getResult();

    assert(result.type === "success");

    expect(result.data).toBe("expected");
  });
});

Critical: Never use conditional assertions without type narrowing. Always use assert() for discriminated union branches to enable type narrowing.

Mocking

Mocking should be used as a last resort. Before mocking, consider refactoring the implementation to make it more testable. If the implementation can be changed to be easier to test without mocks, suggest that refactoring instead.

Basic mocking example:

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

describe("with mocks", () => {
  test("mocks function call", () => {
    const mockFn = vi.fn();

    mockFn("arg");

    expect(mockFn).toHaveBeenCalledWith("arg");
  });
});

Browser Mode Component Testing

Setup

Browser mode tests require explicit import configuration:

import { describe, test, expect } from "vitest";
import { render } from "vitest-browser-react";
import { page, userEvent } from "vitest/browser";

Critical: Always use userEvent from vitest/browser for user interactions, not direct element methods.

Basic Component Test

import { describe, test, expect } from "vitest";
import { render } from "vitest-browser-react";
import { page } from "vitest/browser";
import { UserGreeting } from "./UserGreeting";

describe("UserGreeting", () => {
  test("renders greeting with user name", async () => {
    await render(<UserGreeting name="Alice" />);

    await expect.element(page.getByText("Hello, Alice!")).toBeInTheDocument();
  });

  test("renders default greeting when no name provided", async () => {
    await render(<UserGreeting />);

    await expect.element(page.getByText("Hello, Guest!")).toBeInTheDocument();
  });
});

Component Interaction Testing

import { describe, test, expect } from "vitest";
import { render } from "vitest-browser-react";
import { page, userEvent } from "vitest/browser";

describe("Counter", () => {
  test("increments count on button click", async () => {
    await render(<Counter initialCount={0} />);
    await expect.element(page.getByText("Count: 0")).toBeInTheDocument();

    await userEvent.click(page.getByRole("button", { name: "Increment" }));

    await expect.element(page.getByText("Count: 1")).toBeInTheDocument();
  });
});

Form Testing

import { describe, test, expect } from "vitest";
import { render } from "vitest-browser-react";
import { page, userEvent } from "vitest/browser";

describe("LoginForm", () => {
  test("submits with user input", async () => {
    await render(<LoginForm />);

    await userEvent.fill(page.getByLabelText("Username"), "testuser");
    await userEvent.fill(page.getByLabelText("Password"), "password123");
    await userEvent.click(page.getByRole("button", { name: "Submit" }));

    await expect
      .element(page.getByText("Welcome testuser"))
      .toBeInTheDocument();
  });
});

Testing with Context Providers

import { describe, test, expect } from "vitest";
import { render } from "vitest-browser-react";
import { page } from "vitest/browser";
import { ThemeProvider } from "./ThemeProvider";

describe("ThemedButton", () => {
  test("renders with theme", async () => {
    await render(<ThemedButton>Click Me</ThemedButton>, {
      wrapper: ({ children }) => (
        <ThemeProvider theme="dark">{children}</ThemeProvider>
      ),
    });

    await expect
      .element(page.getByRole("button"))
      .toHaveAttribute("data-theme", "dark");
  });
});

Hook Testing

import { describe, test, expect } from "vitest";
import { renderHook } from "vitest-browser-react";

describe("useCounter", () => {
  test("increments counter", async () => {
    const { result, act } = await renderHook(() => useCounter());

    expect(result.current.count).toBe(0);

    await act(() => {
      result.current.increment();
    });

    expect(result.current.count).toBe(1);
  });
});

Common Patterns Reference

Hierarchical Test Organization

import { describe, test, expect } from "vitest";

describe("Calculator", () => {
  describe("add", () => {
    test("adds two positive numbers", () => {
      expect(add(2, 3)).toBe(5);
    });

    test("adds negative numbers", () => {
      expect(add(-2, -3)).toBe(-5);
    });
  });

  describe("subtract", () => {
    test("subtracts numbers", () => {
      expect(subtract(5, 3)).toBe(2);
    });
  });
});

Test Fixtures with test.extend

Prefer test.extend over beforeEach/afterEach for setup and teardown:

import { test as base, expect } from "vitest";

interface Fixtures {
  testData: TestData;
}

const test = base.extend<Fixtures>({
  testData: async ({}, use) => {
    const data = createTestData();

    await use(data);

    cleanup(data);
  },
});

describe("with fixtures", () => {
  test("uses test data", ({ testData }) => {
    expect(testData).toBeDefined();
  });
});

Test Execution

Prefer npm scripts over direct CLI execution. Vitest CLI runs in interactive mode by default, which is problematic for automated execution.

When running tests directly via CLI, always use the --run option to disable interactive mode:

vitest --run

For CI/CD or automated workflows, use npm scripts defined in package.json:

npm test
# or
npm run test

Lint Error Resolution

If test code produces lint errors, resolve them before proceeding. Common fixes:

• Add missing imports
• Fix type errors
• Remove unused variables
• Correct assertion patterns