Streamlining Cypress Test Automation with cypress-plugin-steps

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.

Table of Contents

• 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:

1. It resets the step counter after each section.
2. 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.