Cypress Component Testing: A Complete Tutorial

Cypress has become a popular choice for front-end developers, especially when it comes to building modern web applications. Cypress component testing provides a way to test individual modules of your user interface. This ensures that components behave as expected throughout development.

What Is Component Testing With Cypress?

Component testing in Cypress is a technique to verify if an individual part of a user interface, like a button or form, works on its own. With Cypress, you can run these tests right in the browser to see exactly how your component behaves in different conditions without the need to start the whole web application.

The main difference between Cypress component testing and Cypress end-to-end testing is their scope. Component testing focuses mainly on a single UI element in isolation whereas E2E testing covers the entire application workflow.

Getting Started With Cypress Component Testing

Let’s dive into Cypress component testing using a real-world example. I cloned a section on the Write for Us page from the LambdaTest website with React and SASS.

You can either use this project to follow along, or you can use any existing React project. You’ll still get the same result. All you have to do is follow the steps accordingly.

If you want to use the project, clone this Cypress Component Testing GitHub repository.

Prerequisites

To follow along with this Cypress component testing tutorial, make sure to:

• Install Node.js.
• Have npm or yarn as your package manager.

Set Up React Project for Component Testing

Before configuring Cypress for component testing, you need a project to work with.

Note: If you already have a React project, you can skip to the next section.

1. Create a React App

Use Vite for a rapid, modern development experience. Open your terminal and run:

This command will launch an interactive setup where you:

• Enter a name for your project
• Select a framework (choose React)
• Pick a language (select JavaScript, unless you prefer TypeScript)

2. Move Into Your Work Directory and Install Dependencies

Run the below command to move into your work directory and install the dependencies:

3. Add SASS for Styling (Optional)

Run the below command to install SASS:

4. Folder structure

This is how a folder structure looks like:

Yours might look different, maybe due to folder name, file name, or how you created your app, but in the end, you’ll still achieve the same result if you follow up.

Our main focus in this Cypress tutorial will be on the <Form /> component. We’ll use Cypress to test the input fields, checking their placeholders and ensuring they accept user input.

5. Add your React component

Here’s what App.jsx file looks like:

This is not our main focus, but it’s good that you see the code in each file down to the very one we’re testing, especially if you want to practice with this same code example.

In the App.tsx component, we have <Navbar /> and <SubmitBlog />. However, we’re more concerned with the <SubmitBlog /> component, which contains a form we’ll be working with.

The SubmitBlog component contains SubmitBlogContent and Form. The SubmitBlogContent component is an image and title for the section. Finally, here’s the Form.jsx code we want to test:

Here’s the styling:

Configure Cypress for Component Testing

Now that we have a working React project, the next step is to set up Cypress for component testing. Cypress allows you to test individual components of your application, which makes it easier to identify UI bugs early in development.

1. Install Cypress

First, install Cypress as a development dependency:

2. Open Cypress

Once installed, launch Cypress using:

This command opens the Cypress App (Test Runner). You’ll be prompted to choose the type of testing:

• End-to-End (E2E) Testing
• Component Testing

For this tutorial, select Component Testing.

3. Configure Framework and Bundler

After selecting component testing, Cypress will ask you to configure your setup:

• Framework: React
• Bundler: Vite

This ensures Vite is available as a dev dependency for Cypress to use internally.

4. Verify Vite Installation

Check your package.json file in the devDependencies section. If Vite is missing, install it:

5. Finalize Setup in Cypress

Click “Continue” in the Cypress app.

Select your preferred browser (I am using Electron), and then click “Start Component Testing in Electron”.

Write Component Tests

We’ll write a Cypress component test to check:

• The form renders correctly.
• All input fields exist.
• You can type into the input fields and submit the form.

First, add data-cy attributes to the form elements in the Form.jsx file:

1. Create the Test File

Inside the cypress folder:

2. Write the test

Key Notes:

• Use describe to group tests and it to define test cases.
• Import React and the component explicitly.
• Use cy.mount() to render the component in the Cypress Test Runner.

Run Cypress Component Tests

Start Cypress in component testing mode:

Or use:

Then click the Form.cy.jsx file to run the test. Cypress will render the form and execute all assertions in real-time.

How to Run Cypress Component Tests on Cloud?

Running Cypress component tests locally works well, but for larger test suites, team collaboration, or CI integration, running tests on the cloud is better. We’ll use HyperExecute, an end-to-end test orchestration platform from LambdaTest.

Clone React Project

We’ll use a simple React project from the Cypress GitHub Repository, specifically the “react-webpack5-js” example.

1. Clone the repository to your local machine.
2. Navigate to the react-webpack5-js folder.

Running Test on HyperExecute

HyperExecute provides a pre-configured environment for faster testing. It supports Cypress, Selenium, Playwright, Appium, and multiple languages like Python, Java, C#, PHP, and Go.

1. Create a folder and YAML file

Create a folder in your project root, and inside it, create matrix.yml with the following configuration:

2. Download and Add HyperExecute CLI

Download the HyperExecute CLI for your OS and place it in your project root. It reads the YAML configuration and uses your LambdaTest credentials.

3. Upload and Run Your Tests

Run this command in your terminal to upload and run your tests on HyperExecute:

Replace <user_name> and <access_key> with your LambdaTest credentials.

4. View Your Tests on HyperExecute Dashboard

Navigate to HyperExecute, and click your test to view execution tasks and logs.

Best Practices for Cypress Component Testing

To effectively carry out component testing with Cypress, you need to follow some best practices. They will make your tests reliable, readable, and easy to maintain:

• Use data-* Attributes for Targeting Elements: Avoid using class names or tag selectors like input, .btn, or .form-control in your tests.

They are too generic and are more likely to change during code refactoring. Instead, use custom attributes like data-cy or data-testid. They are more stable and specifically meant for testing.

• Keep Tests Focused and Isolated: Test one component at a time. Each test should focus on a particular feature or behavior.

Avoid testing too many things in a single test block. Isolating your test makes it easier to identify where something is going wrong.

// Good it('shows validation error for empty email', () => { ... }); // Bad it('renders, fills form, validates fields, submits, and checks success message', () => { ... });

1 2 3 4 5

// Good it('shows validation error for empty email', () => { ... });   // Bad it('renders, fills form, validates fields, submits, and checks success message', () => { ... });

• Reset State Between Tests: Use beforeEach() to mount the component fresh each time.
beforeEach(() => { cy.mount(&lt;Form /&gt;); });

1 2 3

beforeEach(() => { cy.mount(<Form />); });

• Test Both Visual and Interactive Behavior: Don’t just check if the component renders. Interact with it like a real user would. Type into fields, click buttons, and assert the outcome.
• Optimize Tests for Speed: Component tests should run quickly. Avoid unnecessary delays, timers, or complex setups that slow them down. If you need to mock data or props, do it efficiently.
• Use Meaningful Descriptions: Your test names should describe what is being tested, not how it’s done. Think of them like user stories.
// Good it('displays an error when email is empty'); // Bad it('checks if email input works');

1 2 3 4 5

// Good it('displays an error when email is empty');   // Bad it('checks if email input works');

Troubleshooting Tips for Cypress Component Tests

One way or the other, issues will come up when writing or running Cypress component tests. Here are some common issues and how to troubleshoot them.

• Component Doesn’t Render in the Test Runner: Sometimes you might want to run your test, but nothing shows up. This can be because the component is missing or the test fails immediately.

Possible causes include:

• You forgot to call cy.mount()
• You’re missing a required prop
• The component has runtime errors

Make sure the component is mounted correctly, and if it requires props, pass them.

cy.mount(<UserCard user={prop} />);

1	cy.mount(<UserCard user={prop} />);

Also, check the browser console in the Cypress Test Runner for any React errors.

• Styling Looks Broken: Your component might render perfectly, but it looks weird, maybe because it’s missing some styles or has the wrong layout. This happens a lot when you forget to import the component’s styling file.

Always import styles manually in your test file.

import '../../src/components/Form/Form.module.scss';

1	import '../../src/components/Form/Form.module.scss';

If you’re using CSS modules or SCSS, make sure your build tool (like Vite or Webpack) is configured to handle them in Cypress.

• State Persists Between Tests: When one test affects another, like data from a previous test showing up in the next one, use beforeEach() to reset the component before each test:
beforeEach(() => { cy.mount(<Form />); });

1 2 3

beforeEach(() => {   cy.mount(<Form />); });

Also, avoid using .only and .skip except when you’re debugging.

• Props Not Working as Expected: When you pass props but the component doesn’t behave the way it does in the actual app, it could be because props are missing or misconfigured, or you’re not mocking external dependencies (like APIs).

Make sure you’re passing all required props in cy.mount().

• JSX Won’t Compile or Test File Crashes: You see a build error or a test file fails to load when using JSX. This can be because the file extension is .js instead of .jsx, or you forgot to import React (if your config requires it).

To fix this, use the .cy.jsx extension.

Form.cy.jsx

1	Form.cy.jsx

And import React in your test file:

import React from 'react';

1	import React from 'react';

Conclusion

Cypress component testing bridges the gap between isolated unit tests and full end-to-end scenarios, giving developers confidence that their UI behaves as expected. By setting up the environment properly, following best practices, and organizing tests effectively, you ensure faster feedback and fewer regressions. Leveraging cloud platforms further enhances Cypress testing with scalability, and parallel execution, making the workflow efficient for modern teams.

Citations

• Cypress Component Testing: https://docs.cypress.io/app/component-testing/get-started