XQA
Back to Test Automation
2026-01-187 min read

Cypress Custom Commands

Learn Cypress Custom Commands step by step with clear examples and exercises.

Title: Cypress Custom Commands - A full guide for Test Automation with JavaScript

Why This Matters

Automated testing is essential for ensuring software quality and reducing manual effort. Cypress, a modern end-to-end testing solution, offers the ability to create custom commands that help in writing more efficient tests. This guide will walk you through creating and using custom commands in your test automation projects with JavaScript. By understanding and utilizing custom commands, you can write maintainable, readable, and testable code that improves the efficiency of your testing workflow.

Prerequisites

To follow this guide, you should have a basic understanding of:

  1. JavaScript: Familiarity with the language is essential for writing custom commands in Cypress.
  2. Cypress: Basic knowledge of Cypress and its end-to-end testing capabilities is required to understand how custom commands fit into the testing workflow. Additionally, it's helpful to have experience working with Selenium or Playwright for comparison purposes.
  3. Familiarity with npm (Node Package Manager) for installing and managing dependencies in your project.
  4. Understanding of Cypress test structure, including support files, plugins, and fixtures.
  5. Knowledge of HTML, CSS, and web technologies to create and interact with the elements on a web page during testing.

Core Concept

Cypress allows you to create custom commands that encapsulate reusable functionality in your tests. These commands can be defined globally or locally, and they make it easier to write maintainable, readable, and testable code.

To define a custom command, you can use the Cypress.Commands.add method. Here's an example of creating a custom command called login:

// In your support/commands.js file
Cypress.Commands.add('login', (username, password) => {
cy.visit('/login')
cy.get('#username').type(username)
cy.get('#password').type(password).submit()
})

In the example above, we've created a login command that visits the login page, enters the provided username and password, and submits the form. You can then use this custom command in your tests like so:

// In your test file
describe('Login Test', () => {
it('Should log in successfully', () => {
cy.login('testuser', 'testpassword')
// Continue with your test assertions here
})
})

Custom Command Options

Custom commands can have options that control their behavior. For example, the prevSubject: 'element' option ensures that the custom command operates on an element. Here's how to use it:

// In your support/commands.js file
Cypress.Commands.add('clickElementWithClass', { prevSubject: 'element' }, (className) => {
cy.get(`.**${className}**`).click()
})

Now, you can use this custom command in your tests like so:

// In your test file
describe('Click Element Test', () => {
it('Should click an element with a specific class name', () => {
cy.visit('/your-page')
cy.clickElementWithClass('example-class')
// Continue with your test assertions here
})
})

Custom Command Aliases

You can also create aliases for your custom commands using the as keyword:

// In your support/commands.js file
Cypress.Commands.add('login', (username, password) => {
cy.visit('/login')
cy.get('#username').type(username)
cy.get('#password').type(password).submit()
})

// Aliasing the login command as 'signIn'
Cypress.Commands.add('signIn', 'login')

Now, you can use the signIn alias in your tests like so:

// In your test file
describe('Login Test', () => {
it('Should log in successfully using the signIn alias', () => {
cy.signIn('testuser', 'testpassword')
// Continue with your test assertions here
})
})

Worked Example

Let's create a custom command for taking a screenshot of an element when it fails to load within a specific time frame.

  1. First, create a new file named support/commands.js. If it doesn't exist already.
  1. Add the following code to define the waitAndScreenshot command:
// In your support/commands.js file
Cypress.Commands.add('waitAndScreenshot', { prevSubject: 'element' }, (elem, timeout) => {
const defaultTimeout = 5000;
const finalTimeout = timeout || defaultTimeout;

cy.wrap(elem).should('be.visible', { timeout: finalTimeout })
.then(() => {
// Take a screenshot if the element is visible within the specified time frame
cy.log('Element loaded successfully')
})
.catch((error) => {
// If the element fails to load, take a screenshot and log the error
const screenshotName = 'element-failed-to-load'
cy.log(`Error: ${error}`)
cy.screenshot(screenshotName)
})
})
  1. Now you can use this custom command in your tests to take a screenshot when an element fails to load within a specific time frame.
// In your test file
describe('Element Load Test', () => {
it('Should take a screenshot if the element fails to load', () => {
cy.visit('/your-page')
cy.get('#element').waitAndScreenshot(1000) // Wait for 1 second before taking the screenshot
// Continue with your test assertions here
})
})

Common Mistakes

  1. Not defining custom commands in the correct file: Custom commands should be defined in the support/commands.js file to ensure they are available across all tests.
  2. Missing the prevSubject: 'element' option: When defining a custom command that operates on an element, make sure to include the prevSubject: 'element' option to avoid errors.
  3. Not handling errors properly: If your custom command doesn't handle errors correctly, it can lead to test failures or unexpected behavior. Make sure to catch and log any errors that occur during the execution of your custom commands.
  4. Not using cy.wrap() for chaining commands: When working with elements returned by cy.get(), use cy.wrap() to chain additional commands without encountering errors.
  5. Incorrectly defining command names: Make sure to define command names in lowercase, as Cypress converts them to camelCase automatically when used in your tests.
  6. Not using the correct syntax for options: When defining custom command options, use the { prevSubject: 'element' } format instead of prevSubject: 'element'.
  7. Not considering test isolation: Ensure that your custom commands do not affect other tests by creating isolated fixtures or setting up and tearing down test data as needed.

Practice Questions

  1. Write a custom command for clicking an element with a specific class name.
  2. Create a custom command for verifying that a specific text appears on the page within a given time frame.
  3. Implement a custom command for logging in to your application using a custom API endpoint.
  4. Create a custom command that simulates user interaction with a dropdown menu by clicking the menu button and selecting an option.
  5. Write a custom command that takes a screenshot of the current viewport when a specific condition is met during the test execution.
  6. Implement a custom command for validating the presence of multiple elements on a page using a given CSS selector.
  7. Create a custom command that simulates user interaction with a slider by adjusting its value to a specific number.
  8. Write a custom command for verifying that a modal or dialog box is displayed and contains certain text.
  9. Implement a custom command for validating the content of a table on a web page, including row count, column names, and cell values.
  10. Create a custom command for simulating user interaction with a date picker by selecting a specific date from the calendar.

FAQ

Q: Can I define global custom commands in Cypress?

A: Yes, you can define global custom commands by placing them in the support/commands.js file.

Q: How do I use a custom command in my tests?

A: To use a custom command in your tests, simply call it like any other Cypress command within the test body.

Q: Can I pass arguments to my custom commands?

A: Yes, you can pass arguments to your custom commands by defining them as function parameters when using Cypress.Commands.add.

Q: How do I handle errors in custom commands?

A: To handle errors in custom commands, use try-catch blocks and log the error messages for debugging purposes.

Q: Can I use custom commands with Selenium or Playwright?

A: While Cypress is a modern end-to-end testing solution, you can create similar custom commands using JavaScript with Selenium WebDriver (using languages like Java, Python, etc.) and Playwright (using JavaScript). However, the specific implementation may vary between these tools.

Q: Can I use async/await syntax in my custom commands?

A: Yes, you can use async/await syntax in your custom commands to make them more readable and easier to work with.

Q: How do I test custom commands themselves?

A: To test custom commands, create separate test files or test functions that call the custom command and verify its behavior using assertions.

Q: Can I use custom commands in integration tests?

A: Yes, you can use custom commands in integration tests just like any other Cypress commands.

Q: How do I share custom commands between projects or teams?

A: To share custom commands between projects or teams, create a separate package using npm and publish it to a repository like npm or GitHub Packages for easy distribution and reuse.

Q: Can I use custom commands with Cypress plugins?

A: Yes, you can use custom commands in Cypress plugins to extend the functionality of your testing workflow.

Cypress Custom Commands | Test Automation | XQA Learn