10 Cypress Selector Best Practices

Cypress is a powerful testing framework that allows developers to write end-to-end tests for their web applications. One of the most important aspects of writing tests with Cypress is selecting the right elements on the page. Selectors are used to identify elements on the page and Cypress provides a variety of options for selecting elements.

In this article, we will discuss 10 best practices for selecting elements with Cypress. We will cover topics such as using data-test attributes, avoiding complex selectors, and using the Cypress.Selector utility. Following these best practices will help you write more reliable and maintainable tests.

1. Use data-cy attributes

Data-cy attributes are custom HTML attributes that you can add to your elements. They allow Cypress to easily identify and select specific elements on the page, without having to rely on complex CSS selectors or XPath expressions. This makes it easier for developers to write tests quickly and accurately.

Using data-cy attributes also helps keep your codebase organized and maintainable. By adding descriptive names to each element, you can easily find them in the future when making changes or debugging issues.

2. Avoid using id selectors

Id selectors are not reliable because they can change over time. If you use an id selector to locate an element, and then the id of that element changes, your test will fail. This is why it’s best practice to avoid using id selectors when writing Cypress tests.

Instead, try to use class or data-test attributes as selectors. These types of selectors are more reliable since they don’t change as often as ids do. Additionally, if you’re using a framework like React, you can take advantage of its built-in testing utilities to create custom data-test attributes for each component.

3. Don’t use complex CSS selectors

Complex selectors can be difficult to read and maintain, making it harder for other developers to understand your code. Additionally, complex selectors are more prone to breaking when the page structure changes, which could lead to unexpected test failures.

Instead of using complex CSS selectors, try to use simpler ones that target specific elements on the page. For example, you can use an element’s ID or class name if available, or even a combination of attributes like type, name, value, etc. This will make your tests easier to read and maintain, as well as less likely to break due to page structure changes.

4. Don’t use XPath selectors

XPath selectors are slow and unreliable. They can be difficult to read, debug, and maintain. Additionally, XPath selectors are not supported in all browsers, so they may not work as expected across different environments.

Instead of using XPath selectors, use the built-in Cypress selector methods such as .get() or .find(). These methods are faster and more reliable than XPath selectors. Plus, they are easier to read and maintain.

5. Use the .should() command to assert your element is visible

The .should() command allows you to make sure that the element you are selecting is actually visible on the page. This helps prevent false positives when running your tests, as it ensures that the element you are trying to select is actually present and visible in the DOM.

It also helps ensure that any changes made to the page don’t break your tests, as the .should() command will fail if the element isn’t found or isn’t visible. This can help save time debugging issues with your tests, as you’ll know right away if something has changed on the page.

6. Use the .within() command when you need to scope a selector

The .within() command allows you to scope a selector so that it only looks for elements within the specified element. This is important because if you don’t use this command, Cypress will search through all of the elements on the page and could return incorrect results.

For example, let’s say you have two buttons with the same class name but different text values. If you don’t use the .within() command, Cypress may select the wrong button. By using the .within() command, you can ensure that Cypress only searches within the specified element and returns the correct result.

7. Use the .as() command for reusing selectors

The .as() command allows you to store a selector in a variable, which can then be used multiple times throughout your test. This helps reduce the amount of code that needs to be written and makes it easier to maintain tests over time. It also ensures that if the underlying HTML changes, you only need to update the selector once instead of having to go through all of your tests and make sure they are still valid.

8. Use .and() and .invoke() commands to chain multiple actions together

The .and() command allows you to chain multiple actions together, so that they are all executed in one go. This is useful when you need to perform a series of steps on the same element or set of elements. For example, if you wanted to click an element and then type some text into it, you could use the .and() command to do both at once.

The .invoke() command is similar to the .and() command, but instead of chaining multiple actions together, it allows you to call a function with arguments. This can be used to pass data from your test code into the page being tested, which can be very useful for testing complex interactions.

9. Use the .filter() command to reduce the number of elements in a collection

When you use a selector to find elements on the page, Cypress will return all matching elements. This can be problematic if there are multiple elements with the same class or ID name. To avoid this issue, you should use the .filter() command to narrow down your selection and only select the element that you need.

For example, let’s say you want to click on an element with the class “button”. Instead of using cy.get(‘.button’), you could use cy.get(‘.button’).filter(‘[data-test=”myButton”]’) to make sure you’re selecting the correct element.

Using the .filter() command is one of the best practices when working with Cypress selectors because it helps ensure that you’re selecting the right element every time.

10. Use the .eq() command to access an item from a collection

The .eq() command allows you to access a specific item from a collection of elements. This is important because it ensures that your tests are not dependent on the order in which the elements appear in the DOM. If you use other methods, such as .first(), or .last(), then your tests may fail if the order of the elements changes.

Using the .eq() command also makes your code more readable and easier to maintain. It’s much clearer when you can see exactly which element you’re targeting instead of relying on an index number.