What is Cypress Testing Library and its Usage
By Gurudatt S A, Community Contributor - October 31, 2022
Web Elements are pivotal in the user experience and hence need to be tested thoroughly for customer engagement. Browser Automation using frameworks like Cypress is widely used for testing web elements. To query web elements, Cypress provides commands like get(), contains(), find() and within(). Using these commands, you further need to chain commands based on how you want to query an element.
For example, To find an element based on its text content, you need to use the below command
cy.contains(“MyText”) To query an element based on a custom attribute use the below command
cy.get(“[data-cy=’myId’]”)Cypress Testing Library is the integration of the DOM Testing library with Cypress. Let us understand the DOM Testing library first.
DOM Testing Library is the lightweight testing library for DOM nodes that provides methods resembling the way a user finds elements on the Web Page.
Detailed API information can be found here
Installation and Setup of Cypress Testing Library
To install the cypress-testing-library, in the terminal from your root cypress project, execute the below command:
npm install --save-dev @testing-library/cypress
This will install the cypress-testing-library as a dev dependency.
Once the installation is successful, you need to import the reference of cypress-testing-library in our cypress/support/commands.js file.
import '@testing-library/cypress/add-commands'
This will chain all of the cypress-testing-library API to cy object.
Cypress Testing Library APIs
There are several APIs in the Cypress Testing Library, as seen below.
| API | Definition |
|---|---|
| findByPlaceholderText | <input type=“text” placeholder=“Input 1” id=“by-text-input”> With an element like above, we can then use the API as like below cy.findByPlaceholderText(“Input 1”) With this API we can find the element by its Placeholder text. This api will throw error if there are more than 1 matching element |
| findAllByPlaceholderText | <input type=“text” placeholder=“Input 1” id=“by-text-input”> <input type=“text” placeholder=“Input 2” id=“by-text-input-2”>With the above elements, if we need to find both the elements then we write cypress command likecy.findAllByLabelText(/^Input \d$/) |
| findByLabelText | <label for=“by-text-input”>Label 1</label> With above element we can see that Label element has text “Label 1” Our Cypress command will be cy.findByLabelText(“Label 1”) |
| findAllByLabelText | <label for=“by-text-input”>Label 1</label> <label for=“by-text-input-2”>Label 2</label>If we want get multiple elements matching for the provided label text, we can write our cypress command likecy.findAllByLabelText(/^Label \d$/) |
| findByText | <button onclick=“this.innerText = ‘Button Clicked'”>Button Text 1</button> With the above element, if we need to find the element by its matching text, we can write our cypress command like cy.findByText(“Button Text 1”) |
| findAllByText | <button onclick=“this.innerText = ‘Button Clicked'”>Button Text 1</button> <button onclick=“this.innerText = ‘Button Clicked'”>Button Text 2</button>We can use this API when we want to find more than 1 element by its textcy.findAllByText(/^Button Text \d$/) |
| findByDisplayValue | <input type=“text” value=“Display Value 1”> We can use this API when we want to find the element by its value attribute cy.findByDisplayValue(“Display Value 1”) |
| findAllByDisplayValue | <input type=“text” value=“Display Value 1”> <input type=“text” value=“Display Value 2”>We can use this API when we want to find multiple elements matching the valuecy.findAllByDisplayValue(/^Button Text \d$/) |
| findByAltText | <img src=“data:image/png;base64,” alt=“Image Alt Text 1” onclick=“this.style.border = ‘5px solid red'”> We can use this API when we want to find the element based on its alt attribute cy.findByAltText(“Image Alt Text 1”) |
| findAllByAltText | <img src=“data:image/png;base64,” alt=“Image Alt Text 1” onclick=“this.style.border = ‘5px solid red'”> <img src=“data:image/png;base64,” alt=“Image Alt Text 2” onclick=“this.style.border = ‘5px solid red'”>We can use this API when we want to find multiple elements matching the alt attribute |
| findByTitle | <span title=“Title 1”>1</span> We can use this API when we want to find element based on its title attribute cy.findByTitle(“Title 1”) |
| findAllByTitle | <span title=“Title 1”>1</span> <span title=“Title 2”>2</span>We can use this API when we want to find multiple elements based on its title attributecy.findAllByTitle(/^Title \d$/) |
| findByRole | <div role=“dialog”>dialog 1</div> We can use this API when we want to find element based on its role attribute cy.findByRole(“dialog”) |
| findAllByRole | <div role=“dialog”>dialog 1</div> <div role=“dialog-fake”>dialog 2</div>We can use this API when we want to find multiple elements based on role attributecy.findAllByRole(/^dialog/) |
| findByTestId | <img data-testid=“image-with-random-alt-tag-1” src=“data:image/png;base64,” onclick=“this.style.border = ‘5px solid red'” alt=“Image Random Alt Text 0.9710155761447143”> We can use this API when all our elements are added with custom test attribute like data-testid. Then we can just pass the custom attribute value to this API. cy.findByTestId(“image-with-random-alt-tag-1”) Note: We can also change the default custom attribute by adding below line in our cypress/support/index.js import {configure} from ‘@testing-library/cypress’ configure({testIdAttribute: ‘data-test-id’}) |
| findAllByTestId | <img data-testid=“image-with-random-alt-tag-1” src=“data:image/png;base64,” onclick=“this.style.border = ‘5px solid red'” alt=“Image Random Alt Text 0.9710155761447143”> <img data-testid=“image-with-random-alt-tag-2” src=“data:image/png;base64,” onclick=“this.style.border = ‘5px solid red'”>We can use this API to find multiple elements based on the custom test attributecy.findAllByTestId(/^image-with-random-alt-tag-\d$/) |
Cypress test examples using these commands can be found here.
Below is the example cypress test using BrowserStack demo app
it("validate the element existance", () => {
cy.visit("https://www.bstackdemo.com/");
cy.findByDisplayValue("Apple").should("exist");
});Conclusion
This article discussed how to leverage the cypress-testing-library to hide multiple chaining of the commands. This will keep the code clean as well as avoid users creating their own methods in the framework which might just increase the code duplication and redundant functions.
The cypress-testing-library APIs are self explanatory on what it does, hence it gives clarity from a readability perspective. And these APIs are similar to DOM Testing Library, developers will also have benefit of using the cypress-testing-library API similar to DOM testing library.
Whenever running Cypress tests, it is recommended to test on real devices so that the real user conditions can be taken into account for better accuracy of test results. Tools like BrowserStack Automate help QAs by providing access to 3000+ device browser combinations for a comprehensive automated testing.
Was this post useful?
We're sorry to hear that. Please share your feedback so we can do better
Thanks a lot for your feedback!
Featured Articles
What is Cypress Page Object Model?
What’s new in Cypress 10? How it will change your current testing requirements
App & Browser Testing Made Easy
Seamlessly test across 20,000+ real devices with BrowserStack
