Best Practices for Custom Commands in Cypress: A Detailed Guide

Introduction

In our previous post, we introduced the concept of custom commands in Cypress and demonstrated how they can simplify and enhance your testing framework. This follow-up post dives deeper into the best practices for creating and using custom commands, providing detailed examples to ensure your tests are maintainable, readable, and robust.

Why Best Practices Matter

Following best practices when creating custom commands ensures that your tests remain scalable, easy to understand, and quick to update. Properly structured custom commands can significantly reduce code duplication and improve the overall quality of your test suite.

Best Practices for Custom Commands

1. Name Commands Clearly
Clear and descriptive names make your commands easy to understand and use. A good command name should convey its purpose without needing additional context.
Example:

// cypress/support/commands.js
Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login');
  cy.get('input[name=email]').type(email);
  cy.get('input[name=password]').type(password);
  cy.get('button[type=submit]').click();
});

Usage:

// cypress/integration/login.spec.js
describe('Login Tests', () => {
  it('Should login with valid credentials', () => {
    cy.login('[e-mail]', 'password123');
    cy.url().should('include', '/dashboard');
  });
});

2. Parameterize Commands
Commands should accept parameters to enhance their flexibility and reusability. This allows the same command to be used in different contexts with different data.

Example:

// cypress/support/commands.js
Cypress.Commands.add('fillForm', (formData) => {
  cy.get('input[name=firstName]').type(formData.firstName);
  cy.get('input[name=lastName]').type(formData.lastName);
  cy.get('input[name=email]').type(formData.email);
  cy.get('button[type=submit]').click();
});

Usage:

// cypress/integration/form.spec.js
describe('Form Tests', () => {
  it('Should submit the form with valid data', () => {
    const formData = {
      firstName: 'John',
      lastName: 'Doe',
      email: '[e-mail]'
    };
    cy.fillForm(formData);
    cy.get('.success-message').should('be.visible');
  });
});

3. Chain Commands
Ensure custom commands return Cypress chainables using cy.wrap() to enable chaining and maintain the flow of Cypress commands.

Example:

// cypress/support/commands.js
Cypress.Commands.add('selectDropdown', (selector, value) => {
  cy.get(selector).select(value).should('have.value', value);
  return cy.wrap(value);
});

Usage:

// cypress/integration/dropdown.spec.js
describe('Dropdown Tests', () => {
  it('Should select a value from the dropdown', () => {
    cy.visit('/dropdown-page');
    cy.selectDropdown('#dropdown', 'Option 1').then((value) => {
      expect(value).to.equal('Option 1');
    });
  });
});

4. Document Commands
Add comments to your custom commands to describe their purpose and usage. This helps other developers understand your code and use it correctly.

Example:

// cypress/support/commands.js

/**
 * Custom command to login to the application
 * @param {string} email - User email
 * @param {string} password - User password
 */
Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login');
  cy.get('input[name=email]').type(email);
  cy.get('input[name=password]').type(password);
  cy.get('button[type=submit]').click();
});

5. Modularize Common Actions
Encapsulate common actions within custom commands to promote reuse and reduce duplication. This also makes tests more readable by abstracting complex interactions.

Example:

// cypress/support/commands.js
Cypress.Commands.add('addItemToCart', (itemName) => {
  cy.get('.product-list').contains(itemName).click();
  cy.get('.add-to-cart').click();
});

Usage:

// cypress/integration/cart.spec.js
describe('Cart Tests', () => {
  it('Should add an item to the cart', () => {
    cy.visit('/shop');
    cy.addItemToCart('Laptop');
    cy.get('.cart-items').should('contain', 'Laptop');
  });
});

Conclusion

By following these best practices, you can create custom commands in Cypress that are not only powerful but also maintainable and easy to understand. Clear naming, parameterization, chaining, documentation, and modularization are key to writing effective custom commands. Implement these practices in your test automation framework to enhance the quality and efficiency of your tests.

Start refining your custom commands today, and take your Cypress tests to the next level. Happy testing!