Component testing: a practical guide for frontend developers

As a frontend developer, you spend most of your time building components. A button, a form field, a navigation bar, an entire page: in a modern UI, each is a component. Each one renders differently depending on the props and state passed into it, which means each one has many possible variations to get right.

Component testing is how you verify those variations behave and render correctly, one component at a time, without spinning up your whole application. It renders a component in a real browser, lets you simulate how a user would interact with it, and lets you assert that it responds the way it should.

This guide explains what component testing is, how it differs from the other kinds of tests you might write, the techniques and tools involved, and how to get started.

Try component testing with Storybook »

Component testing is one piece of a complete frontend testing strategy. For how it fits alongside unit, visual, accessibility, and end-to-end testing, see Chromatic’s frontend testing guide.

What is component testing

A component test renders a single UI component in a real browser, in isolation from the rest of your application. Once rendered, the test can interact with the component the way a user would and make assertions about how it responds.

What makes component testing distinct is that it combines strengths usually split across other test types. Like an end-to-end test, it provides high fidelity by running in a real browser and simulating real user behavior. Like a unit test, it tests a single piece of UI in isolation and can reach into the implementation to mock data or manipulate dependencies. That combination is what makes it a powerful way to test the functional behavior of your UI.

Where component testing fits in the development cycle

It helps to think about what you are testing. Atomic design, the mental model popularized by Brad Frost, describes UIs as a hierarchy of components that build up in complexity — from atoms like buttons and inputs, to molecules and organisms, up through templates and full pages. Component testing applies at every level of that hierarchy: you can test a single atom in isolation, or a composed organism, or an entire page-level component.

Because components are the thing frontend developers build all day, component testing naturally happens early and often during development. A developer’s core job is to meet the functional requirements of a feature. Component tests (alongside unit tests) answer exactly that question while giving the fastest feedback. In a well-ordered testing process, component tests and unit tests allow you confirm the component renders in a browser and behaves as intended. Once the feature is passing those basic tests, you layer on accessibility, appearance, and finally end-to-end testing that confirm the feature integrates with the rest of the app.

The practical upshot is that component testing isn’t a chore bolted on at the end. You write a component, render it in its various states to see your work, and those same states become the tests that prove it meets requirements.

Learn more about where component testing sits in the frontend development cycle in Chromatic’s article.

Frontend Testing Guide

We researched dozens of teams to figure out which frontend testing strategies actually work. This helps you create a pragmatic testing strategy while avoiding pitfalls.

Core characteristics of component testing

• Isolation. The component is tested on its own, separate from the rest of the app. This is both the strength and the limit of component testing: you get fast, focused, reliable tests, at the cost of not verifying how the whole system fits together.
• Scope. A component test can cover anything from a single small component to a large page-level component. The higher up the hierarchy you go, the more the test resembles an end-to-end test.
• Environment. Component tests run in a real browser rather than a simulated or headless DOM emulation. Running in a real browser means the test exercises the same rendering, layout, and APIs your users get, which gives you higher confidence than emulated environments.
• Ownership. Component tests are typically written and maintained by the frontend developers building the components, as part of their normal development workflow — not handed off to a separate QA team. Product managers and designers are typically key stakeholders and part of the testing process as well.

Why component testing matters

UI test coverage presents a dilemma. End-to-end tests give the most confidence since they mimic actual user behavior through an actual browser, but they are slow, flaky, expensive to set up, and hard to steer into specific UI states. Unit tests are cheap to write and run since they run against an emulated DOM but they reveal little about whether the interface actually works in a real browser. Teams trying to catch UI regressions get squeezed between those two options.

Component tests resolve that dilemma by sitting in between. They offer end-to-end-style browser fidelity with the speed, reliability, and compactness of unit tests. That makes them a natural fit for the majority of your UI tests, with end-to-end tests reserved for a handful of critical flows.

The practical payoff: component tests let you reach UI states that are genuinely hard to trigger in a full end-to-end run — loading states, error states, empty states, form validation failures — quickly and reliably. You cover the wide range of states your components can be in, while a small number of end-to-end tests cover the critical happy paths.

For more on why the Storybook team believes component testing is the future of UI testing, read Component testing in Storybook.

Common component testing techniques

In practice, frontend component testing tends to use a few complementary techniques, often layered on the same component:

• Render testing. The simplest technique. A test that renders a component in a given state and passes as long as it renders without errors is a smoke test — what Storybook calls a render test. Despite its simplicity, it catches a surprising number of issues, and you often get it for free just by defining the states your component can be in.
• Interaction testing. Going a step further, you simulate user behavior such as clicking, typing, and selecting and assert that the component responds correctly. This is how to test stateful components: open a dialog, submit a form, toggle a control, and verify the result.
• Mocking and spying. Because component tests run the component in isolation, you can mock data, network requests, and dependencies to drive the component into specific states (a loading spinner, a 404 error, an empty list), and you can spy on functions to verify they’re called correctly.

Together these let you reach essentially any UI state and verify both how the component looks and how it behaves.

These techniques are what you do; the tools below are what you do them with. The two don't map one-to-one since most component testing tools support several techniques at once and a single test often combines them. With that in mind, here are the most common tools and where each fits.

Tools for component testing

Several tools play a role in component testing, and most teams use more than one:

• Storybook: A frontend workshop where you build components in isolation and write their states as stories. Those stories double as component tests: each one is a render test by default, and you can add interaction testing on top with a play function and mock dependencies as needed. Storybook runs your tests in a real browser, in the same environment where you develop, which makes it especially strong for testing components visually and interactively.
• Vitest: A fast, modern test runner widely used for component testing (render and interaction) as well as unit testing. It provides the mocking and spying utilities these tests rely on.
• Jest: A long-established JavaScript test runner used primarily for unit testing frontend logic. It supports render and interaction testing, and mocking too, but it's less commonly reached for component testing than Vitest.
• Testing Library: A library for querying and interacting with rendered components the way a user would. It’s commonly paired with Storybook or Vitest to provide the interaction testing behind them.
• Cypress and Playwright component testing. Both are best known as end-to-end tools, and both also offer component testing modes that render components in a real browser and run interaction tests against them.
• Chromatic visual testing: Component tests verify behavior, but confirming a component looks right still means reviewing pixels by hand. Chromatic (built by the Storybook team) automates that by snapshotting each story and flagging visual changes against a baseline, serving as a layer on top of the render tests you've already written. It runs on the stories you’ve already written, making it a natural complement to component testing. It also provides interaction testing by replacing Storybook in CI.

Example: testing a component in Storybook

Let's look at an example that demonstrates the three techniques covered above. The EventForm component has a title input, an invitee picker that loads people from a getUsers() API call, and a submit button. It calls onSubmit with the title and the chosen invitees.

type EventFormProps = {
  onSubmit: (event: { title: string; invitees: User[] }) => void;
};

1. Render test

The first story is to help you verify how the component renders while building it.

It also acts as a smoke test. When Storybook runs this story as a test, it passes if the component renders without throwing.

// EventForm.stories.ts
import type { Meta, StoryObj } from '@storybook/react-vite';
import { fn } from 'storybook/test';

import { EventForm } from './EventForm';

const meta = {
  component: EventForm,
  args: { onSubmit: fn() },
} satisfies Meta<typeof EventForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Default: Story = {};

2. Interaction test

Next, let's verify the component behavior. The play function runs after the story renders and interacts with the component the way a user would. This one submits the form without a title and checks that the validation fires.

import { expect } from 'storybook/test';

export const EmptyTitleShowsError: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Create event' }));
    await expect(canvas.getByText('Title is required')).toBeInTheDocument();
  },
};

The test runs in a real browser, and you can watch it play back in the Storybook UI.

3. Test with mocking and spying

The EventForm fetches invitees from getUsers(), so to test a successful submission we'll mock this API.

Register the module as mocked once, in your Storybook config:

// .storybook/preview.ts
import { sb } from 'storybook/test';

sb.mock(import('../lib/users.ts'));

Now every story gets a mock version of getUsers. In the story, tell the mock what to return, then drive the form to completion.

We set the onSubmit arg to fn() in step one. This turns it into a spy, so it records every call. Therefore, we can verify that it was called correctly.

The mock drives the component into a known state. The spy verifies the underlying component logic.

import { mocked } from 'storybook/test';
import { getUsers } from '../lib/users';

export const SubmitsWithInvitees: Story = {
  beforeEach: async () => {
    mocked(getUsers).mockResolvedValue([{ id: 'u1', name: 'Priya' }]);
  },
  play: async ({ canvas, userEvent, args }) => {
    await userEvent.type(canvas.getByLabelText('Title'), 'Design review');
    await userEvent.click(canvas.getByRole('button', { name: 'Add invitee' }));
    await userEvent.click(await canvas.findByText('Priya'));
    await userEvent.click(canvas.getByRole('button', { name: 'Create event' }));

    await expect(args.onSubmit).toHaveBeenCalledWith({
      title: 'Design review',
      invitees: [{ id: 'u1', name: 'Priya' }],
    });
  },
};

Component testing vs unit testing

Unit tests and component tests are closely related since both are isolated and written by developers, but they differ in what they verify. A unit test checks the smallest testable piece of code, often a pure function, without any side-effects such as rendering UI. A component test renders an actual component in a real browser and verifies that it looks and behaves correctly.

A useful rule of thumb: use unit tests for pure logic that’s independent of the UI (formatting, calculations, data transformations), and use component tests for anything that renders or responds to user interaction.

Component testing vs integration testing

Integration testing verifies that multiple units work together correctly rather than in isolation. In modern frontend practice, it usually isn’t treated as a separate category with its own tooling. Instead, it tends to be absorbed into the test types around it: testing a tree of components together is effectively a component test (render a composed component and assert on the combined behavior), while testing how the frontend integrates with backend services and APIs is effectively an end-to-end test.

In other words, you’re still doing integration testing, just via component tests for component-to-component interactions and end-to-end tests for full-stack flows.

Component testing vs end-to-end testing

End-to-end (E2E) tests spin up your entire application including frontend, backend, APIs to simulate a user moving through a complete flow, like signing up or checking out. They’re the highest-fidelity tests you can write because they exercise exactly what the user experiences.

The tradeoff is cost. End-to-end tests are slower, more prone to flakiness, and require substantial infrastructure to set up and maintain. The setup step alone can take longer than running every other test type combined. That’s why experienced teams use them sparingly, reserving them for a small number of critical user journeys.

The two are complements, not competitors: end-to-end tests cover the critical paths through your app, and component tests cover the much larger space of individual UI states around them.

Component testing in the age of AI agents

AI coding agents can generate a component, wire up its props, and produce UI code in seconds. The risk is that they invent components that already exist, drift from established patterns, and hallucinate APIs. Faster generation means more code to validate, which makes component testing more important, not less.

Component testing addresses this in two ways:

• Tests act as guardrails. When a component test fails, it returns a specific, deterministic error, such as a prop mismatch, a broken interaction, or an accessibility violation, which an agent can read and fix on its own. The agent generates code, runs the tests, reads the failures, and iterates until they pass; a human steps in only for judgment calls like ambiguous visual changes or whether the result matches intent. Because component tests run quickly in a real browser and tie each failure to a specific component, they give agents exactly the fast, precise feedback they can act on.
• Stories act as context. The stories you write to test a component also describe, in a structured and validated form, what the component is and how it’s meant to be used. Handed to an agent, that record lets it build from your existing components instead of inventing new ones. The stories do double duty: they verify behavior, and they teach agents to work within your system.

This is why Storybook treats component testing as foundational for AI-assisted frontend work: the same stories are simultaneously your tests and the context agents depend on. For more, see Storybook for AI and Chromatic’s Frontend Workflow for AI.

Get started with Storybook »

Want to learn more best practices with Storybook? Read our guide on design system documentation.

How to document your design system: best practices & tools

A design system is only as useful as its documentation. Without it, the components you’ve carefully built go undiscovered, get misused, or get rebuilt from scratch by the next developer who couldn’t find them. A 2026 Design Systems Report from Zeroheight reveals that only 38% of design systems were widely or fully adopted across their organizations, with documentation completeness as one of the strongest markers of successful adoption. Good documentation is what turns a collection of components

ChromaticDominic Nguyen

Frequently asked questions

Who usually performs component testing?
Component testing is typically done by the frontend developers who build the components, as part of their normal development workflow, rather than by a separate QA team. Because the tests are written alongside the component code, they tend to be created and maintained by the same people writing the UI.

What is another name for component testing?
Component testing is sometimes referred to as module testing, and in frontend contexts it overlaps with what people loosely call UI testing.

Why use component testing?
Component tests give you browser-level confidence at close to unit-test speed and cost. They let you quickly and reliably verify the many states a component can be in — including states that are hard to reach in a full end-to-end run — which makes them well suited to the majority of your UI tests.

Is component testing the same as unit testing?
No. Unit tests verify isolated logic, usually in a simulated environment, while component tests render a real component in a real browser and verify how it looks and behaves. They’re complementary.

Do component tests replace end-to-end tests?
No. They complement them. Component tests cover the wide range of individual UI states; a smaller number of end-to-end tests cover critical full-stack user flows.