Testing library query selectors


A first look at query selectors in testing library

12 Apr, 2022 ยท 3 min read

Today weโ€™ll look into testing library. This is a set of packages to help you test UI components from a user perspective.

We already have it available in our React tests. (Follow this article to get started)

We have to keep in mind that this library is mainly a selector library, meaning it can be used to query certain elements. Itโ€™s not bound to a specific framework or testing library.

For instance to query something by text:

const defaultText = screen.getByText(/The counter is now on/g);

However, we still need Jest to make sure what we retrieved with testing library is true.


Query selectors in testing library

A big part of testing library is its ability to use query selectors. You can even see the one above here in the example.

They are a way to find elements in the DOM quickly, and we can use the following types:

  • get
  • find
  • query

The main difference is how they query and whether to throw an error or await for something.

And then, each of these has the option to define whether we want one or multiple elements. You can define this by either using By or AllBy behind your selector.

Letโ€™s say we want to use single element selectors:

  • getBy
    • Nothing found? It will throw an error
    • 1 element found, returns the element
    • More found? Throw an error
  • findBy
    • Nothing found? It will return null
    • 1 element found, returns the element
    • More found? Throw an error
  • queryBy
    • Nothing found? It will throw an error
    • 1 element found, returns the element
    • More found? Throw an error

So basically, getBy and queryBy do the same thing. There is just one major difference. findBy will return a promise so that we can await this.

For multiple elements, itโ€™s the same. However, instead of returning the element, it returns an array of elements.

Types of queries

Now that we know how to query, we can dive into the types of queries we can use.


We can use the ByRole selector to find elements with a specific role in the DOM, for instance, if we want to query a button.

const button = screen.getByRole('button');


The ByLabelText query can find labels with specific text.

For instance if we have the following HTML setup:


We can use the following query to select this:

const label = screen.getByLabelText('Name');


Much like the above, we can use this to query elements with a specific placeholder value:

const placeholder = screen.getByPlaceholderText('Enter your email');


This is a commonly known text selector we have used in previous articles. It can be used to query for text elements in the dom, and itโ€™s super powerful as it can leverage regular expressions.

const defaultText = screen.getByText(/The counter is now on/g);
const defaultText = screen.getByText('The counter is now on 0');
// etc


As the name suggests, this one can be used to query elements by their current displayed value.

For instance having the following HTML:

<input type="text" id="lastName" value="Bongers" />

We can query this element like this:

const value = screen.getByDisplayValue('Bongers');


ByAltText is a quick test case for finding elements with specific alt tags.

const alt = screen.getByAltText('my amazing photo');


A not so commonly known selector to target elements with a title attribute.

<i title="Delete"><Icon /></i>
const title = screen.getByTitle('Delete');

And then there is ByTestId, but weโ€™ll go into more details on that one in the following article.


I hope you learned something new about the types of query selectors and how to use each one of them.

Please keep a lookout for the upcoming articles as we dive even more into testing.

Thank you for reading, and letโ€™s connect!

Thank you for reading my blog. Feel free to subscribe to my email newsletter and connect on Facebook or Twitter

Spread the knowledge with fellow developers on Twitter
Tweet this tip
Powered by Webmentions - Learn more

Read next ๐Ÿ“–

Testing library asFragment tests

18 Apr, 2022 ยท 2 min read

Testing library asFragment tests

Changing the default testing container

17 Apr, 2022 ยท 3 min read

Changing the default testing container

Join 2099 devs and subscribe to my newsletter