Google Maps provides a $200 monthly credit, but beyond that, usage is billed per request. For applications like logistics, ride-hailing, or fleet tracking – where thousands of requests are made daily – costs can grow quickly depending on which APIs you use.

OpenStreetMap (OSM) offers a different approach. Instead of charging for access to map APIs, it provides free, open geographic data that you can build on.

In this guide, you'll learn what OpenStreetMap is, how it differs from Google Maps, and how to integrate it into a React application using Leaflet.

What We'll Cover:

1. What is OpenStreetMap?

2. Why Choose OpenStreetMap Over Google Maps?

3. Understanding the OpenStreetMap Ecosystem

   • Data Layer (OpenStreetMap)

   • Rendering Layer (Leaflet, MapLibre)

   • Services Layer

   • How Everything Works Together

4. How to Integrate OpenStreetMap in React with Leaflet

5. How to Add Geocoding with Nominatim

6. Advanced Features

7. When to Choose OpenStreetMap vs Google Maps

8. Wrapping Up

What is OpenStreetMap?

OpenStreetMap is a free, open, and community-driven map of the world. Anyone can contribute to it, and anyone can use it.

Unlike Google Maps, which gives access through controlled APIs, OpenStreetMap gives you access to the underlying geographic data itself.

This data is structured in three main ways:

1. Nodes: single points (for example, a bus stop or a tree)

2. Ways: lines or shapes made up of nodes (like roads or buildings)

3. Relations: groups of nodes and ways that define more complex things (like routes or boundaries)

Each of these elements includes tags (key-value pairs), such as:

highway=residential
name=Allen Avenue

So instead of just displaying a map, OpenStreetMap lets you work with structured geographic data.

The Open Database License (ODbL)

OpenStreetMap data is licensed under the ODbL. This means:

• You can use it for commercial or personal projects

• You must give proper attribution

This makes it especially useful for developers who want clarity around data ownership.

Why Choose OpenStreetMap Over Google Maps?

Cost

OpenStreetMap data is free to use. But it's important to be precise here: OpenStreetMap removes licensing costs, but not infrastructure costs.

You may still need to pay for:

• Tile hosting

• Geocoding services

• Routing engines

Control

With Google Maps, you can't modify the data, and you rely entirely on Google's APIs

But with OpenStreetMap, you can download and store the data, modify it, and build custom solutions on top of it.

Customization

OpenStreetMap gives you more flexibility:

• You control how maps are rendered

• You can choose or build your own map styles

• You can create domain-specific maps

Adoption

OpenStreetMap is widely used. Companies like Meta and Microsoft contribute to it, and many platforms rely on it directly or indirectly.

This shows that the ecosystem is mature and reliable.

Understanding the OpenStreetMap Ecosystem

A common mistake is to think that OpenStreetMap works like a single API. It doesn't.

Instead, it works as a set of layers, where each layer handles a different responsibility.

Data Layer (OpenStreetMap)

This is the foundation. It contains all the raw geographic data:

• Roads

• Buildings

• Landmarks

• Boundaries

This is what you are ultimately working with.

Rendering Layer (Leaflet, MapLibre)

Raw data isn't visual. It needs to be turned into something users can see.

There are two main approaches:

1. Raster tiles (used by Leaflet): pre-rendered images

2. Vector tiles (used by MapLibre): raw geometry styled in the browser

Leaflet uses raster tiles by default, which makes it simple and fast to start with.

Services Layer

This is what makes your map interactive. Geocoding converts addresses into coordinates, while reverse geocoding converts coordinates into addresses.

Routing calculates directions between points, and tile servers provide the actual map visuals.

How Everything Works Together

When a user searches for a place:

1. The user enters a location

2. A geocoding service converts it into coordinates

3. The map updates its position

4. A tile server provides the visual map

Each part is separate, but they work together to create the full experience.

How to Integrate OpenStreetMap in React with Leaflet

Let's build a simple map.

Step 1: Create a React App

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

Step 2: Install Dependencies

npm install leaflet react-leaflet
npm install --save-dev @types/leaflet

Step 3: Import Leaflet CSS

import 'leaflet/dist/leaflet.css';

This is required for the map to display correctly.

Step 4: Create a Map Component

import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';

function Map() {
  const position = [51.505, -0.09]; // latitude, longitude

  return (
    <MapContainer
      center={position}
      zoom={13}
      style={{ height: '100vh' }}
    >
      <TileLayer
        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
      />
      <Marker position={position}>
        <Popup>Hello from OpenStreetMap</Popup>
      </Marker>
    </MapContainer>
  );
}

export default Map;

Let's break down the important parts here:

MapContainer initializes the map.

• center is where the map starts

• zoom is how close the view is

• style must include height, or the map won't show

TileLayer defines where the map visuals come from.

• {z} is the zoom level

• {x}, {y} are the tile coordinates

• {s} is the subdomain

Each tile is a small image (usually 256×256 pixels), and Leaflet combines them to form the full map.

Marker adds a point on the map at a specific coordinate.

Popup displays information when the marker is clicked.

Important note:

The default OpenStreetMap tile server:

https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

is meant for learning, demos, and low-traffic apps. For production, you should use a dedicated provider or your own tile server.

How to Add Geocoding with Nominatim

Nominatim is OpenStreetMap's geocoding service. It allows you to convert addresses into coordinates and coordinates into readable locations.

Custom Hook for Geocoding

import { useState } from 'react';

export function useGeocoding() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const searchAddress = async (query) => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch(
        `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(query)}&format=json&limit=5`,
        {
          headers: {
            'User-Agent': 'YourAppName/1.0'
          }
        }
      );

      if (!response.ok) {
        throw new Error('Request failed');
      }

      const data = await response.json();
      setLoading(false);
      return data;
    } catch (err) {
      setError(err.message);
      setLoading(false);
      return [];
    }
  };

  return { searchAddress, loading, error };
}

In this code:

• useState manages loading and error states

• encodeURIComponent ensures safe URLs

• User-Agent is required by Nominatim

• response.json() converts response into usable data

Nominatim returns coordinates as strings, so you have to convert them before using them.

Important Usage Rules

The public Nominatim service:

• Allows about 1 request per second

• Requires proper identification

• May block excessive usage

You should debounce user input, cache results, and avoid repeated requests.

Creating a Search Component

The search component lets users type an address or place name and get matching locations via Nominatim. It includes a text input and a submit button.

When the form is submitted, it calls our searchAddress function (from the useGeocoding hook), which fetches up to 5 address results. These results are displayed below the input as clickable items.

When the user clicks a result, the component parses the returned latitude and longitude into numbers and passes them (along with a display name) up to the parent component via the onLocationSelect callback. This will allow the parent (for example, the map) to update its center based on the chosen location.

function SearchBox({ onLocationSelect }) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const { searchAddress, loading } = useGeocoding();

  const handleSearch = async (e) => {
    e.preventDefault();
    if (!query.trim()) return;

    const data = await searchAddress(query);
    setResults(data);
  };

  const selectLocation = (result) => {
    onLocationSelect({
      lat: parseFloat(result.lat),
      lon: parseFloat(result.lon),
      name: result.display_name
    });
  };

  return (
    <div>
      <form onSubmit={handleSearch}>
        <input
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder="Search location"
        />
        <button type="submit">
          {loading ? 'Searching...' : 'Search'}
        </button>
      </form>

      <div>
        {results.map((result) => (
          <div key={result.place_id} onClick={() => selectLocation(result)}>
            {result.display_name}
          </div>
        ))}
      </div>
    </div>
  );
}

Key concepts here:

• useState stores the current input (query) and the array of search results.

• e.preventDefault() stops the form submission from reloading the page.

• Calling searchAddress(query) fetches geocoding results from Nominatim.

• parseFloat() converts the returned lat/lon strings into JavaScript numbers before using them.

• onLocationSelect is a callback prop that sends the selected coordinates and name back to the parent component (for example to update the map).

Advanced Features

We can further extend the map app by adding more advanced functionality. For example:

Routing (OSRM, GraphHopper)

You can integrate turn-by-turn routing on your map. A common solution is to use a library like Leaflet Routing Machine, which supports OSRM out of the box and has plugins for GraphHopper. This adds a route UI control where users enter start and end points, and the library fetches a route from one of these engines to draw on the map.

Custom Tile Providers (Carto, MapTiler, and so on)

Instead of the standard tile.openstreetmap.org, you can use hosted tile services that offer OSM-based maps. For example, Carto and MapTiler both provide tile APIs (often with custom style options and higher usage limits).

Carto, MapTiler, and similar services are listed among the providers that allow free usage of OSM tiles. By using a custom tile provider, you gain flexibility in map design and avoid hitting the public server’s limits.

Vector Maps (MapLibre GL JS)

You can switch from raster tiles to vector tiles for even richer interactivity. Vector tiles send raw map data (geometries and attributes) to the client, which are then rendered in the browser. This allows dynamic styling and advanced features: for instance, you can change the map’s theme on the fly (for example, switch to a “dark mode” style at night) or highlight certain features like bike lanes more prominently.

Libraries like MapLibre GL JS (the open-source successor to Mapbox GL) can display OSM vector tiles with highly customizable styles and smooth zooming/rotation. This makes your map more responsive and adaptable to different use cases.

When to Choose OpenStreetMap vs Google Maps

Choose OpenStreetMap when:

• You need flexibility

• You want to reduce costs at scale

• You want control over data

Choose Google Maps when:

• You want an all-in-one solution

• You need features like Street View

• You want minimal setup

Wrapping Up

OpenStreetMap offers a powerful alternative to Google Maps for developers who need cost control, data ownership, and customization. While it requires understanding different components, the flexibility it provides is worth the learning curve.

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.