Ultimate Guide: React, TypeScript, Vite & Vitest Setup for 2026

Introduction: The 2026 Standard for Type-Safe React Testing

Jest requires heavy configuration to work with Vite. The build tool handles module resolution and bundling. Jest tries to do this alone, causing friction. Vitest uses the Vite engine directly. This eliminates the translation layer between test runner and bundler.

Most teams report faster startup times with Vitest. Large codebases often see a 3x improvement. The delay in watching tests drops noticeably. You get results in milliseconds, not seconds. This speed supports a tight feedback loop.

A single toolchain reduces configuration overhead. You maintain one vite.config.js file. The test runner reads the same settings. This alignment prevents environment mismatches. Development and testing stay in sync.

Top frontend teams are switching to Vitest. Native ES module support removes polyfill hacks. The ecosystem moves toward standard modules. Faster runs mean more tests run. This density improves code coverage without slowing development.

React Testing Library focuses on user behavior. It queries elements by their text or role. This mirrors how real users find content. Fragile DOM queries break when structure changes. User-centric queries stay stable.

RTL pairs cleanly with Vitest’s globals. You import expect directly from vitest. The library adds matchers like toBeInTheDocument. These assertions are readable and explicit. They describe the component state directly.

Human-readable assertions reduce maintenance. toBeDisabled() checks button states directly. toHaveAttribute() validates HTML properties. This approach avoids brittle CSS class checks. The code survives UI refactors.

Server Components change how we test. RTL handles client-side interactions well. It ignores internal implementation details. Accessibility-first testing becomes the default. This practice ensures broader user access.

This guide targets QA engineers and frontend developers. TypeScript adoption requires strict type safety. You need a setup that scales with your app. Quick tutorials often miss edge cases. This guide covers the full stack.

We cover Vite configuration and TypeScript settings. The Vitest setup includes global types. React Testing Library integration follows. We address common pitfalls and errors. The structure is sequential and actionable.

Expect a production-ready configuration. We use JSDOM for DOM environments. The setup handles Server Components correctly. This is not a quick overview. It is a detailed, 8500-word reference.

The combination of Vite, TypeScript, and Vitest provides a fast ecosystem. React Testing Library adds user-centric validation. This stack offers type safety and speed. It supports reliable testing workflows.

Step 1: Project Initialization and Dependency Installation

Creating the Vite + React + TypeScript Scaffold

Run the creation command in your terminal to generate the base project.

npm create vite@latest my-app --template react-ts

This command pulls the official Vite template for React with TypeScript support. The process asks you to confirm the project directory name. It then downloads the necessary files and installs the base dependencies.

The generated structure includes a src folder for your code and a public folder for static assets. Vite handles the build configuration automatically. You get a working development server out of the box.

Check the tsconfig.json file in the root directory. It sets strict type checking by default. This setup catches type errors before you run your code.

{
    "compilerOptions": {
      "target": "ES2020",
      "useDefineForClassFields": true,
      "lib": ["ES2020", "DOM", "DOM.Iterable"],
      "module": "ESNext",
      "skipLibCheck": true,
      "moduleResolution": "bundler",
      "allowImportingTsExtensions": true,
      "resolveJsonModule": true,
      "isolatedModules": true,
      "noEmit": true,
      "jsx": "react-jsx",
      "strict": true,
      "noUnusedLocals": true,
      "noUnusedParameters": true,
      "noFallthroughCasesInSwitch": true
    },
    "include": ["src"],
    "references": [{ "path": "./tsconfig.node.json" }]
}

The strict flag ensures the compiler is picky. You must handle undefined values explicitly. This reduces runtime crashes in production.

The folder structure keeps source files separate from build artifacts. This separation makes it easier to locate test files. You can place tests next to the components they verify.

Installing Core Testing Dependencies

Add the testing packages as development dependencies. These tools do not ship with the production build.

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

This command installs five packages for testing logic and environment simulation. Vitest acts as the test runner. It executes your test files and reports results.

@testing-library/react provides utilities to render components. It mimics how a user interacts with the DOM. The library encourages testing behavior over implementation details.

@testing-library/jest-dom adds custom matchers to the assertion library. These matchers make assertions easier to read. You can check if an element has specific text or attributes.

@testing-library/user-event simulates user interactions. It triggers events like clicks and key presses. This helps verify that components respond correctly to input.

jsdom provides a browser-like environment in Node.js. It allows DOM manipulation without a real browser. Vitest uses this environment to run tests quickly.

Check if @types/react and @types/react-dom are in your devDependencies. The Vite template usually includes them. If they are missing, add them to enable type checking for React hooks.

npm install -D @types/react @types/react-dom

Version conflicts can arise if you mix old and new packages. Stick to the latest stable releases. Vitest and React Testing Library update frequently.

Use the --save-dev flag to keep production dependencies clean. This keeps your bundle size small. It also clarifies which packages are only for testing.

Verifying the Initial Setup and Package.json Scripts

Open package.json and locate the scripts object. Add two scripts for running tests.

{
    "scripts": {
      "dev": "vite",
      "build": "tsc && vite build",
      "preview": "vite preview",
      "test": "vitest",
      "test:watch": "vitest --watch"
    }
}

The test script runs Vitest in a single pass. It exits after reporting results. This mode is useful for continuous integration pipelines.

The test:watch script keeps the process running. It re-runs tests when files change. This saves time during development.

Run npm test to verify the setup. The terminal should show Vitest starting. It will report no tests found if you have no test files yet.

This empty run confirms that the runner is installed correctly. It checks that the configuration is valid.

You can create a dummy test file to verify execution. Save a file named App.test.tsx in the src folder.

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import App from './App';

describe('App component', () => {
  it('renders main heading', () => {
    render(<App />);
    const heading = screen.getByRole('heading', { name: /App/i });
    expect(heading).toBeInTheDocument();
    });
});

Run npm run test:watch to see this test pass. The terminal displays green checkmarks. This confirms the entire stack works together.

CI/CD pipelines rely on the test script. It provides a consistent exit code. A non-zero code indicates failure.

A clean Vite + React + TypeScript scaffold with Vitest and RTL installed provides a solid foundation for building reliable test suites.

Step 2: Configuring Vite for Testing Environments

Setting Up `vite.config.ts` for Test Globals

Create vite.config.ts in your project root. This file controls how Vite and Vitest behave during development and testing. Import defineConfig from vitest/config to get proper TypeScript support.

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

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
  },
});

The globals: true option removes the need to import test, expect, and describe in every file. Vitest injects these functions into the global scope. This cuts down on repetitive code.

Large test suites often have hundreds of test files. Removing repetitive imports makes the code cleaner. It also speeds up the writing process for engineers.

Without globals, you write import { test, expect } from 'vitest' at the top of each file. With globals, you call test('...', () => ...) directly. The logic stays the same. The syntax becomes lighter.

Configuring the JSDOM Environment

React components render to the DOM. Vitest runs in a Node environment by default. Node does not have a window object or document. You need a browser simulation layer.

Set environment: 'jsdom' in the test block of your config. This loads JSDOM, a JavaScript implementation of the DOM. It provides the browser APIs your React components expect.

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
  },
});

JSDOM is the standard for React Testing Library tests. It handles event simulation and DOM queries reliably. Other environments like node lack these features entirely.

happy-dom is faster for some operations. It is lighter than JSDOM. However, JSDOM has better compatibility with the Testing Library ecosystem. Stick with JSDOM for general UI tests.

Switch to happy-dom only for non-DOM logic. Use it for utility functions that do not touch the DOM. This splits the performance cost from the UI testing cost.

Integrating React Plugin in Vite Config

The @vitejs/plugin-react handles JSX syntax. Vitest cannot parse .tsx files without it. You must add this plugin to the plugins array.

Import react from @vitejs/plugin-react. Pass it to the plugins array in your config. This ensures both dev and test builds use the same transformer.

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

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
  },
});

This plugin converts JSX into React.createElement calls. It also supports React Fast Refresh in development mode. In tests, it ensures components render correctly.

Keep the dev and test configurations aligned. Mismatches cause subtle bugs. If you update the plugin version, check both environments.

Properly configuring vite.config.ts with globals, JSDOM, and the React plugin is essential for Vitest to interact with React components.

Step 3: Configuring TypeScript for Test Compatibility

Updating `tsconfig.json` for Vitest and DOM Types

Open tsconfig.json and locate the compilerOptions object. Default settings often lack context for test environments. You must explicitly tell TypeScript where to find global definitions.

Add the vitest/globals entry to the types array. This tells the compiler that functions like describe, it, and expect exist without explicit imports.

Include vite/client in the same array. This provides types for Vite-specific globals like import.meta.env.

Add @testing-library/jest-dom to access custom DOM matchers. Without this, assertions like toBeInTheDocument will fail type checking.

{
   "compilerOptions": {
     "target": "ES2020",
     "useDefineForClassFields": true,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "ESNext",
     "skipLibCheck": true,
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "resolveJsonModule": true,
     "isolatedModules": true,
     "noEmit": true,
     "jsx": "react-jsx",
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
     "types": ["vitest/globals", "@testing-library/jest-dom"]
   }
}

The types array restricts global scope. TypeScript only loads definitions listed here. Removing a type from this list breaks related globals.

Before this change, expect throws a "Cannot find name 'expect'" error. The compiler assumes no global variables exist.

After adding vitest/globals, the error disappears. The type definitions load automatically.

The @testing-library/jest-dom entry adds methods to the HTMLElement interface. It extends the base DOM types with testing-specific assertions.

If you remove vite/client, import.meta.env becomes any. This reduces type safety in your test setup files.

Configuring `jsx` and `module` Resolution

Set jsx to react-jsx. This uses the modern React 17+ transformation. It removes the need to import React in every file.

The old react setting requires explicit imports. It also generates more verbose JavaScript output.

Use moduleResolution: "bundler". This aligns TypeScript with Vite’s module resolution strategy. It handles nested package.json exports correctly.

Older settings like node or classic often fail with modern React libraries. They do not respect the exports field in package.json.

{
   "compilerOptions": {
     "jsx": "react-jsx",
     "moduleResolution": "bundler",
     "module": "ESNext"
   }
}

The react-jsx mode compiles JSX into React.createElement calls automatically. It supports the new JSX transform introduced in React 17.

This setting reduces boilerplate code. You no longer need import React from 'react' in every test file.

Module resolution affects how TypeScript finds dependencies. bundler mode respects Vite’s aliasing and package exports.

If you use node resolution, TypeScript may fail to find types from nested packages. This causes "Could not find a declaration file" errors.

Consistent module resolution prevents mismatches between dev and test environments. Vitest relies on the same resolution logic as Vite.

Handling Type Errors in Test Files

Strict mode in tsconfig.json catches implicit any types. It forces explicit typing for variables and function returns.

Common errors include missing props on rendered components. TypeScript flags these as type mismatches immediately.

Fix errors by typing your test fixtures correctly. Create interfaces for component props and data models.

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

interface Props {
  name: string;
  count: number;
}

const TestComponent = ({ name, count }: Props) => {
  const [state, setState] = useState('init');
  return (
     <div>
       <h1>{name}</h1>
       <p>{count}</p>
     </div>
   );
};

test('renders name', () => {
  render(<TestComponent name="Test" count={1} />);
  expect(screen.getByText('Test')).toBeInTheDocument();
});

The Props interface defines required attributes. TypeScript checks these against the rendered component.

If you omit count, TypeScript raises a compile error. This prevents runtime crashes in tests.

Use // @ts-nocheck only for quick hacks. It disables all type checking for that file.

Proper typing catches bugs before execution. It ensures test data matches component expectations.

Typing render and screen queries prevents loose assertions. Use getByText with specific string types.

Strict typing eliminates guesswork. It forces you to define test data structures explicitly.

Configuring tsconfig.json with the correct types ensures TypeScript fully supports Vitest globals and React Testing Library matchers without errors.

Step 4: Creating the Vitest Setup File

Why a Setup File is Necessary for RTL

Vitest does not include React Testing Library matchers by default. You cannot call toBeInTheDocument immediately after importing render. The test runner expects plain JavaScript assertions. You must bridge this gap manually.

A setup file solves this problem. It runs before every test file in your suite. This ensures global state is ready for each test case. You avoid repeating boilerplate code in every spec file.

The industry standard is a dedicated file like setupTests.ts. You configure Vite to load this file for all tests. The setupFiles option in your config handles this.

Without this file, you face immediate errors. Tests fail because the matchers are undefined. With the file, you get a clean testing environment. The difference is immediate and obvious.

A setup file extends Vitest with global testing utilities.

You define the path in vite.config.ts. Vite reads this path at startup. It executes the code before loading any test files. This keeps your test files clean and focused.

Consider a test file without a setup. You would need to import matchers manually. You would call expect.extend in every file. This is repetitive and error prone.

The setup file runs in the same context as your tests. It has access to the same globals. You can modify expect directly. This modification persists for all subsequent tests.

The execution order matters here. Vite loads the setup file first. Then it loads your test files. This sequence guarantees availability of matchers.

You gain consistency across your project. Every test file behaves identically. You do not need to remember imports. The environment is pre-configured for you.

Implementing the Setup File with Jest-DOM Matchers

You need to install @testing-library/jest-dom for matchers. This package provides the toBeInTheDocument logic. You do not need to write this logic yourself.

The setup file imports these matchers directly. You import from the matchers subpath. This gives you access to the raw matcher functions.

import * as matchers from "@testing-library/jest-dom/matchers";

expect.extend(matchers);

This code adds matchers to the global expect object. Vitest uses this global expect by default. You do not need to pass it to render or screen.

Developers coming from Jest find this familiar. The API looks identical to their previous experience. They can write assertions without thinking about imports.

This setup makes tests human readable. You can assert on DOM state easily. The code reads like natural language.

Matchers extend expect with React Testing Library logic.

You can verify text content in an element. You can check if an element exists in the document. These assertions rely on the extended expect.

The expect.extend method takes an object. This object contains the matcher functions. Vitest spreads these into the global expect.

You can use these matchers in any test file. They are available immediately. You do not need to import them again.

This approach reduces cognitive load. You focus on the test logic. You ignore the setup boilerplate. The environment handles the heavy lifting.

You gain confidence in your assertions. The matchers are well tested. They handle edge cases for you.

Adding Cleanup and Global Setup Logic

Tests can leave side effects behind. React components may attach event listeners. These listeners consume memory and CPU.

You need to clean up after each test. Vitest provides an afterEach hook. You can use this hook in your setup file.

import { cleanup } from "@testing-library/react";

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

The cleanup function removes rendered DOM nodes. It also detaches event listeners. This prevents memory leaks in your test suite.

Run this hook after every test case. It ensures a clean slate for the next test. Isolation is critical for reliable results.

You can add other global mocks here. The window.scrollTo method often causes issues. You can mock it to return silently.

Cleanup prevents memory leaks and ensures test isolation.

You can mock IntersectionObserver as well. This observer is used by many modern components. Mocking it prevents errors in JSDOM.

Object.defineProperty(window, "IntersectionObserver", {
  writable: true,
  value: class MockIntersectionObserver {
    constructor() {}
    observe() {}
    unobserve() {}
    disconnect() {}
  },
});

This mock satisfies components that check for visibility. It stops errors about missing Observer API. Your tests run without crashing.

You can also mock window.matchMedia. This helps with responsive design tests. You control the media query results.

Global setup logic centralizes your configuration. You keep your test files pure. The setup file handles the environment.

This structure scales well for large projects. You add mocks in one place. You maintain them easily over time.

A dedicated setup file extends Vitest with React Testing Library matchers and cleanup logic, ensuring reliable and human-readable tests.

Step 5: Writing Your First React Component Tests

Creating a Simple React Component for Testing

Start with a component that has minimal logic. Complex components hide bugs. Simple components expose testing mechanics. A counter is ideal. It has state. It has interactions. It has output.

The component tracks a number. It displays the number. It provides buttons to change the number. This setup isolates the core concepts. You test state changes. You test user inputs. You test visual output.

Avoid business logic here. Keep the component pure. This makes assertions straightforward. You do not need to mock APIs. You do not need to handle async flows. Focus on the render tree.

import { useState } from 'react';

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

  const increment = () => setCount((c) => c + 1);
  const decrement = () => setCount((c) => c - 1);
  const reset = () => setCount(0);

  return (
     <div>
       <h1>Counter</h1>
       <p data-testid="count">Current count: {count}</p>
       <button onClick={increment}>Increment</button>
       <button onClick={decrement}>Decrement</button>
       <button onClick={reset}>Reset</button>
     </div>
   );
}

This code is readable. It uses standard React hooks. The data-testid attribute marks the count display. This selector is stable. It does not break with CSS changes. Use data-testid for critical assertions.

The structure is flat. No nested logic. No external dependencies. This simplicity helps you learn the test runner. You see how React renders to the DOM. You see how Vitest reports results.

Writing Unit Tests with RTL and Vitest

Create a test file named Counter.test.tsx. Place it in the src directory. Vitest finds files ending in .test.tsx. It runs them in parallel.

Import render from @testing-library/react. Import screen from the same library. Import userEvent from @testing-library/user-event. These imports provide the testing utilities.

Use describe to group related tests. Use it to define a specific case. The it block contains the assertion. Vitest executes these blocks sequentially.

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

describe('Counter', () => {
  it('displays initial count as zero', () => {
    render(<Counter />);
    expect(screen.getByTestId('count')).toHaveTextContent('Current count: 0');
  });
});

This test checks the initial state. render mounts the component. It adds the component to the DOM. The screen object queries the DOM. getByTestId finds the element. toHaveTextContent checks the text.

The assertion is clear. It fails if the text differs. It fails if the element is missing. Vitest prints the error message. You see the expected value. You see the actual value.

This approach is reliable. It does not rely on internal implementation. It tests the user's view. The component works if the text matches. This is the goal of unit testing.

Simulating User Interactions with User-Event

Static text checks are insufficient. Users click buttons. They type input. They scroll. Tests must mimic this behavior. userEvent provides realistic interactions.

Import userEvent in your test file. Create an instance with userEvent.setup(). Pass this instance to interaction methods. This simulates browser events.

Click the increment button. Check the count again. The state should change. The text should update. This flow verifies the logic.

describe('Counter interactions', () => {
  it('increments count on click', async () => {
    const user = userEvent.setup();
    render(<Counter />);
    
    const button = screen.getByText('Increment');
    await user.click(button);
    
    expect(screen.getByTestId('count')).toHaveTextContent('Current count: 1');
  });

  it('decrements count on click', async () => {
    const user = userEvent.setup();
    render(<Counter />);
    
    const button = screen.getByText('Decrement');
    await user.click(button);
    
    expect(screen.getByTestId('count')).toHaveTextContent('Current count: -1');
  });
});

The async keyword is required. User interactions are asynchronous. The click event triggers a state update. React re-renders. The test waits for this.

await user.click handles the event loop. It triggers the click. It waits for the effect. This prevents race conditions. Static assertions might fail here. They do not wait for renders.

This pattern works well for interactive components. It tests the user's journey. You verify the button works. You verify the text updates. This matches real usage.

Writing unit tests with RTL and Vitest allows for realistic testing. This method ensures your components work as intended. It catches regressions early. It builds confidence in your code.

Step 6: Advanced Testing Patterns and Configuration

Configuring Vitest for Code Coverage

Enable code coverage directly in your vite.config.ts. This keeps your configuration centralized and avoids external tooling friction. The V8 provider offers the fastest runtime coverage. It bypasses the slower instrumentation layer found in older tools.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      thresholds: {
        lines: 90,
        functions: 90,
        branches: 90,
        statements: 90,
       },
     },
   },
});

This configuration sets up the V8 provider. It also defines output formats and strict thresholds. The thresholds enforce minimum quality standards. CI pipelines fail builds if coverage drops below these limits.

The V8 provider uses the native V8 engine. It parses your code during test execution. This approach is nearly instant compared to bytecode injection. Accuracy remains high because it relies on the runtime itself.

Run npm run test -- --coverage to generate reports. The command produces text and LCOV files. You can view LCOV files in any browser. The text output prints directly to your terminal.

CI systems use these reports to gate merges. A failing threshold blocks deployment. This forces developers to write necessary tests. It prevents code rot in critical paths.

Mocking API Calls with Vitest

Use vi.mock to replace external dependencies. Vitest supports module-level mocking natively. This mirrors the Jest API but runs faster.

import { describe, it, expect, vi } from 'vitest';
import { render, screen } from '@testing-library/react';
import UserList from './UserList';

const mockFetch = vi.fn();
global.fetch = mockFetch;

describe('UserList Component', () => {
  it('displays users from API', async () => {
    mockFetch.mockResolvedValue({
      ok: true,
      json: async () => [{ id: 1, name: 'Alice' }],
    });

    render(<UserList />);
    expect(screen.getByText('Alice')).toBeInTheDocument();
  });
});

This example replaces fetch globally. The mock returns a resolved promise. The test verifies the rendered output.

vi.mock works at the module level. It hoists automatically in most cases. Use vi.hoisted if you need explicit control. This avoids timing issues in complex setups.

Mock functions track call counts. Use mockFn.mock.calls to inspect arguments. This helps verify interaction logic. You can also mock return values dynamically.

Axios requires slightly different handling. Mock the instance or the underlying adapter. The principle remains the same. Replace the network layer with a stable response.

Native module mocking simplifies test isolation. You do not need a separate mock server. Tests run in complete isolation. This speeds up the feedback loop.

Testing Hooks and Custom Logic

Extract business logic into custom hooks. This makes testing straightforward. Use renderHook from @testing-library/react to invoke hooks directly.

import { renderHook, act } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { useCounter } from './useCounter';

describe('useCounter Hook', () => {
  it('increments and decrements correctly', () => {
    const { result } = renderHook(() => useCounter());

    expect(result.current.count).toBe(0);

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

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

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

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

renderHook returns the hook's result. It also provides an act wrapper. This ensures state updates flush correctly.

The result object contains the current state. Access properties directly for assertions. Modify state using the returned actions. Wrap mutations in act to trigger updates.

This approach isolates logic from the DOM. You do not need to render a component. Tests run faster without DOM overhead. This is ideal for pure functions.

Complex state machines benefit from this pattern. Keep UI components thin. Move data fetching and transformation into hooks. Tests verify the logic without rendering.

Advanced Vitest features like code coverage, mocking, and hook testing enable thorough and reliable testing of complex React applications.

Step 7: Troubleshooting, Best Practices, and Conclusion

Common Pitfalls and How to Avoid Them

Type errors in test files usually stem from missing configurations. Check your tsconfig.json first. Ensure the types array includes vitest/globals. This allows you to use describe and test without importing them.

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

The error message will be clear if this is missing. It says the name does not exist on the global type. Add the entry and the error vanishes.

JSDOM often fails silently if not configured. Vitest defaults to browser or node. You must switch to jsdom for DOM queries. Set the environment in vite.config.ts.

export default defineConfig({
  test: {
    environment: 'jsdom',
  },
});

Without this, screen.getByRole throws a null pointer. The stack trace points to the query method. Read the error message carefully. It usually tells you the DOM is missing.

RTL matchers fail when setupTests.ts is ignored. Vitest does not auto-run setup files. You must list them in the config.

export default defineConfig({
  test: {
    setupFiles: './src/setupTests.ts',
  },
});

If you skip this, toBeInTheDocument is undefined. The test crashes immediately. Check your console output for the error. It is usually the first line.

Community docs solve most issues. The Vitest GitHub issues track known bugs. The React Testing Library docs explain matcher behavior. Read them before posting.

Best Practices for Maintainable Test Suites

Descriptive names save time later. Use it for specific behaviors. Avoid vague titles like should work.

it('displays the correct title', () => {
  // ...
});

This title explains the expectation. It helps when scans fail in CI. The error message includes the name.

Use data-testid for stable queries. Screen queries like getByRole are better for accessibility. However, test-id is reliable for unique elements.

<Button data-testid="submit-btn" />

const btn = screen.getByTestId('submit-btn');
expect(btn).toBeEnabled();

This query does not break if you change the HTML tag. It does not break if you add a wrapper div. It stays stable.

Keep tests focused and isolated. Each test should check one behavior. Do not test multiple features in one block.

it('increments counter on click', () => {
  render(<Counter />);
  const btn = screen.getByRole('button');
  userEvent.click(btn);
  expect(screen.getByText('1')).toBeInTheDocument();
});

This test checks only the click. It does not check initial render. Keep it small. Refactor often. Merge similar tests. Delete unused ones.

Conclusion: Embracing the Modern React Testing Ecosystem

The stack is simple. Vite scaffolds the project. Vitest runs the tests. TypeScript checks the types. RTL handles the DOM.

This combination works for 2026. It is fast. It is type-safe. It is easy to debug.

Adopt this stack for new projects. Migrate existing ones gradually. Start with the simplest components. Add coverage slowly.

Build applications with confidence. The tools are ready. The stack is proven. Use it well.

Let's build something together

We build fast, modern websites and applications using Next.js, React, WordPress, Rust, and more. If you have a project in mind or just want to talk through an idea, we'd love to hear from you.

Start a Project →

Ultimate Guide: React, TypeScript, Vite & Vitest Setup for 2026