Unit testing in JavaScript with Vitest and Jest

In this tutorial you will write unit tests for Brew & Bean's JavaScript price and cart logic using Vitest, a modern test runner that works well with Vite and React projects. You will learn the basic structure of a test file, common expect matchers, testing errors, running one test with many inputs, shared set-up with beforeEach, and mock functions.

Prerequisites: Node.js 18 or newer with npm, and basic JavaScript (functions, arrays, objects, ES modules with import and export). The ideas match the pytest lesson, so if you did that one, you will see the same patterns in a different language.

Jest is the long-standing JavaScript test framework, created at Facebook, and is found in many existing codebases (including Create React App projects). Vitest is newer, designed to work with Vite and ES modules out of the box, and deliberately copies Jest's API. If you can write Vitest tests, you can write Jest tests, and the reverse is also true.

Which should you pick? For a new Vite project (such as the Brew & Bean React site), use Vitest. If your team already uses Jest, stay with Jest. The differences are small, and are listed near the end.

mkdir brew-tests
cd brew-tests
npm init -y
npm install --save-dev vitest

Creates a project and installs Vitest as a development dependency.

Open package.json. Add "type": "module" so Node treats .js files as ES modules, and replace the test script. A minimal file looks like this:

{
  "name": "brew-tests",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "vitest run"
  }
}

Keep the devDependencies entry that npm added for vitest (not shown here). vitest run runs once and exits. Plain vitest stays running and re-runs tests when you save.

Create the code to test:

export const MENU = {
  espresso: 120,
  cappuccino: 180,
  "masala-chai": 90,
  croissant: 150,
};

export function formatPrice(amount) {
  return `₹${amount}`;
}

export function calculateTotal(items) {
  if (items.length === 0) {
    throw new Error("An order needs at least one item");
  }
  let total = 0;
  for (const { itemId, qty } of items) {
    if (!(itemId in MENU)) {
      throw new Error(`Unknown item: ${itemId}`);
    }
    if (qty < 1 || qty > 10) {
      throw new Error("Quantity must be between 1 and 10");
    }
    total += MENU[itemId] * qty;
  }
  return total;
}

A small JavaScript twin of the Python pricing module, with four menu items to keep the example short.

Vitest finds files ending in .test.js (or .spec.js). A test file imports the code, groups related tests with describe, and defines each test with it (or test, which is the same thing).

import { describe, it, expect, test } from "vitest";
import { calculateTotal, formatPrice } from "./pricing.js";

describe("calculateTotal", () => {
  it("adds up several items", () => {
    const items = [
      { itemId: "espresso", qty: 2 },
      { itemId: "croissant", qty: 1 },
    ];
    expect(calculateTotal(items)).toBe(390);
  });

  it("rejects an empty order", () => {
    expect(() => calculateTotal([])).toThrow("at least one item");
  });

  test.each([0, 11])("rejects quantity %i", (qty) => {
    expect(() => calculateTotal([{ itemId: "espresso", qty }])).toThrow(
      "between 1 and 10"
    );
  });
});

describe("formatPrice", () => {
  it("adds the rupee sign", () => {
    expect(formatPrice(120)).toBe("₹120");
  });
});

describe groups tests, it defines one test, expect(...).toBe(...) is an assertion. test.each runs one test for several inputs.

Let's read the file. `describe("calculateTotal", ...)` names a group. `it("adds up several items", ...)` is one test, and its name should read like a sentence: 'calculateTotal adds up several items'. Inside, `expect(actual).matcher(expected)` is the assertion. If a matcher fails, it throws and the test fails.

test.each is Vitest's version of pytest's parametrize. In the file above, test.each([0, 11])("rejects quantity %i", ...) runs the test twice, once for each boundary just outside the allowed range. %i is replaced with the value in the test name, so a failure tells you which input broke.

You can also give rows of values. Add this to pricing.test.js:

test.each([
  [1, 120],
  [10, 1200],
])("accepts quantity %i for a total of %i", (qty, expected) => {
  expect(calculateTotal([{ itemId: "espresso", qty }])).toBe(expected);
});

Boundary values 1 and 10 are valid. Each inner array is one case: [qty, expected total].

When several tests need a fresh object, create it in beforeEach, which runs before every test. Here is a small shopping cart that uses calculateTotal:

import { calculateTotal } from "./pricing.js";

export function createCart() {
  const lines = [];
  return {
    add(itemId, qty = 1) {
      const existing = lines.find((line) => line.itemId === itemId);
      if (existing) {
        existing.qty += qty;
      } else {
        lines.push({ itemId, qty });
      }
    },
    lines() {
      return lines.map((line) => ({ ...line }));
    },
    total() {
      return calculateTotal(lines);
    },
  };
}

createCart returns an object with add, lines and total. add merges the same item into one line.

import { describe, it, expect, beforeEach, vi } from "vitest";
import { createCart } from "./cart.js";

describe("cart", () => {
  let cart;

  beforeEach(() => {
    cart = createCart();
  });

  it("starts empty", () => {
    expect(cart.lines()).toEqual([]);
  });

  it("merges the same item into one line", () => {
    cart.add("espresso");
    cart.add("espresso", 2);
    expect(cart.lines()).toEqual([{ itemId: "espresso", qty: 3 }]);
  });

  it("totals the cart", () => {
    cart.add("masala-chai", 2);
    cart.add("croissant");
    expect(cart.total()).toBe(330);
  });

  it("refuses to total an empty cart", () => {
    expect(() => cart.total()).toThrow("at least one item");
  });
});

describe("a mock function", () => {
  it("records how it was called", () => {
    const onOrder = vi.fn();
    onOrder("ord-1001");
    expect(onOrder).toHaveBeenCalledTimes(1);
    expect(onOrder).toHaveBeenCalledWith("ord-1001");
  });
});

beforeEach builds a new cart before every test, so tests cannot affect each other. vi.fn() creates a mock function that records its calls.

Each test starts with a clean cart. If cart were created once outside beforeEach, the second test would see items added by the first, and results would depend on the order of tests. That kind of hidden dependency is a classic source of flaky tests.

The last test in cart.test.js uses vi.fn(), a mock function. It does nothing by default, but it remembers how it was called. That lets you check that your code called a callback, without needing the real thing. For example, a checkout function that takes an onOrder callback and calls it with the new order id. The checks toHaveBeenCalledTimes(1) and toHaveBeenCalledWith("ord-1001") verify that call.

Mocks are a big topic, and *Mocks, stubs and test doubles* in this track covers them properly, including replacing network calls and modules.

npx vitest

Starts watch mode: tests re-run when you save a file, and only the affected ones run. Press q to quit. Press h to see keyboard options.

Watch mode is how most developers work: change a line, save, and see green or red within a second. Combine it with writing a failing test first, then the code to pass it.

Most tests in this lesson would run in Jest if you removed the import ... from "vitest" line, changed vi.fn() to jest.fn(), and set up your project for ES modules or CommonJS. The matchers (toBe, toEqual, toThrow) and structure (describe, it, beforeEach) are the same.

For React, the common pairing is Vitest (or Jest) plus React Testing Library, which renders a component and lets you find things the way a user would (by visible text or role) and click them. That is a topic for the front-end tracks. The foundation is exactly what you learned here: arrange, act, assert.

Typical questions: "What is the difference between toBe and toEqual?", "How do you test an async function?" (make the test function async and await the call, or use expect(promise).resolves), "What is a mock and when would you use one?", "What is the difference between Jest and Vitest?", "What makes a test flaky?" Be ready with the beforeEach example above to explain independent tests.

Write Vitest tests (JavaScript, ES modules, importing describe, it, expect from vitest) for this function.

Function:
[paste function]

Rules it must follow:
[list the rules, e.g. qty 1 to 10, unknown items throw]

Include the happy path, boundary values using test.each, and error cases using toThrow. Use clear test names written as sentences. Do not change the function.

What to expect: Run the tests with npm test. Check that boundary values are on the exact edges, that error tests wrap the call in an arrow function, and that expected numbers are hand-calculated. Break the function on purpose to confirm a test fails.