App & Browser Testing Made Easy

Give your users a seamless experience by testing on 3000+ real devices and browsers. Don't compromise with emulators and simulators

Get Started free
Home Guide What is Cypress Testing Library and its Usage

What is Cypress Testing Library and its Usage

By Gurudatt S A, Community Contributor -

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.

APIDefinition
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.

Run Cypress Tests on Real Devices

Tags
Automated UI Testing Automation Frameworks Cypress Website Testing

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