Best Practices for Custom Commands in Cypress: A Detailed Guide

Aswani Kumar - Jul 11 - - Dev Community

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();
});
Enter fullscreen mode Exit fullscreen mode

Usage:

// cypress/integration/login.spec.js
describe('Login Tests', () => {
  it('Should login with valid credentials', () => {
    cy.login('test@example.com', 'password123');
    cy.url().should('include', '/dashboard');
  });
});
Enter fullscreen mode Exit fullscreen mode

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();
});
Enter fullscreen mode Exit fullscreen mode

Usage:

// cypress/integration/form.spec.js
describe('Form Tests', () => {
  it('Should submit the form with valid data', () => {
    const formData = {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com'
    };
    cy.fillForm(formData);
    cy.get('.success-message').should('be.visible');
  });
});
Enter fullscreen mode Exit fullscreen mode

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);
});
Enter fullscreen mode Exit fullscreen mode

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');
    });
  });
});
Enter fullscreen mode Exit fullscreen mode

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();
});
Enter fullscreen mode Exit fullscreen mode

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();
});
Enter fullscreen mode Exit fullscreen mode

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');
  });
});
Enter fullscreen mode Exit fullscreen mode

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!

. . . . . . . . . . . . . . . . . . . . . . . . . .