Well, you can save your time and energy by writing tests for your application that run whenever you add a new feature, all without leaving your IDE during development. This will help you be confident that each feature works as expected.

In this guide, I'll help you build confidence through code: you'll learn how to validate APIs with tests first, then confirm the results in Postman or any other API testing tool.

Prerequisites

• Node.js & Express basics: You should have a working knowledge of Node.js and Express (or a similar library like fastify), including how to build and run a simple API.

• Working knowledge of TypeScript: The code snippets in this guide are written using TypeScript, so you should have a solid understanding of TypeScript basics.

• Basic familiarity with MongoDB: Helpful but not required. The examples in this guide use MongoDB for demonstration purposes, but the underlying logic applies to any database or data layer. Only the tooling differs.

• Hands-on API experience: Prior experience writing at least one backend API with Express will help you follow along more effectively.

• Curiosity and motivation: A willingness to deepen your backend skills by learning how to write and run tests for your APIs.

• Environment setup: Node.js version 20 or higher installed on your machine.

Table of Contents

• Prerequisites

• Testing Concept

• Unit testing

• Comparison between unit and integration tests

• Summary

You can find all the code snippets used in this guide in this Git repository. Each example has its own branch, and they're combined into a main branch if you want a full example version. Please consider starring the repository if you find it helpful.

Key Testing Concepts

Testing helps you build confidence in your codebase. You wrie code that tests other code in your application, or code that checks if a function or feature behaves the way that it should.

In this guide, we'll cover two types of testing:

• Unit testing: This is the most basic type of testing and, in my opinion, the easiest. You test a single piece of code in isolation to see how it behaves.

• Integration testing: This approach is used to test how different parts of the application are integrated to make sure they're working together as intended.

Key Testing Terms

Throughout this guide, I'll be using some technical terms are related to testing which I want to explain up front:

• Mocking: mocking is a technique used to make a fake implementation of a real function call.

• Spying: spying is a way of inspecting a function to see, for example, if the function is called with a certain type of argument or how many times it's been called.

• Assertion: assertions check to see if the output you're getting matches the expected output.

Alright now that we have that covered, let's go over some basics of testing so you have the best practices down before we start writing tests.

How to Name a Test File

Make sure your test files follow one of these naming conventions:

• filename.test.ts

• filename.spec.ts

• filename.test.js

• filename.spec.js

Both the spec and test keyword in a file name makes it possible to run the test file. They also help testing frameworks run the right file.

You can choose either the TypeScript or JavaScript extension on a file based on which language you're using to write the test. For this guide I'm using TypeScript so I'll be using the TypeScript (.ts) test file version.

Parts of a Testing File

Typically, a test file will have four main parts that you should be familiar with, which are:

• describe: Used to describe which test you're going to write.

• it: Used to specify a condition that a function must pass when tested against.

• expect: Used to determine what type of results you're expecting when you call a function that's being tested

• matchers: These are different method available on the expect keyword that we use to evaluate if the function we're testing returns a value that meets the expected data or value.

Example of a test file:

import { describe, it, expect } from "vitest";
import validateEmail from "../utils/email-validation";

describe("email validation test suites", () => {
  it("must define email validation function", () => {
    expect(validateEmail).toBeDefined();
  });
});

The above snippet tests if the validateEmail function is defined.

In this test file:

• We use describe to specify the description of the test. describe receives a string description of the test and a function to handle different test cases.

• The it keyword specifies and defines a test for a function you're testing, it receives a string describing a specific test description and a callback function to execute and handle test assertion.

• Then expect uses the function return type to check if it matches a specific condition through the toBeDefined matcher method.

List of Matchers:

There are many matchers available to you. Below are a few of them:

• toBe: compares the passed-in value to see if it matches the function's returned value. It's used on primitive data types like strings, numbers, and so on.

• toEqual: compares the passed-in value to see if it matches the function's returned value. It's used on non-primitive data types like objects, arrays, and so on.

• toThrow: used on a function that threw an error to check if the function threw expected error object or instance.

• toBeCalledWith: used to check if a function is called with a given parameter.

• toBecalledOnce: used to check if a function is called only once.

• toBeDefined: used to check if a function is defined.

• toBeUndefined: used to check if a function returns an undefined value.

• toBeTruthy: used to check if a function returns a true Boolean value.

• toBeFalsy: used to check if a function returns a false Boolean value.

These are few of the many matchers out there.

Vitest Installation

Now that you know some testing basics, we can get into the actual tests. We'll start by installing vitest, the framework that we'll use to run and write tests for our application.

You can choose your preferred package manager to use to install vitest from the list below:

pnpm add -D vitest # for pnpm package manager
npm install -D vitest # for npm package manager
yarn add -D vitest # for yarn package manager
bun add -D vitest # for bun package manager

Unit Testing

A unit test focuses on testing a small piece of code in isolation in your application. A simple example could be if you have a function that adds contact info to a database. For the test, you could check if the email is valid before adding the contact to the database.

Let's start by testing a simple email validation function so you can get comfortable with how unit tests works and how to write one:

export default function validateEmail(email: string) {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

  if (regex.test(email)) {
    return true;
  } else {
    throw new Error("Invalid email format");
  }
}

The above snippet exports a function that receives an email and then uses regex to validate if the email is valid. It throws an error if the email is invalid.

Tests for the validateEmail Function

Let's start by checking if validateEmail returns true for correct emails:

import { describe, it, expect } from "vitest";
import validateEmail from "../utils/email-validation";

describe("email validation test suites", () => {

  it("returns true for valid email", () => {
    const sampleEmail = "arnoldjabo@gmail.com";
    expect(validateEmail(sampleEmail)).toBeTruthy();
  });

});

In the above test, we're creating a variable sampleEmail to be used as a sample email in the validateEmail function. Save this and then run npx vitest in your terminal. You should see a terminal with the results of your test. It should look like the below screenshot:

When you run tests, Vitest shows the list of test files you're testing, how many tests were executed, and how many passed and failed tests you have.

Let's create another test that detects an invalid email:

import { describe, it, expect } from "vitest";
import validateEmail from "../utils/email-validation";

describe("email validation test suites", () => {

    it("throws error for invalid email", () => {
    const sampleEmail = "verymasd.com";
    const invalidEmailResults = () => validateEmail(sampleEmail);
    expect(invalidEmailResults).toThrow("Invalid email format");
  });

});

For functions that throw errors, you need to wrap them inside another function to prevent them from stopping the test before the test reaches the assertion or expect section.

In our example above, the validateEmail function is wrapped inside another function which will hold whatever the error validateEmail throws is. It then assigns it to the invalidEmailResults variable. Next we use the toThrow matcher on the expect assertion to match a type of error validateEmail expects to be thrown for an invalid email.

If your run the test, you'll have two passed tests now:

If you didn't wrap the validateEmail function inside another function when it throws an error, you'll see something like this when you run the test:

As you can see, the error fires before reaching the test final assertion. So when you have a function that throws errors, remember to wrap your function inside another function to avoid throwing errors mid-test.

Tip: When writing unit tests, focus on the expected input and output of a function. You don't have to worry or need to think about the implementation of the function: the input and output are the key elements here.

Testing API Calls

By now you should understand how a unit test works. So next, let's see how you can unit test an API that makes a call to a database.

import Contacts from "../../schema/contactList";
import { Request, Response } from "express";
import validateEmail from "../../utils/email-validation";

async function addContacts(req: Request, res: Response) {
  const { contactName, phoneNumber, email } = req.body;
  validateEmail(email);

  const contact = await Contacts.create({ contactName, phoneNumber, email });

  return res.status(201).json({ message: `successfully created ${contact.contactName}` });
}

export default addContacts;

In the code snippet above, we have a function that creates a contact with the database. It also validates if the passed email is valid.

In this example, we're using mongo DB for the database and Mongoose for connecting the codebase with our mongo DB instance.

Unit tests for non-pure functions (that is, functions that are dependent on external services, like making API calls or calling other functions) are tested a bit differently.

For these cases, you create a mock or fake version of the original function that makes a call to the external service and then define its behavior to match the expected return value that you'd have if you used its real version.

We'll start by mocking the implementation of the email validation function. This will help solidify the understanding on how mocking works in unit testing and testing in general.

Note: mocking the validateEmail function isn't that important because it doesn't make a big difference from using the email validation function directly here. But for learning purposes, we'll mock it to help you understand how it works.

When mocking the modules import, we use the vi.mock function which helps transform the imports of a given module into mocks or fake versions of the real ones.

vi.mock(filepath,callback);

vi.mock receives two arguments: the file path location of the module you want to mock, and a callback function called a factory function which we'll use to transform the module imports into mocks.

Let's start by mocking the validateEmail path and creating a factory function to transform the module into mocks:

vi.mock("../utils/email-validation", () => {
  return { default: vi.fn()};
});
import validateEmail from "../utils/email-validation";

In the callback function (factory function), we then return an object of the exported module, with a key of default and a value of vi.fn. For function mocking we use vi.fn() which automatically replaces the function's return value with undefined.

We use default as a key because the validateEmail function is exported as a default export. If it was a named export, we would have used the actual export name instead of default in the return object.

vi.mock("../utils/email-validation", () => {
  return { validateEmail: vi.fn() };
});
import { validateEmail } from "../utils/email-validation";

Always import your module after the mock module operation to avoid using the real module.

There are methods on vi.fn() that help define the implementation and behaviors of the mocked function. Some of these methods include:

• mockReturnValue: Used to define a return value for a mocked function

• mockRejectsValue: Used for promise-based functions to define the error the function will return.

• mockResolveValue: Used for promise-based functions to define the data the function will return.

• mockImplementation: Used to define a new function behavior of a mocked function.

• mockReturnThis: Used to return the actual instance of a function you're mocking.

These are the methods that you'll likely use most of the time when defining mock implementation and setting mock return value. Just keep in mind that there are many others.

Here, for emailValidate, we'll be using the mockReturnValue and mockImplementation methods.

Let's use mockReturnValue to make the validateEmail function return true by default, assuming the email will be formatted correctly:

vi.mock("../utils/email-validation", () => {
  return { default: vi.fn().mockReturnValue(true) };
});
import validateEmail from "../utils/email-validation";

We define a mock function with vi.fn and then chain on the mockReturnValue(true) to change the mock function default return value (undefined) to true in our case.

Defining the Mocking Implementation

You can do a lot with a mocked function, like defining a new implementation for the mocked function that replaces existing logic in the original function.

Let's create a test suite with a fake email that throws an error when you pass the wrong email while creating contacts.

import { describe, expect, it, vi } from "vitest";
import mockinggoose from "mockingoose";
import Contacts from "../schema/contactList";
import addContacts from "../src/controllers/add-contacts.controller";

import { type Response, type Request } from "express";

vi.mock("../utils/email-validation", () => {
  return { default: vi.fn().mockReturnValue(true) };
});

import validateEmail from "../utils/email-validation";

const fakeContact = {
  contactName: "arnold",
  phoneNumber: 798600102,
  email: "arnoldjabo@gmail.com",
};

describe("Add contacts to the database", async () => {
  it("throws error for the wrong email address", async () => {
    const req = {
      body: { ...fakeContact, email: "fakemail" },
    } as Request;  

    const res = {
      status: vi.fn().mockReturnThis(),
      json: vi.fn(),
    } as any as Response;

    (validateEmail as ReturnType<typeof vi.fn>).mockImplementation(() => {
      throw new Error("invalid email!");
    });
 
    await expect(addContacts(req, res)).rejects.toThrow();
  });
});

In the snippet above, we're mocking or creating a fake request object that's cast as request type of express. We do the same with the response object – but the difference here is that with response we're also creating mocks for common methods that you'd use on an Express response (which are status and a json object).

We then turn the return type of the validateEmail function into the vitest mocking function type to avoid TypeScript warnings. Then we use the mockImplementation method to throw a new error inside validateEmail.

The assertion works differently because now we're throwing a promise-based error. We use rejects on the assertion and then chain on another matcher that stimulates which type of error the function will throw.

Tip: when working with TypeScript, the response object can't be cast like we did on the request object because the response object is much stricter than request. So you'll first need to cast it as any and then cast back to the response object. That way you avoid the TypeScript warning while still keeping the type in play for your test code.

Mocking a Mongoose Model

With unit tests, we don't want to save test data to a real database. Instead we can fake the implementation of the service that calls the database service – in our case, we can use the create method from Mongoose. It'll save the record to a Mongo database. We can then define what it should return on success (and it should look identical to what it would return if we were using a real database).

We'll start by installing a library for mocking a Mongoose model called mockingoose:

pnpm add -D mockingoose # for pnpm package manager
npm install -D mockingoose # for npm package manager
yarn add -D mockingoose # for yarn package manager
bun add -D mockingoose # for bun package manager

After installation we'll create a mock for our contacts model:

import { describe, expect, it, vi } from "vitest";
import mockinggoose from "mockingoose";
import Contacts from "../schema/contactList";

const fakeContact = {
  contactName: "arnold",
  phoneNumber: 798600102,
  email: "arnoldjabo@gmail.com",
};

describe("Add contacts to the database", async () => {
  it("successfully create a new contact to the database", async () => {
    mockinggoose(Contacts).toReturn(fakeContact, "save");
  });

});

To mock a Mongoose model, we call the mockinggoose() function and pass the model to mock. Then we use the toReturn matcher to describe what it should return, toReturn matcher expects two arguments.

Those arguments are a fake dataset for the model and a Mongo method that we'll use to work with the data. For our example we'll use save because we're creating records in the document.

Unit Testing the API

We can start by writing the first test for the add contact API call like this:

import { describe, expect, it, vi } from "vitest";
import mockinggoose from "mockingoose";
import Contacts from "../schema/contactList";
import addContacts from "../src/controllers/add-contacts.controller";
import { type Response, type Request } from "express";

vi.mock("../utils/email-validation", () => {
  return { default: vi.fn().mockReturnValue(true) };
});

import validateEmail from "../utils/email-validation";

const fakeContact = {
  contactName: "arnold",
  phoneNumber: 798600102,
  email: "arnoldjabo@gmail.com",
};

describe("Add contacts to the database", async () => {
  it("successfully create a new contact to the database", async () => {
    mockinggoose(Contacts).toReturn(fakeContact, "save");

    const req = {
      body: fakeContact,
    } as Request;

    const res = {
      status: vi.fn().mockReturnThis(),
      json: vi.fn(),
    } as any as Response;

    await addContacts(req, res);
    expect(res.status).toHaveBeenCalledWith(201);
    expect(res.json).toHaveBeenCalledWith({
      message: `successfully created ${fakeContact.contactName}`,
    });
  });
 });

For this test assertion, we're using different matchers called spies. These are used on a function to inspect how many times it's been called or which parameters were used to call it (and so on).

Here we're expecting the status function of response to be called with a status of 201 as its argument. Then the JSON object is called with a message argument that we're using to send out the response.

Integration Tests

Integration tests test the communication and integration of different parts of an application. For example, they might check if your database integrates well with the function that makes the API call to the database.

Unlike unit tests (where we don't need to have our test making API calls), with integration tests we're testing if parts of the application integrate together and works as expected. We don't need to mock anything, because we want to make sure that we're successfully sending a request to the backend and connecting to the database.

Creating Integration Test Data Storage

When you're running integration tests, there are two ways to create a testing environment that acts as a database. They include:

• Creating a duplicate schema of your real database and using the copy as a testing database environment. Whenever you're running tests, you point your database connectivity to the test DB.

• Creating in-memory database storage. This approach doesn't require you to have two separate schemas (one for testing and another for production). Instead you construct the same schema shape in your codebase memory and use it as your testing environment.

Using the first approach is complicated because you have to set up and configure which database to use for which environment. But for the second approach, you can just set up the right schema structure as the original schema and use it for testing without needing to configure it in the database and remove it after use.

For Mongo DB there's a package that simplifies the in-memory storage option for us called mongodb-memory-server. It deletes all the data that was used for testing after the tests have finished running.

How to Set Up the Environment for the Integration Tests

You'll need to install:

• supertest: a package that helps you make API calls/requests and returns back the response when testing.

• mongodb-memory-server: a package that makes in memory database storage for testing data.

# command for pnpm package manager
pnpm add -D mongodb-memory-server supertest @types/supertest

# command for npm package manager
npm install --save-dev mongodb-memory-server supertest @types/supertest

# command for yarn package manager
yarn add --dev mongodb-memory-server supertest @types/supertest

# command for bun package manager
bun add -d mongodb-memory-server supertest @types/supertest

Before moving on, we need to change the setup of our server entry file.

If you've been using Express with Node or any other framework, you may be familiar with the following type of setup for the server entry file where everything is added into a single file:

import express from "express";
import { loadEnvFile } from "node:process";
import connectToDB from "../config/dbConfig";
import addContacts from "./controllers/add-contacts.controller";

const app = express();
loadEnvFile();
async function dbConnection() {
  await connectToDB();
}
dbConnection();

app.use(express.json());
app.post("/add-contacts", addContacts);
app.listen(5000, () => console.log("the server successfully connected"));

This setup works fine and it's valid in certain cases. But when working with integration tests, it can be problematic. This is because in integration tests, we'll need an instance of Express to use when making the request. If we export the app variable here inside the main file when we make a request while testing, the production DB connection will conflict with the testing DB connection. This'll cause the tests to stop working.

The solution here is create another file, define an Express instance, and export it. Then we'll use the exported Express instance in the server to start a server. The setup looks like this:

app.ts

import express from "express";
import addContacts from "./controllers/add-contacts.controller";

const app = express()

app.use(express.json())
app.post("/add-contacts", addContacts);

export default app;

Then the main file server.ts or main.ts uses the app variable like this:

import { loadEnvFile } from "node:process";
import connectToDB from "../config/dbConfig";
import app from "./app";

loadEnvFile();

async function bootsrap() {
  await connectToDB();
  app.listen(5000, () => console.log("the server successfully connected"));
}
bootsrap();

We're importing the Express instance from the app file and then using the bootstrap() function to set up the database and start the server. With this in place, we can start writing integration tests for the addContact module.

How to Write the Integration Tests

Tip: With integration test(s) you can name your file like filename.integration.test.ts this is the most commonly used naming convention for integration tests, but it is not mandatory it just a naming convention.

You first need to set up the database testing data storage using the mongoose and mongdb-memory-server packages and the Express instance for making requests.

import { afterAll, beforeAll, describe, expect, it } from "vitest";

import { MongoMemoryServer } from "mongodb-memory-server";
import mongoose from "mongoose";
import app from "../src/app";


describe("intergration test setup for add contact api", () => {
  let mongoServer: MongoMemoryServer;
  let server: any;

  beforeAll(async () => {
    mongoServer = await MongoMemoryServer.create();
    const uri = mongoServer.getUri();
    await mongoose.connect(uri);
    server = app.listen(0);
  });

  afterAll(async () => {
    mongoServer.stop();
    mongoose.disconnect();
    server.close();
  });
});

The beforeAll and afterAll functions are vitest functions. beforeAll runs before any test starts executing and afterAll will run after all tests are done executing.

In the test, we set up the database and Express instance before any test runs.

First, we created the mongoServer variable. Then, inside the beforeAll block, we initialize it with MongoMemoryServer.create to create an in-memory database for testing data storage. We get the connection string using the uri variable using the getUri method. Finally we use Mongoose to connect to the generated in-memory connection string.

The server variable is assigned to the Express instance listening to port 0, but you can use any port number of your choice – it's just for demonstration purposes. This creates an Express instance for our testing environment.

In afterAll, after all tests have finished executing, we close the server and in-memory DB and then also disconnect our Mongoose instance.

Within the same describe block, we then add the test description and assertion (same as we did in unit testing):

import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { MongoMemoryServer } from "mongodb-memory-server";
import mongoose from "mongoose";
import app from "../src/app";
import request from "supertest";
import Contacts from "../schema/contactList";

describe("intergration test for add contact api", () => {
  /*
    Here we do server setup and database in memory setup that was discussed,
    in the previous snippets for setting up integration data storage testing environment 
   */
  const fakeContact = {
    contactName: "arnold",
    phoneNumber: 798600102,
    email: "arnoldjabo@gmail.com",
  };

  describe("POST /add-contacts", () => {
    it("creates a new record to the database", async () => {
      const response = await request(app)
        .post("/add-contacts")
        .send(fakeContact);

       const contactList = await Contacts.findOne({
        email: "arnoldjabo@gmail.com",
      })!;
      expect(contactList?.email).toBe("arnoldjabo@gmail.com");
      console.log(contactList);

      expect(response.status).toBe(201);
      expect(response.body).toEqual({
        message: `successfully created ${fakeContact.contactName}`,
      });
    });
  });
});

Here in the test file, we're describing the test as a post method test for the add-contact endpoint. Then we test if it adds data to the database.

Within the it body, we use request from supertest to make a request to the server we've created. We also chain on an HTTP method with the endpoint we want to test.

For methods that send data to the backend like POST, PATCH, or PUT, we use the send() method on request to add an object of the data that we're sending.

We'll use the response to assert what the response could look like. For example, we're expecting the server to give a status code of 201 on successful data entry and a JSON object with a message property that confirms that it has added a contact.

We're using an assertion to check if the response's status matches what we expect, as well as if the response body matches the expected message we should be getting.

To test if the data are really being added to the database, I've added contactList to get the contact we just added by finding it by email. Then we log the contactList to the console to show how in-memory works. It's pretty much the same as a real Mongo DB instance. If we were to run the tests, we would have something that looks like this:

You can see from the console the in-memory stores and retrieves data as a regular Mongo database does.

When to Use Unit vs Integration Tests

So when do you use each type of test?

Use unit tests when you have pure functions like the email validation example we had earlier.

And use Integration tests for functions that makes external API calls that are dependent on external service like database calls to avoid mocking every function that you're importing.

Summary

This guide explains how two types of testing work: unit tests and integration tests.

Unit tests are code that tests specific pieces of your codebase in isolation, and are best for pure functions. Integration test are code that tests successful integration and communication between parts of your application, and they're best for non-pure functions.

If you found the article helpful, you can buy me coffee.

In this tutorial, you’ll learn how to set up Vitest in a React project, write effective tests for your components and hooks, and understand the testing patterns that will help you build more reliable applications.

Table of Contents

• What is Vitest and Why Should You Use It?

• Prerequisites

• How to Set Up Vitest in Your React Project

• How to Write Your First Test

• How to Test React Components

• How to Test User Interactions

• How to Test Custom Hooks

• How to Mock API Calls

• Best Practices for Testing React Components

What is Vitest and Why Should You Use It?

Vitest is a testing framework built on top of Vite. It uses Vite’s development server and plugin pipeline to transform and load files during testing. This means your tests use the same configuration and plugins as your app (for example, the React plugin, TypeScript support,and so on), so you don’t need a separate build or compile step.

Vitest runs tests in parallel across worker threads for maximum speed, and it automatically enables an instant “watch” mode (similar to Vite’s HMR) that reruns only the tests related to changed files. Vitest also has first-class support for modern JavaScript out of the box: it handles ESM, TypeScript, and JSX natively via Vite’s transformer (powered by Oxc).

Because Vitest provides a Jest-compatible API, you can continue to use familiar testing libraries (for example, React Testing Library, jest-dom matchers, user-event, and so on) without extra setup.

In short, Vitest tightly integrates with your Vite-powered stack (or can even run standalone) and lets you plug in existing testing tools seamlessly.

Here is why Vitest has become popular in the React ecosystem:

• Speed: Vitest can run tests more than four times faster than Jest in many scenarios. This speed comes from Vite's fast Hot Module Replacement and efficient caching capabilities.

• Zero configuration: Unlike Jest, which required Babel integration, TSJest setup, and multiple dependencies, Vitest works out of the box. It reuses your existing Vite configuration, eliminating the need to configure a separate test pipeline.

• Native TypeScript support: Vitest handles TypeScript and JSX natively through ESBuild, with no additional configuration needed.

• Modern JavaScript: Vitest offers native support for ES modules out of the box, making it ideal for modern JavaScript stacks.

• Familiar API: If you know Jest, you already know most of Vitest. The API is intentionally compatible, making migration straightforward.

Prerequisites

To follow along with this tutorial, you should have:

• Basic knowledge of React and JavaScript

• Understanding of React Hooks

• Node.js installed (version 14 or higher)

• A React project created with Vite (or you can create one as we go)

How to Set Up Vitest in Your React Project

Let's start by creating a new React project with Vite and setting up Vitest.

Step 1: Create a React Project with Vite

If you don't have an existing project, create one with the following command:

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

This creates a React project with Vite as the build tool.

Step 2: Install Vitest and Testing Dependencies

Install Vitest along with the React Testing Library and other necessary dependencies:

npm install --save-dev vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom

Here's what each package does:

• vitest: The testing framework itself

• @testing-library/react: Provides utilities for testing React components

• @testing-library/jest-dom: Adds custom matchers for DOM assertions

• @testing-library/user-event: Simulates user interactions

• jsdom: Provides a DOM environment for testing

Step 3: Configure Vitest

Create a vitest.config.js file in your project root:

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './src/test/setup.js',
  },
});

Setting globals: true exposes the describe and it functions on the global object, so you don't need to import them in every test file. The environment: 'jsdom' setting tells Vitest to use jsdom for simulating a browser environment.

Step 4: Create the Test Setup File

Create a file at src/test/setup.js:

import { expect, afterEach } from 'vitest';
import { cleanup } from '@testing-library/react';
import '@testing-library/jest-dom';

afterEach(() => {
  cleanup();
});

The cleanup() function runs after each test to clean up the DOM, ensuring tests don't interfere with each other.

Step 5: Add Test Scripts

Add the following script to your package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest",
    "test:ui": "vitest --ui",
    "coverage": "vitest --coverage"
  }
}

Now you can run tests with npm test.

How to Write Your First Test

Let's write a simple test to make sure everything is working. Create a file called sum.test.js in your src directory:

import { expect, test } from 'vitest';

function sum(a, b) {
  return a + b;
}

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

Run npm test and you should see your test pass. A test in Vitest passes if it doesn't throw an error.

How to Test React Components

Now let's test an actual React component. We'll start with a simple component and gradually build up to more complex scenarios.

Testing a Simple Component

Create a component called Greeting.jsx:

export function Greeting({ name }) {
  return (
    <div>
      <h1>Hello, {name}!</h1>
      <p>Welcome to our application</p>
    </div>
  );
}

Now create a test file Greeting.test.jsx:

import { render, screen } from '@testing-library/react';
import { Greeting } from './Greeting';

describe('Greeting Component', () => {
  it('should render the greeting with the provided name', () => {
    render(<Greeting name="Alice" />);

    const heading = screen.getByRole('heading', { level: 1 });
    expect(heading).toHaveTextContent('Hello, Alice!');
  });

  it('should render the welcome message', () => {
    render(<Greeting name="Bob" />);

    const paragraph = screen.getByText('Welcome to our application');
    expect(paragraph).toBeInTheDocument();
  });
});

The describe function groups related tests into a single describe block. Each it function contains one test case.

The render function from React Testing Library renders your component in a test environment. The screen object provides query methods to find elements in the rendered output.

Understanding Query Functions

React Testing Library provides three types of query functions: get, query, and find.

getBy queries: Throw an error if the element isn't found. Use these when you expect the element to be present.

const button = screen.getByRole('button', { name: /click me/i });

queryBy queries: Return null if the element isn't found. Use these when you want to assert that an element doesn't exist.

const errorMessage = screen.queryByText('Error');
expect(errorMessage).not.toBeInTheDocument();

findBy queries: Return a promise and wait for the element to appear. Use these for asynchronous operations.

const loadedData = await screen.findByText('Data loaded');

Testing a Counter Component

Let's test a more interactive component. Create Counter.jsx:

import { useState } from 'react';

export function Counter({ initialCount = 0 }) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
      <button onClick={() => setCount(count - 1)}>Decrement</button>
      <button onClick={() => setCount(0)}>Reset</button>
    </div>
  );
}

Create the test file Counter.test.jsx:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Counter } from './Counter';

describe('Counter Component', () => {
  it('should render with initial count of 0', () => {
    render(<Counter />);

    expect(screen.getByText('Count: 0')).toBeInTheDocument();
  });

  it('should render with custom initial count', () => {
    render(<Counter initialCount={5} />);

    expect(screen.getByText('Count: 5')).toBeInTheDocument();
  });

  it('should increment count when increment button is clicked', async () => {
    const user = userEvent.setup();
    render(<Counter />);

    const incrementButton = screen.getByRole('button', { name: /increment/i });
    await user.click(incrementButton);

    expect(screen.getByText('Count: 1')).toBeInTheDocument();
  });

  it('should decrement count when decrement button is clicked', async () => {
    const user = userEvent.setup();
    render(<Counter initialCount={5} />);

    const decrementButton = screen.getByRole('button', { name: /decrement/i });
    await user.click(decrementButton);

    expect(screen.getByText('Count: 4')).toBeInTheDocument();
  });

  it('should reset count to 0 when reset button is clicked', async () => {
    const user = userEvent.setup();
    render(<Counter initialCount={10} />);

    const resetButton = screen.getByRole('button', { name: /reset/i });
    await user.click(resetButton);

    expect(screen.getByText('Count: 0')).toBeInTheDocument();
  });
});

In these Counter tests, we first use render(<Counter />) to mount the component in a virtual DOM. We then query the output using Testing Library’s screen object. For example, screen.getByText('Count: 0') finds the element displaying the initial count of 0, and expect(...).toBeInTheDocument() asserts that it is present. The getByText query will throw an error if the text isn’t found, immediately failing the test.

For interactive tests, we create a user with const user = userEvent.setup() and then call await user.click(...) on the increment/decrement/reset buttons. The userEvent.click method simulates a real user click (dispatching the sequence of events a browser would fire). We locate buttons by their accessible role and name (for example, getByRole('button', { name: /increment/i })), following best practices for accessible queries.

After each click, we assert that the DOM updates accordingly (for example, the count text changes to “Count: 1”). Using async/await with user.click ensures the test waits for any state changes. In this way, each test checks the user-visible behavior: that clicking the Increment button increases the count, the Decrement button decreases it, and the Reset button sets it back to zero, without depending on the component’s internal implementation.

How to Test User Interactions

User interactions are a critical part of testing React applications. The @testing-library/user-event library provides a more realistic simulation of user behaviour than simple event dispatching.

Testing Form Inputs

Create a LoginForm.jsx component:

import { useState } from 'react';

export function LoginForm({ onSubmit }) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();

    if (!email || !password) {
      setError('Both fields are required');
      return;
    }

    setError('');
    onSubmit({ email, password });
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
      </div>
      <div>
        <label htmlFor="password">Password</label>
        <input
          id="password"
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
        />
      </div>
      {error && <p role="alert">{error}</p>}
      <button type="submit">Log In</button>
    </form>
  );
}

Create the test file LoginForm.test.jsx:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

describe('LoginForm Component', () => {
  it('should render email and password inputs', () => {
    render(<LoginForm onSubmit={() => {}} />);

    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
  });

  it('should update input values when user types', async () => {
    const user = userEvent.setup();
    render(<LoginForm onSubmit={() => {}} />);

    const emailInput = screen.getByLabelText(/email/i);
    const passwordInput = screen.getByLabelText(/password/i);

    await user.type(emailInput, 'test@example.com');
    await user.type(passwordInput, 'password123');

    expect(emailInput).toHaveValue('test@example.com');
    expect(passwordInput).toHaveValue('password123');
  });

  it('should show error when form is submitted empty', async () => {
    const user = userEvent.setup();
    const mockSubmit = vi.fn();
    render(<LoginForm onSubmit={mockSubmit} />);

    const submitButton = screen.getByRole('button', { name: /log in/i });
    await user.click(submitButton);

    expect(screen.getByRole('alert')).toHaveTextContent('Both fields are required');
    expect(mockSubmit).not.toHaveBeenCalled();
  });

  it('should call onSubmit with form data when valid', async () => {
    const user = userEvent.setup();
    const mockSubmit = vi.fn();
    render(<LoginForm onSubmit={mockSubmit} />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /log in/i }));

    expect(mockSubmit).toHaveBeenCalledWith({
      email: 'test@example.com',
      password: 'password123',
    });
  });
});

The LoginForm tests similarly use render and screen to interact with the component. We use screen.getByLabelText(/email/i) and screen.getByLabelText(/password/i) to find the input fields by their associated labels, mimicking how users identify form fields.

To simulate typing, we use await user.type(input, text), which sends real keyboard events to the input (via user-event). After typing, we assert the input’s value with expect(input).toHaveValue(...) (a custom matcher from jest-dom).

When submitting the form empty, clicking the Log In button triggers the form’s validation and displays an error message. We find this error by querying getByRole('alert') and check its text content. We also assert that the mock onSubmit handler was not called.

In the valid submission test, we fill both fields and click Log In; then expect(mockSubmit).toHaveBeenCalledWith({...}) verifies the submit handler received the correct { email, password } object.

These tests focus on user actions and outcomes: typing and clicking drive the form logic, and our assertions confirm the expected outputs (visible error text or the callback arguments).

How to Test Custom Hooks

Custom hooks encapsulate reusable logic, and they need testing just like components. React Testing Library provides a renderHook function specifically for this purpose.

Creating and Testing a Custom Hook

Create a custom hook useFetch.js:

import { useState, useEffect } from 'react';

export function useFetch(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        setLoading(true);
        const response = await fetch(url);

        if (!response.ok) {
          throw new Error('Network response was not ok');
        }

        const json = await response.json();
        setData(json);
        setError(null);
      } catch (err) {
        setError(err.message);
        setData(null);
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, [url]);

  return { data, loading, error };
}

Create the test file useFetch.test.js:

import { renderHook, waitFor } from '@testing-library/react';
import { useFetch } from './useFetch';

describe('useFetch Hook', () => {
  beforeEach(() => {
    global.fetch = vi.fn();
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it('should return loading state initially', () => {
    global.fetch.mockImplementation(() => 
      Promise.resolve({
        ok: true,
        json: async () => ({ data: 'test' }),
      })
    );

    const { result } = renderHook(() => useFetch('https://api.example.com/data'));

    expect(result.current.loading).toBe(true);
    expect(result.current.data).toBe(null);
    expect(result.current.error).toBe(null);
  });

  it('should return data when fetch succeeds', async () => {
    const mockData = { id: 1, title: 'Test Post' };

    global.fetch.mockImplementation(() =>
      Promise.resolve({
        ok: true,
        json: async () => mockData,
      })
    );

    const { result } = renderHook(() => useFetch('https://api.example.com/posts/1'));

    await waitFor(() => expect(result.current.loading).toBe(false));

    expect(result.current.data).toEqual(mockData);
    expect(result.current.error).toBe(null);
  });

  it('should return error when fetch fails', async () => {
    global.fetch.mockImplementation(() =>
      Promise.resolve({
        ok: false,
      })
    );

    const { result } = renderHook(() => useFetch('https://api.example.com/posts/1'));

    await waitFor(() => expect(result.current.loading).toBe(false));

    expect(result.current.data).toBe(null);
    expect(result.current.error).toBe('Network response was not ok');
  });
});

The renderHook function from React Testing Library renders custom hooks, and waitFor is used to wait for asynchronous state updates in the hook.

How to Mock API Calls

When testing components that make API calls, you don't want to hit real endpoints. Mocking ensures your tests are fast, reliable, and don't depend on network conditions.

Mocking with Vitest

Vitest doesn’t auto-mock modules like Jest does, so you need to manually mock them. Let's see how to mock an Axios call.

Create a PostsList.jsx component:

import { useState, useEffect } from 'react';
import axios from 'axios';

export function PostsList() {
  const [posts, setPosts] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchPosts = async () => {
      try {
        const response = await axios.get('https://api.example.com/posts');
        setPosts(response.data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchPosts();
  }, []);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Create the test file PostsList.test.jsx:

import { render, screen, waitFor } from '@testing-library/react';
import axios from 'axios';
import { PostsList } from './PostsList';

vi.mock('axios');

describe('PostsList Component', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should display loading state initially', () => {
    axios.get.mockImplementation(() => new Promise(() => {}));
    render(<PostsList />);

    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('should display posts when API call succeeds', async () => {
    const mockPosts = [
      { id: 1, title: 'First Post' },
      { id: 2, title: 'Second Post' },
    ];

    axios.get.mockResolvedValue({ data: mockPosts });
    render(<PostsList />);

    await waitFor(() => {
      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
    });

    expect(screen.getByText('First Post')).toBeInTheDocument();
    expect(screen.getByText('Second Post')).toBeInTheDocument();
  });

  it('should display error when API call fails', async () => {
    axios.get.mockRejectedValue(new Error('Network error'));
    render(<PostsList />);

    await waitFor(() => {
      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
    });

    expect(screen.getByText(/error/i)).toBeInTheDocument();
  });
});

In these tests, we verify specific UI states: the “loading” test checks that a loading indicator shows while data is being fetched, the “success” test confirms that post items render when the API returns data, and the “error” test makes sure an error message appears if the call fails.

We mock Axios by calling vi.mock('axios') and then using methods like mockResolvedValue(...) on axios.get to simulate a successful response (and mockRejectedValue(...) to simulate a failure). This kind of mocking isolates our tests from real network calls (making them fast and reliable) and lets us control exactly what data or error the hook receives.

We use await waitFor(...) to pause the test until those asynchronous updates complete before making assertions. Finally, we use screen.getByText(...) to find elements that should be present (it will throw an error if they’re missing) and screen.queryByText(...) to check that elements aren’t present (it returns null if the element is not in the DOM).

Mocking Specific Module Functions

Sometimes you only want to mock specific functions while keeping the rest of a module's behaviour intact. Here's how to do that:

vi.mock('date-fns', async () => {
  const original = await vi.importActual('date-fns');
  return {
    ...original,
    format: vi.fn(() => '2025-01-01'),
  };
});

In Vitest, you use vi.importActual to retain all original methods while mocking only the format method.

Best Practices for Testing React Components

Now that you know how to write tests, let's talk about how to write good tests.

Test User Behaviour, Not Implementation

Focus on testing what users see and do, not internal component details. If you refactor your component's implementation without changing its behaviour, your tests shouldn't break.

Bad test (testing implementation):

it('should set isOpen state to true', () => {
  const { result } = renderHook(() => useState(false));
  // Testing internal state directly
});

Good test (testing behaviour):

it('should show menu when button is clicked', async () => {
  const user = userEvent.setup();
  render(<Menu />);

  await user.click(screen.getByRole('button', { name: /menu/i }));
  expect(screen.getByRole('navigation')).toBeVisible();
});

Use Accessible Queries

React Testing Library encourages you to query elements the way users do. Prefer queries that mirror user interaction:

1. getByRole (best for interactive elements)

2. getByLabelText (for form fields)

3. getByPlaceholderText

4. getByText

5. getByTestId (last resort)

Keep Tests Simple and Focused

Each test should verify one thing. If your test needs a lot of setup or has many assertions, consider splitting it into multiple tests.

Clean Up Between Tests

Use afterEach to clean up the DOM after each test run, ensuring tests don't interfere with each other. This is already handled if you followed the setup steps earlier.

Use Descriptive Test Names

Test names should clearly describe what they're testing and what the expected outcome is.

Good test names:

it('should display error message when form is submitted empty');
it('should call onSubmit with email and password when form is valid');
it('should disable submit button while request is pending');

Mock External Dependencies

Always mock API calls, timers, and other external dependencies. Your tests should be isolated and not depend on network conditions or external services.

Conclusion

Now, you have learned how to set up Vitest in a React project and write effective tests for components, user interactions, custom hooks, and API calls. Vitest provides a powerful and efficient way to test React applications, especially when combined with modern tools like Vite.

Testing is about building confidence in your code, documenting expected behaviour, and enabling safe refactoring. Vitest's speed makes testing feel less like a chore and more like a natural part of development.

Start small. Add tests for critical user flows. Test the components that change frequently. As you build the habit, you will find that tests actually make development faster, not slower. The code will still be there tomorrow. But the bugs you catch today won't be.