Test a single UI component in isolation with Cypress component testing

Goal

Verify that a UI component renders correctly and responds to user input without launching a full application or writing end-to-end tests. Cypress component testing mounts one component in a real browser so you can assert on its HTML, events, and output using standard Cypress commands.

Prerequisites

• A Node.js project with a package manager (npm, yarn, or pnpm).
• Cypress version 7 or later installed as a development dependency. Component testing is not supported in releases before version 7.
• A UI component written in a framework Cypress supports for component testing, depending on the installed Cypress version and framework adapter.
• A bundler such as Vite or Webpack configured to process the component's syntax, because Cypress component testing compiles and renders the component in the browser.

Install Cypress and scaffold component testing

Run this command in the project root. No administrator privileges are required; avoid using sudo with npm because it can corrupt file ownership in node_modules.

npm install --save-dev cypress

Open the Cypress Test Runner to initialize the project structure:

npx cypress open

When the launcher appears, choose component testing and select your framework. Cypress creates a component testing configuration and a cypress/component directory. If you configure manually, create cypress/component and add component-testing settings to the project's Cypress configuration file.

Create a component spec

Create a spec file under cypress/component. This example uses JSX syntax; adjust the import and component markup for your framework and bundler setup.

import Counter from '../../src/components/Counter';

describe('Counter component', () => {
  it('increments the value when the button is clicked', () => {
    cy.mount();

    cy.get('[data-testid="counter-value"]').should('contain', '0');
    cy.get('[data-testid="increment-button"]').click();
    cy.get('[data-testid="counter-value"]').should('contain', '1');
  });
});

Key commands used here:

• cy.mount renders the component in the browser so Cypress can query its DOM.
• cy.get selects elements by selector. Prefer data-testid or other stable attributes over CSS classes that may change.
• should asserts on the element's state or text.

Run the test and check results

Run the component tests from the project root:

npx cypress run

Or open the interactive runner:

npx cypress open

Expected checks:

• The Test Runner lists the spec under the component testing section.
• The spec run ends with a passing status and no red failures in the command log.
• The command log shows cy.mount, click, and each should assertion passing in order.
• If a test fails, Cypress captures a screenshot or video according to your configuration, typically in the screenshots or videos directory under cypress.

Diagnose common failures

Symptom	Likely cause	Check or adjustment
Component renders blank or throws during mount	Missing bundler configuration or unresolved imports	Confirm the framework adapter and bundler are installed; check the browser console in the Test Runner for module errors.
Assertion times out	Slow render, animation, or asynchronous state update	Use a stable selector and avoid fixed waits; if the component relies on asynchronous data, mock that dependency or wait for a specific DOM change instead of using cy.wait with a hardcoded duration.
Test passes locally but fails in CI	Different browser viewport, missing fonts, or timing differences	Run the same browser version in CI as locally, and set retry attempts in the Cypress configuration file for flaky UI assertions.

Recovery and rollback

Adding component testing changes project state by installing a dev dependency and creating configuration and spec files. To remove it:

1. Delete the cypress/component directory.
2. Revert any component-testing additions to the Cypress configuration file.
3. Optionally run npm uninstall cypress if Cypress is no longer needed.

These steps remove test infrastructure without touching production source code.

Limitations

• Component tests run in a real browser, so CSS transitions, timers, and third-party widgets can introduce flakiness that does not appear in pure unit tests.
• Mounting one component in isolation does not verify routing, global state, or interactions between multiple components. Use end-to-end tests for those flows.
• Framework support depends on the Cypress version and the availability of a mounting library or adapter for your frontend framework.

Practical verification

After writing the spec, intentionally break one assertion—for example, change '1' to '2'—and run npx cypress run. Confirm the test fails and Cypress reports the expected versus actual value. Revert the change and confirm the suite passes again. This proves the test is actually exercising the component rather than passing vacuously.