Testing JavaScript with Vitest

Write focused unit tests with Vitest, structure cases, isolate dependencies, mock network calls, and interpret coverage.

Est. 35 min Updated Suggest a fix
// Part 01 — Why tests

Tests Turn Expectations into Repeatable Checks

A test is executable evidence that code behaves as intended for a chosen set of inputs. Tests do not prove that a program has no defects, but they make important behaviour easier to change without relying on memory or repeating every manual check. They are most useful when they describe observable behaviour rather than the private details of how a function happens to be implemented today.

Vitest is a JavaScript test runner designed to work naturally with Vite-based projects, while also supporting other configurations. It provides test declarations, assertions, mocks, and coverage integration. Before adding a tool, check whether your repository already has a test runner and follow its established setup.

Use the smallest test level that gives confidence in the behaviour being changed.
Test levelWhat it exercisesExample
UnitOne function or small module in isolationDoes parseAmount reject a non-positive amount?
IntegrationSeveral components connected across a boundaryDoes the repository load and save expenses together?
End-to-endA user flow through a running applicationCan a learner add an expense and see it in the list?
🎯 Pro Tip
Good tests are readable specifications. A teammate should understand the expected behaviour from the test name and assertions without reverse-engineering the implementation.
// Part 02 — First test

Arrange, Act, Assert

A clear test has three ideas: arrange the inputs, act by calling the code, and assert on the result. Import the function and Vitest helpers, then name the scenario. Keep each test focused enough that a failure points toward one behaviour. In a TypeScript project, keep the test file and source file in the project setup Vitest already uses.

amount.test.js
javascript
import { describe, expect, it } from 'vitest'
import { parseAmount } from './amount.js'

describe('parseAmount', () => {
  it('converts a positive numeric input', () => {
    const result = parseAmount('42.50')
    expect(result).toBe(42.5)
  })

  it('rejects a blank input', () => {
    expect(() => parseAmount('')).toThrow('positive number')
  })
})

Assertions such as toBe, toEqual, and toThrow express different kinds of expectations. Use strict equality for primitives and structural equality for objects or arrays. Prefer checking public outcomes over checking that a helper was called a particular number of times unless that interaction is itself important to the contract.

📌 Real World Example
An expense calculator should be tested for the total it returns, not for whether it used reduce. The implementation can later change to a loop without changing what users rely on.
// Part 03 — Test cases

Cover Boundaries and Decisions, Not Just Lines

Start from the rules the feature promises. For a numeric amount, that means a valid positive value, blank input, zero, negative values, and a value that cannot be represented as a finite number. One example per rule is usually more valuable than many nearly identical examples. Table-driven tests make related cases concise while preserving readable names.

amount.test.js
javascript
import { describe, expect, it } from 'vitest'
import { parseAmount } from './amount.js'

describe('parseAmount boundaries', () => {
  it.each([
    ['', 'blank'],
    ['0', 'zero'],
    ['-3', 'negative'],
    ['not-money', 'non-numeric'],
  ])('rejects %s (%s)', (input) => {
    expect(() => parseAmount(input)).toThrow()
  })
})

Do not copy every implementation branch into a test just to raise a counter. Think about decisions a user can observe: validation messages, saved state, response handling, or accessible feedback. Include a regression test when a bug has a small, reproducible example so the same failure is less likely to return.

// Part 04 — Async code

Wait for Promises and Assert Their Outcomes

A test that starts an asynchronous operation but does not return or await it can finish before the assertion runs. Mark the test callback async and await the function under test. For a rejection, assert that the promise rejects with an expected error. This makes Vitest know when the behavior has completed.

courses.test.js
javascript
import { expect, it, vi } from 'vitest'
import { loadCourses } from './courses.js'

it('returns parsed courses after a successful response', async () => {
  const fetchCourses = vi.fn().mockResolvedValue([
    { id: 'js', title: 'JavaScript' },
  ])

  await expect(loadCourses(fetchCourses)).resolves.toEqual([
    { id: 'js', title: 'JavaScript' },
  ])
})

it('reports a rejected request', async () => {
  const fetchCourses = vi.fn().mockRejectedValue(new Error('offline'))
  await expect(loadCourses(fetchCourses)).rejects.toThrow('offline')
})

Injecting a dependency such as fetchCourses makes the core logic easy to test without replacing a global. For code that calls the browser directly, mock the narrow boundary or use an integration test with a controlled network response. Restore mocks between cases when they change shared state.

⚠️ Important
A test that passes only because it runs after another test is unreliable. Reset mocks and isolate mutable state so each test can run alone and in a different order.
// Part 05 — Mock boundaries

Mock External Work, Not the Logic You Want to Test

A mock replaces a dependency with predictable behaviour. Use it for an API, clock, or storage boundary when the real dependency would make a unit test slow or nondeterministic. Keep the validation and decision-making code real; otherwise the test may only prove that your mock behaves as expected.

expense-service.test.js
javascript
import { beforeEach, expect, it, vi } from 'vitest'
import { saveExpense } from './expense-service.js'

beforeEach(() => {
  vi.restoreAllMocks()
})

it('persists a valid expense through the storage boundary', () => {
  const storage = { save: vi.fn() }
  const expense = { id: 'e-1', amount: 125, category: 'travel' }

  saveExpense(storage, expense)

  expect(storage.save).toHaveBeenCalledWith(expense)
})

The test checks the service contract at a boundary. If the requirement is that a real item survives serialization, add a focused integration test for that behavior rather than asserting many internal calls. Avoid excessive mocking: a fully mocked application can pass even when its parts cannot work together.

DependencyUseful test approachWatch out for
ClockInject a date or use controlled fake timersTests depending on the machine time zone or current day
NetworkInject a client or mock a specific responseUnrealistic mocks that do not match the real response shape
StorageUse a small fake for a unit test; real adapter for integrationTests sharing state between cases
Random valuesInject a deterministic generatorAssertions tied to accidental random output
// Part 06 — Organize the suite

Make the Test Command Predictable

Keep test files near their related source or in a consistent test directory. Use one naming convention, group related scenarios, and make sure the project test command is documented in its existing package scripts. A test suite should run without a developer needing to remember hidden setup steps. Do not add a competing runner to a project that has already standardized on one.

vitest.config.js
javascript
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'node',
    include: ['src/**/*.test.js'],
    clearMocks: true,
  },
})

Choose the environment that matches the tests. Pure functions and Node modules can run in a Node environment; browser-specific code may need a DOM test environment already configured by the application. Keep configuration aligned with the actual project rather than copying options without checking their purpose.

  1. Run the project test command once before editing and confirm how tests are discovered.
  2. Write one focused test for the expected behaviour and run that test during development.
  3. Run the full relevant suite after the change to catch interactions and shared-state mistakes.
  4. Review the failure output and fix the cause instead of weakening a meaningful assertion.
// Part 07 — Coverage and CI

Coverage Is a Map, Not a Quality Score

Coverage reports which code ran during tests. Line coverage shows executed lines; branch coverage can expose an untested decision path. High coverage does not guarantee useful assertions: a test can execute a line and never check its result. Use reports to find risky untested behavior, then decide whether a meaningful test is warranted.

In continuous integration, run the same deterministic test command used locally. A failing test should make the change visible before it reaches users. Keep tests independent of secrets, local machine files, and production services. If a test needs an external service, isolate it or provision a controlled test environment deliberately.

🎯 Pro Tip
Fix flaky tests rather than rerunning them until they pass. Flakiness erodes trust and can hide a real regression in a busy team.
// Part 08 — Pitfalls

Common Testing Mistakes

Asserting implementation details instead of outcomes

Why: A harmless refactor breaks the test even though behaviour is unchanged.

Fix: Assert the public return value, state, or user-visible behaviour.

Forgetting to await an asynchronous assertion

Why: The runner finishes before the promise settles.

Fix: Return or await every promise involved in the test.

Mocking every dependency

Why: The test no longer verifies that real parts work together.

Fix: Mock external boundaries and keep the behavior under test real.

Treating coverage percentage as proof of quality

Why: Executed code may have no meaningful assertion.

Fix: Review requirements and branch behavior, then add valuable assertions.

// Part 09 — Practice

Test a Reliable Expense Total

Practice

Build a small suite that protects real rules

  1. Create a pure totalExpenses function and test an empty list, one expense, and several expenses.
  2. Add validation tests for blank, zero, negative, and non-finite amounts.
  3. Test an async loader for both a successful response and a rejected network dependency.
  4. Mock only the storage boundary and assert the stored domain value, not private helper calls.
  5. Run the focused tests and then the full suite; inspect branch coverage for an untested decision.

Hint: Name tests as behaviour statements, so a failing report tells you which expectation changed.

🎯 Key Takeaways

  • ✓Tests are executable expectations that support safe change; they do not prove the absence of all defects.
  • ✓Use Arrange, Act, Assert and test observable behaviour rather than implementation details.
  • ✓Cover important boundary values and decisions, and await asynchronous work.
  • ✓Mock external or nondeterministic boundaries while keeping the logic under test real.
  • ✓Use coverage to discover gaps, not as a substitute for meaningful assertions.
  • ✓Keep tests isolated, deterministic, and runnable through the same command in local development and CI.

Next

What comes next

You can now protect individual behaviours with tests. Next, bring JavaScript, TypeScript, project structure, and testing together in a typed expense tracker, then practice explaining your decisions in interviews.

Lesson 14 · JavaScript Project and Interview Prep →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...