DEV Community: Saurabh Naigaonkar

Streamlining Cypress Test Automation with cypress-plugin-steps

Saurabh Naigaonkar — Thu, 13 Mar 2025 18:07:10 +0000

When it comes to end-to-end testing with Cypress, clarity and maintainability are key. Writing readable tests not only helps developers but also makes debugging easier when something goes wrong. In this blog, we'll explore how the cypress-plugin-steps package can improve your Cypress testing experience by adding step tracking, clear error messages, and enhanced organization to your test runs. Let’s dive into how this small but powerful plugin can elevate your test automation workflow.

What is `cypress-plugin-steps`?

The cypress-plugin-steps is a lightweight Cypress plugin designed to help you structure your tests in a more readable and organized way. It adds two new commands to your Cypress library: cy.step() and cy.section(). These commands allow you to break down your tests into discrete steps and sections, with each step numbered and clearly visible in the Cypress runner and error logs.

Key Features

Step Numbering: Adds automatic step numbering to each action in your test.
Organized Error Messages: Includes the test steps in error messages, helping you quickly pinpoint where things went wrong.
Sectioning: Helps break your tests into sections for better clarity and debugging.

Installation
Usage
- cy.step()
- cy.section()
Bonus Tip: Replace cy.log() with cy.step()

Installation

To get started with cypress-plugin-steps, you first need to install the package. You can do this using npm or Yarn.

Install via npm:

npm install cypress-plugin-steps

Or install via Yarn:

yarn add cypress-plugin-steps

Once installed, you need to import the plugin into your cypress/support/e2e.js file.

import 'cypress-plugin-steps';
// or
require('cypress-plugin-steps');

TypeScript Support

If you're using TypeScript, cypress-plugin-steps has built-in type declarations. In most cases, the types will work automatically upon installing the plugin. However, if you need to ensure TypeScript is aware of the types, add this to your tsconfig.json:

{
  "types": ["cypress-plugin-steps"]
}

This will provide type safety for cy.step() and cy.section().

Usage

Now that you’ve installed the plugin, let’s explore how to use it.

`cy.step()`

The cy.step() command works similarly to cy.log(), but with the added benefit of automatic step numbering. This makes your tests more readable by displaying each step in the Cypress test runner and log output.

Here’s an updated example:

describe('User Signup Test', () => {
  it('should allow a user to sign up', () => {

    cy.step('Visit the signup page');
    cy.visit('/signup');

    cy.step('Fill out the registration form');
    cy.get('#username').type('newuser');
    cy.get('#password').type('securepassword');
    cy.get('#email').type('user@example.com');

    cy.step('Submit the registration form');
    cy.get('button[type="submit"]').click();

    cy.step('Verify successful registration');
    cy.contains('Welcome, newuser!').should('be.visible');
  });
});

In this example, each test step is clearly numbered, making it easy to follow the flow of the test. If the test fails, the error message will include the step number and description, providing useful context.

Error Messages

The integration with Cypress' built-in error handling is one of the standout features of cy.step(). If a test fails, the error message includes the failed step number and description, which helps you pinpoint exactly where the issue occurred.

For example, when a failure occurs, the error message in the terminal will look something like this:

Error: Expected element to be visible at step 4: "Verify successful registration"

The scenario is also captured in the Cypress screenshot, which automatically includes the context of each test step.

`cy.section()`

While cy.step() is great for numbering individual steps, cy.section() is perfect for dividing your tests into sections. Sections are useful when you need to organize complex tests or visually group related steps together.

cy.section() behaves similarly to cy.step(), but with these differences:

It resets the step counter after each section.
It adds a more prominent divider (using ---) in the Cypress runner log for better visual distinction.

Here’s an example of how to use cy.section():

describe('Login and Dashboard Test', () => {
  it('should allow a user to log in and access their dashboard', () => {

    cy.section('Login Process');
    cy.step('Visit the login page');
    cy.visit('/login');

    cy.step('Enter valid credentials');
    cy.get('#username').type('validuser');
    cy.get('#password').type('validpassword');
    cy.get('button[type="submit"]').click();

    cy.section('Dashboard Access');
    cy.step('Wait for the dashboard to load');
    cy.contains('Dashboard').should('be.visible');

    cy.step('Verify dashboard items are present');
    cy.get('.item-list').should('exist');
  });
});

In this example, the test is broken into two sections: "Login Process" and "Dashboard Access." Each section is clearly labeled in the test runner, and the step counter resets after each section, making it easy to track progress.

Bonus Tip: Replace `cy.log()` with `cy.step()`

A helpful tip is to replace all instances of cy.log() with cy.step(). This not only numbers your steps but also improves the organization of your test logs. You can achieve this by running a find-and-replace using this regex:

(?:cy\s*)?log\s*

By making this change across your tests, you ensure that each action is numbered, which improves the clarity of your test output and logs.

Conclusion

The cypress-plugin-steps plugin is a simple yet effective tool for organizing and improving the readability of your Cypress tests. By adding step numbering and sectioning, it helps you visualize and structure your tests in a way that’s easier to follow. This makes debugging faster and helps maintain cleaner test code over time.

So, if you’re looking to streamline your Cypress testing workflow, give cypress-plugin-steps a try. It’s a small addition to your project, but the impact it has on your test clarity and maintainability is huge.

Improve Your Cypress Tests with the Cypress Testing Library Plugin!

Saurabh Naigaonkar — Thu, 06 Mar 2025 13:47:34 +0000

As a SDET, I’m always on the lookout for plugins that can elevate the quality and efficiency of our tests. Today, I’m thrilled to introduce a plugin that brings best practices from the React Testing Library into the world of Cypress: the Cypress Testing Library Plugin! 🎉

If you’ve ever struggled with selecting elements in tests or wanted to ensure your tests are written with an accessibility-first mindset, this plugin is for you. The Cypress Testing Library Plugin helps you write tests that more closely resemble how users interact with your application, making your tests more resilient, maintainable, and user-centric.

Let’s dive into how this plugin works and why it’s such a powerful tool in your testing arsenal!

🚀 What Is the Cypress Testing Library Plugin?

The Cypress Testing Library Plugin integrates the core concepts of the Testing Library with Cypress. It focuses on using queries that reflect how users interact with your web pages—such as by text, role, and labels—rather than relying on brittle CSS selectors or XPath queries. This approach ensures your tests are not tightly coupled to the implementation details of your UI, making them more stable and less likely to break when UI changes occur.

🔧 Installation & Setup

Getting started with the Cypress Testing Library Plugin is a breeze. Just follow these steps:

Install the Plugin:

   npm install --save-dev @testing-library/cypress

Import the Plugin into your Cypress support file (e.g., cypress/support/commands.js):

   import '@testing-library/cypress/add-commands';

That’s it! You’re now ready to start writing more user-centric tests with Cypress Testing Library commands.

🛠️ How to Use It?

With the plugin installed, you can now use the user-friendly queries to interact with elements in your tests. Here are some examples of how to use the new commands:

1. Querying by Text Content (What the user sees)

Let’s say you have a button with the text "Submit". You can query it in a more user-friendly way:

it('should submit the form', () => {
  cy.visit('/login');
  cy.findByText('Submit').click(); // Find the button by its text
  cy.url().should('include', '/dashboard');
});

2. Querying by Label Text (Accessible Forms)

If you have a form field with a label, you can query it based on the label text:

it('should type into the email input', () => {
  cy.visit('/login');
  cy.findByLabelText('Email').type('test@example.com');
  cy.findByLabelText('Email').should('have.value', 'test@example.com');
});

This approach makes sure your test is accessible, and the user will be interacting with it the same way!

3. Querying by Role (for Accessibility)

You can query elements based on their role. For instance, a button can be queried using its role of "button":

it('should click the submit button', () => {
  cy.visit('/login');
  cy.findByRole('button', { name: /submit/i }).click();
  cy.url().should('include', '/dashboard');
});

This ensures your tests are accessibility-compliant and resilient to UI changes like class or ID changes.

🔥 Why Use the Cypress Testing Library Plugin?

1. Encourages Best Practices

The plugin encourages testing your UI in the same way your users interact with it. Rather than using selectors that may break when the UI changes, you focus on text and roles—which makes tests more resilient to changes in implementation.

2. Enhances Accessibility

By using queries like findByLabelText() and findByRole(), you’re naturally writing more accessible tests. This helps you build web apps that are not only functional but also compliant with accessibility standards.

3. Less Fragile Tests

Traditional Cypress tests often rely on class names or IDs, which can easily change. By focusing on user interactions and semantic HTML (like labels and roles), your tests will be less likely to break during UI changes.

4. Aligns with User-Centered Testing

The Cypress Testing Library Plugin moves your tests closer to how users will actually interact with your app. This user-centric approach leads to tests that are more reflective of real-world scenarios, resulting in better testing coverage.

5. Simpler Syntax

The plugin simplifies the syntax for interacting with elements, making your tests cleaner, easier to read, and more maintainable. There’s no need to worry about finding the right CSS selector or XPath anymore.

🏆 Use Case Example: Form Testing

Let’s say you’re testing a login form. With the Cypress Testing Library Plugin, your test becomes more readable and user-centric:

it('should show an error for incorrect credentials', () => {
  cy.visit('/login');

  // Find the input fields by their label text
  cy.findByLabelText('Email').type('invalid@example.com');
  cy.findByLabelText('Password').type('wrongpassword');

  // Find the submit button by its text
  cy.findByText('Submit').click();

  // Assert the error message appears
  cy.findByText('Invalid credentials').should('be.visible');
});

🌟 Final Thoughts

The Cypress Testing Library Plugin takes your Cypress tests to the next level by focusing on user interactions, accessibility, and resilient test practices. Whether you’re building an application with Web Components, working with forms, or testing complex UI workflows, this plugin will help you write more reliable, easy-to-maintain tests that align with how users interact with your app.

If you haven’t tried the Cypress Testing Library Plugin yet, I highly recommend you give it a shot. It will help you create more robust, accessibility-compliant, and user-friendly tests that better reflect your users’ needs!

Do you use the Cypress Testing Library Plugin in your tests? Share your experiences below or drop a comment if you have any questions. Let's talk about best practices for writing resilient tests! 🚀

"#Cypress #TestingLibrary #Accessibility #AutomationTesting #EndToEndTesting #WebTesting #UserCentricTesting #CypressPlugin"

Why This is Unique:

User-Centric Testing: The plugin helps you write tests that mimic real user interactions, improving the relevance and reliability of your tests.
Focus on Accessibility: Encourages using semantic HTML for selecting elements, which naturally enhances accessibility in your application.
Best Practices: Aligns with the best practices from the React Testing Library, focusing on testing how users interact with the page instead of testing implementation details.

This plugin helps make your tests more maintainable and future-proof, ensuring that they stay aligned with both user behavior and accessibility standards.