Testing Library - Queries
Tags: testing, testinglibrary, javascript
Published: 2022-11-02 14:54:39

The [Testing Library family](https://testing-library.com/) (including **React Testing Library**) is a great tool to help you write comprehensive, maintainable UI tests. 

The two primary functions it offers are _queries_, and _user actions_. Queries are the methods that Testing Library gives you to find elements on the page [[6](https://testing-library.com/docs/queries/about)].

This article explains the three types of queries ("getBy", "findBy", "queryBy") and how to use each one in different scenarios with code samples. [Note A]

![Flowchart describing when to use queryBy vs. getBy vs. findBy. Do you expect the element to be there? If no - use queryBy. If yes - should the element be there right away? If yes - use getBy; if no, use findBy.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o82trjoxtqncpy86dqgz.png)

## queryBy

**queryBy** should only be used if you want to assert that an element is not present [[1](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#using-query-variants-for-anything-except-checking-for-non-existence)].

Example use cases:

### Asserting an element should not be present
```js
expect(
  screen.queryByText("Error: Page Not Found")
).not.toBeInTheDocument();
```

### Asserting an element only appears under certain conditions
Example: a form's Submit button does not appear until all input fields are filled.
```js
const submitButton = screen.queryByText('submit');
expect(submitButton).not.toBeInTheDocument();

fireEvent.change(name, { target: { value: "Jane Smith" } });
expect(submitButton).toBeInTheDocument();
```

### Asserting an element is in the correct initial state
Example: a button that is initially "On", not "Off".
```js
// notice getBy can be used here as we expect this to appear
expect(
  screen.getByRole("button", {
    name: /On/i,
  })
).toBeInTheDocument();

// while queryBy is used here as we expect this *not* to appear
expect(
  screen.queryByRole("button", {
    name: /Off/i,
  })
).not.toBeInTheDocument();
```

### Asserting a list of elements is empty
```js
const projectCards = screen.queryAllByTestId("project-card");
expect(projectCards).toHaveLength(0);
```

### Asserting an element disappears or is removed
This example is taken from the Testing Library documentation on disappearance [[2](https://testing-library.com/docs/guide-disappearance/#waiting-for-disappearance)]. 

The **waitFor** async helper function retries until the wrapped function stops throwing an error. This can be used to assert that an element disappears from the page.
```js
test('movie title goes away', async () => {
  // element is initially present...
  // note use of queryBy instead of getBy to return null
  // instead of throwing in the query itself
  await waitFor(() => {
    expect(queryByText('i, robot')).not.toBeInTheDocument()
  })
})
```

There is also a **waitForElementToBeRemoved** helper, but in my experience I find **await waitFor** + **queryBy** to be more reliable, especially if expecting an element to disappear after a **fireEvent** or **userEvent** action. [Note B]

## getBy

**getBy** is used to get an element on the page, and will throw an error if no matching element is immediately found.

Two common use cases are:
* Asserting an element is present on the page, or asserting particular properties about that element.
* Selecting an element on the page to simulate user interaction with it, such as clicking it, entering text, or selecting an input.

While **queryBy** can also be used for those purposes, the main reason to prefer **getBy** over **queryBy** is that **getBy** will generally give you more helpful error messages when the element is not found.

Consider the following examples:

### Example 1 - asserting an element is present
```js
// getBy
expect(screen.getByText("Username")).toBeInTheDocument();
```
If this assertion fails, the error message is `Unable to find an element with the text: Username.` The error message clearly describes the desired element. It will also automatically print out the DOM so you can inspect the page yourself.

```js
// queryBy
expect(screen.queryByText("Username")).toBeInTheDocument();
```
If this assertion fails, the error message may look something like "null is not in the document", or, even more confusingly, "received value must be an HTMLElement or an SVGElement. Received has value: null". There's not much information about what went wrong in these error messages, since the assertion can only see `null` as the actual value.

### Example 2 - interacting with an element
```js
// getBy
const next = screen.getByRole("button", { name: /Next/i });
fireEvent.click(next);
```
If the button is not on the page, **getBy** will throw an error with message "Unable to find an accessible element with the role "button" and name `/Next/i`", which clearly describes the expected element. As mentioned in Example 1, it will also automatically print out the DOM to help in debugging.

```js
// queryBy
const next = screen.queryByRole("button", { name: /Next/i });
fireEvent.click(next);
```
If the button is not on the page, **queryBy** will not throw - instead, it returns `null`. The test will instead fail on the next line, when the **fireEvent** call throws with the error: `Error: Unable to fire a "click" event - please provide a DOM element.` This error message is less obvious since **queryBy** quietly returned `null`, and does not provide any information about the missing element - this requires more time and effort to debug.

## findBy
**findBy** is used to get an element that may not appear on the page immediately. For example, expecting a modal to appear after a button click, or expecting new content to appear after an asynchronous API call returns.

findBy will return a Promise, so you must use `await` or `.then()` [[3](https://testing-library.com/docs/dom-testing-library/api-async/#findby-queries)]. It will throw an error if the element does not appear after a specified timeout. [Note C]

Use cases for **findBy** are the same as **getBy**, but in situations where you may need to wait for the desired element to be on the page.

---

### Notes
<u>A.</u> The code examples shown here use Jest and jest-dom, which provide custom matchers like `toBeInTheDocument()` [[4](https://testing-library.com/docs/ecosystem-jest-dom/)].

<u>B.</u> Because **fireEvent** and **userEvent** are automatically wrapped in **act**, all React state updates are completed before the next line is executed. This means if an element is rendered (or not) based on simple state changes, attempting to use **waitForElementToBeRemoved** results in "Error: The element(s) given to waitForElementToBeRemoved are already removed. waitForElementToBeRemoved requires that the element(s) exist(s) before waiting for removal." since the element was already removed during the state update. 

According to [[5](https://github.com/testing-library/react-testing-library/issues/1033#issuecomment-1107477476 )], "waitForElementToBeRemoved is meant to await for async operations and in the example attached, you don't have anything async but just a simple react state change. In that scenario, there's no need to wait for anything."

<u>C.</u> Behind the scenes, **findBy** is a combination of **getBy** and **waitFor**, and accepts **waitFor** options as the second parameter, allowing you to customize values like the timeout.

### Resources

1. https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#using-query-variants-for-anything-except-checking-for-non-existence
2. https://testing-library.com/docs/guide-disappearance/#waiting-for-disappearance
3. https://testing-library.com/docs/dom-testing-library/api-async/#findby-queries
4. https://testing-library.com/docs/ecosystem-jest-dom/
5. https://github.com/testing-library/react-testing-library/issues/1033#issuecomment-1107477476
6. https://testing-library.com/docs/queries/about 
7. https://testing-library.com/docs/dom-testing-library/cheatsheet/

Topics: Testing Library, React Testing Library, getBy vs findBy vs queryBy, JavaScript, Jest