Vitest with React Testing Library: A Modern Approach to Testing React Apps

As React development evolves, so do the tools we use to test our applications. With the React team recommending Vite as a preferred build tool over create-react-app, developers need a testing solution that integrates seamlessly with the Vite ecosystem. Enter Vitest—a testing framework designed to work harmoniously with Vite-built applications.

In this article, we’ll explore how to set up and use Vitest with React Testing Library for comprehensive React application testing. We’ll cover everything from installation to writing effective tests and leveraging Vitest’s unique features.

Why Vitest for React Testing?

Before diving into setup, let’s understand why Vitest has gained traction in the React ecosystem:

1. Speed: Vitest leverages Vite’s lightning-fast HMR and native ESM support, making test execution significantly faster than Jest.

2. Native Vite Integration: Since Vitest is built on top of Vite, it inherits all of Vite’s benefits, including its plugin system and configuration options.

3. Jest Compatibility: Vitest offers a Jest-compatible API, making migration from Jest straightforward for teams with existing test suites.

4. Modern Features: Vitest includes built-in support for TypeScript, ESM, and other modern JavaScript features without additional configuration.

5. Watch Mode Performance: Vitest’s watch mode is optimized for quick feedback during development, rerunning only the necessary tests.

Setting Up Vitest with React Testing Library

Let’s walk through the process of setting up Vitest in a React project created with Vite.

Prerequisites

Before we begin, make sure you have a React application created with Vite. If not, you can create one using:

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

Step 1: Install Vitest

First, we need to install Vitest as a development dependency:

npm install --save-dev vitest

Step 2: Add the Test Script

Add a test script to your package.json file:

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

The test script runs Vitest in watch mode, while test:run executes the tests once and exits. The test:ui script runs Vitest with its UI interface, which we’ll set up later.

Step 3: Install jsdom for Browser Environment Simulation

Since we’re testing React components that interact with the DOM, we need a browser-like environment:

npm install --save-dev jsdom

Step 4: Install React Testing Library

Next, install React Testing Library and related packages:

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

Step 5: Configure Vitest in Vite Config

Update your vite.config.js file to include Vitest configuration:

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

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

Let’s break down this configuration:

• plugins: [react()]: Enables Vite’s React plugin which provides JSX support, Fast Refresh, and other React-specific optimizations.
• test.environment: 'jsdom': Sets up a browser-like DOM environment using jsdom for testing components that interact with the DOM.
• test.globals: true: Makes test functions (describe, it, expect, etc.) available globally without requiring explicit imports.
• test.setupFiles: Specifies a file that runs before your tests, where you can configure testing utilities.

Using happy-dom as an Alternative

While jsdom is a popular choice, you might want to consider using happy-dom as an alternative DOM implementation:

npm install --save-dev happy-dom

Then update your Vite config:

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'happy-dom', // Using happy-dom instead of jsdom
    globals: true,
    setupFiles: './src/tests/setup.js'
  }
});

Why consider happy-dom?

1. Performance: happy-dom is generally faster than jsdom, which can significantly reduce test execution time in larger projects.
2. Memory efficiency: It uses less memory than jsdom, making it more suitable for CI/CD environments with limited resources.
3. Modern web features: happy-dom sometimes implements newer web APIs faster than jsdom.

For most React applications, both libraries work well with React Testing Library. Consider benchmarking both in your specific project if performance is a concern, happy-dom is a faster alternative, but it doesn’t have some Web APIs. jsdom is more mature package.

If you’re using TypeScript, you might need to adjust the configuration to avoid type errors:

import {defineConfig, UserConfig} from 'vite';
import react from '@vitejs/plugin-react';

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

Step 6: Create the Test Setup File

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

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

// Runs a cleanup after each test case
afterEach(() => {
  cleanup();
});

This setup file imports the necessary testing utilities and ensures DOM cleanup after each test.

Writing Your First Test with Vitest and React Testing Library

Now that we have our testing environment set up, let’s write a simple test for a React component.

Create a Simple Component

Let’s create a simple Counter.jsx component:

import {useState} from 'react';

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

  return (
    <div>
      <h1>Counter: {count}</h1>
      <button onClick={() => setCount(count + 1)}>Increment</button>
      <button onClick={() => setCount(count - 1)}>Decrement</button>
    </div>
  );
}

export default Counter;

Write a Test for the Component

Create a test file named Counter.test.jsx in the same directory:

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

describe('Counter Component', () => {
  it('renders correctly', () => {
    render(<Counter />);
    expect(screen.getByText(/counter: 0/i)).toBeInTheDocument();
  });

  it('increments the count when the increment button is clicked', () => {
    render(<Counter />);
    const incrementButton = screen.getByText(/increment/i);

    fireEvent.click(incrementButton);

    expect(screen.getByText(/counter: 1/i)).toBeInTheDocument();
  });

  it('decrements the count when the decrement button is clicked', () => {
    render(<Counter />);
    const decrementButton = screen.getByText(/decrement/i);

    fireEvent.click(decrementButton);

    expect(screen.getByText(/counter: -1/i)).toBeInTheDocument();
  });
});

Run the Test

Execute the tests by running:

npm test

You should see the tests pass, with output showing the test results.

Vitest Features for React Testing

Now that we have basic testing working, let’s explore some of Vitest’s features that make it particularly well-suited for React testing.

1. Fast Hot Module Replacement (HMR)

Vitest leverages Vite’s HMR capabilities, which means your tests re-run almost instantly when you make changes. This significantly speeds up the test-driven development workflow.

2. UI Mode

Vitest offers a UI interface that provides a visual representation of your test suite:

npm install --save-dev @vitest/ui

Once installed, you can run the UI with:

npm run test:ui

This opens a web interface where you can view test results, coverage reports, and more.

3. Coverage Reports

Vitest includes built-in code coverage support:

npm install --save-dev @vitest/coverage-c8

Update your package.json test script:

{
  "scripts": {
    "test:coverage": "vitest run --coverage"
  }
}

Running npm run test:coverage will generate detailed coverage reports.

4. Snapshot Testing

Like Jest, Vitest supports snapshot testing, which is useful for capturing and verifying component output:

it('matches snapshot', () => {
  const {container} = render(<Counter />);
  expect(container).toMatchSnapshot();
});

5. Mock Functions and Spies

Vitest provides similar mocking capabilities to Jest:

import {vi} from 'vitest';

const mockFn = vi.fn();
mockFn();
expect(mockFn).toHaveBeenCalled();

Advanced Testing Techniques with Vitest

Let’s explore some more advanced testing techniques that you can use with Vitest and React Testing Library.

Testing Asynchronous Operations

Testing asynchronous operations, such as API calls, is a common requirement:

// UserData.jsx
import {useState, useEffect} from 'react';

function UserData({userId}) {
  const [userData, setUserData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchUser = async () => {
      try {
        setLoading(true);
        const response = await fetch(
          `https://jsonplaceholder.typicode.com/users/${userId}`
        );
        if (!response.ok) throw new Error('Failed to fetch user');
        const data = await response.json();
        setUserData(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchUser();
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!userData) return null;

  return (
    <div>
      <h1>{userData.name}</h1>
      <p>Email: {userData.email}</p>
      <p>Phone: {userData.phone}</p>
    </div>
  );
}

export default UserData;

To test this component, we need to mock the fetch API:

// UserData.test.jsx
import {
  render,
  screen,
  waitForElementToBeRemoved
} from '@testing-library/react';
import {vi} from 'vitest';
import UserData from './UserData';

// Mock the global fetch function
global.fetch = vi.fn();

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

  it('displays user data when fetch is successful', async () => {
    global.fetch.mockResolvedValueOnce({
      ok: true,
      json: async () => ({
        id: 1,
        name: 'John Doe',
        email: 'john@example.com',
        phone: '555-1234'
      })
    });

    render(<UserData userId={1} />);

    expect(screen.getByText(/loading/i)).toBeInTheDocument();
    await waitForElementToBeRemoved(() => screen.queryByText(/loading/i));

    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText(/email: john@example.com/i)).toBeInTheDocument();
    expect(screen.getByText(/phone: 555-1234/i)).toBeInTheDocument();
  });

  it('displays error message when fetch fails', async () => {
    // Mock failed response
    global.fetch.mockResolvedValueOnce({
      ok: false
    });

    render(<UserData userId={1} />);

    await waitForElementToBeRemoved(() => screen.queryByText(/loading/i));

    expect(
      screen.getByText(/error: failed to fetch user/i)
    ).toBeInTheDocument();
  });
});

Testing Custom Hooks

Testing custom hooks requires a slightly different approach. We’ll use the renderHook function from @testing-library/react:

// useCounter.js
import {useState} from 'react';

function useCounter(initialValue = 0) {
  const [count, setCount] = useState(initialValue);

  const increment = () => setCount(count + 1);
  const decrement = () => setCount(count - 1);
  const reset = () => setCount(initialValue);

  return {count, increment, decrement, reset};
}

export default useCounter;

Test file:

// useCounter.test.js
import {renderHook, act} from '@testing-library/react';
import useCounter from './useCounter';

describe('useCounter Hook', () => {
  it('should initialize with default value of 0', () => {
    const {result} = renderHook(() => useCounter());
    expect(result.current.count).toBe(0);
  });

  it('should initialize with custom value', () => {
    const {result} = renderHook(() => useCounter(10));
    expect(result.current.count).toBe(10);
  });

  it('should increment the counter', () => {
    const {result} = renderHook(() => useCounter());

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

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

  it('should decrement the counter', () => {
    const {result} = renderHook(() => useCounter());

    act(() => {
      result.current.decrement();
    });

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

  it('should reset the counter', () => {
    const {result} = renderHook(() => useCounter(5));

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

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

Best Practices for Testing React Apps with Vitest

To ensure your tests are effective and maintainable, consider these best practices:

1. Test Behavior, Not Implementation

Focus on testing how your components behave from a user’s perspective, rather than implementation details. React Testing Library encourages this approach by providing utilities that interact with components similar to how users would.

2. Use Role-Based Queries

Whenever possible, use role-based queries like getByRole instead of targeting elements by class or ID:

// Prefer this
const button = screen.getByRole('button', {name: /increment/i});

// Over this
const button = screen.getByTestId('increment-button');

This makes your tests more resilient to implementation changes.

3. Keep Tests Simple and Focused

Each test should verify a single aspect of your component’s behavior. This makes tests easier to understand and maintain.

4. Set Up Test Fixtures

Extract common setup code into fixtures or helper functions to reduce duplication and improve test readability.

Comparing Vitest to Jest

If you’re migrating from Jest to Vitest, here’s a quick comparison of key differences:

1. Performance: Vitest is generally faster due to its integration with Vite’s optimized build process.

2. Configuration: Vitest configuration is typically simpler and can be included directly in your vite.config.js file.

3. ESM Support: Vitest has native ESM support, whereas Jest requires additional configuration.

4. API: While most of the API is compatible, there are some differences in mocking and timer functions.

5. Watch Mode: Vitest’s watch mode leverages Vite’s HMR for faster feedback.

6. Tooling: Vitest provides a modern UI interface and better integration with the Vite ecosystem.

Conclusion

Vitest combined with React Testing Library offers a modern, fast, and effective solution for testing React applications built with Vite. The seamless integration with the Vite ecosystem, Jest-compatible API, and excellent performance make it an attractive choice for new projects and teams looking to upgrade their testing infrastructure.

By following the setup steps and best practices outlined in this article, you can create a robust testing environment that helps ensure your React applications are reliable and maintainable.

Remember that tests are an investment in your application’s quality. They provide confidence when refactoring, adding new features, or fixing bugs. With Vitest, that investment comes with lower overhead and faster feedback, which ultimately leads to a more enjoyable development experience.

Happy testing!