|
| 1 | +# Suggest using explicit assertions rather than just `getBy*` queries (prefer-explicit-assert) |
| 2 | + |
| 3 | +Testing Library `getBy*` queries throw an error if the element is not |
| 4 | +found. Some users like this behavior to use the query itself as an |
| 5 | +assert for the element existence in their tests, but other users don't |
| 6 | +and prefer to explicitly assert the element existence, so this rule is |
| 7 | +for users from the latter. |
| 8 | + |
| 9 | +## Rule Details |
| 10 | + |
| 11 | +This rule aims to encourage users to explicitly assert existence of |
| 12 | +elements in their tests rather than just use `getBy*` queries and expect |
| 13 | +it doesn't throw an error so it's easier to understand what's the |
| 14 | +expected behavior within the test. |
| 15 | + |
| 16 | +> ⚠️ Please note that this rule is recommended to be used together with |
| 17 | +> [prefer-expect-query-by](docs/rules/prefer-expect-query-by.md), so the |
| 18 | +> combination of these two rules will force users to do 2 actual |
| 19 | +> changes: wrap `getBy*` with `expect` assertion and then use `queryBy*` |
| 20 | +> instead of `getBy*` for asserting. |
| 21 | +
|
| 22 | +Examples of **incorrect** code for this rule: |
| 23 | + |
| 24 | +```js |
| 25 | +// just calling `getBy*` query expecting not to throw an error as an |
| 26 | +// assert-like method, without actually either using the returned element |
| 27 | +// or explicitly asserting |
| 28 | +getByText('foo'); |
| 29 | + |
| 30 | +const utils = render(<Component />); |
| 31 | +utils.getByText('foo'); |
| 32 | +``` |
| 33 | + |
| 34 | +Examples of **correct** code for this rule: |
| 35 | + |
| 36 | +```js |
| 37 | +// wrapping the get query within a `expect` and use some matcher for |
| 38 | +// making the assertion more explicit |
| 39 | +expect(getByText('foo')).toBeDefined(); |
| 40 | + |
| 41 | +const utils = render(<Component />); |
| 42 | +expect(utils.getByText('foo')).toBeDefined(); |
| 43 | + |
| 44 | +// ⚠️ `getBy*` should be replaced by `queryBy*` when combined with `prefer-expect-query-by` rule |
| 45 | +expect(queryByText('foo')).toBeDefined(); |
| 46 | + |
| 47 | +// even more explicit if you use `@testing-library/jest-dom` matcher |
| 48 | +// for checking the element is present in the document |
| 49 | +expect(queryByText('foo')).toBeInTheDocument(); |
| 50 | + |
| 51 | +// Doing something with the element returned without asserting is absolutely fine |
| 52 | +await waitForElement(() => getByText('foo')); |
| 53 | +fireEvent.click(getByText('bar')); |
| 54 | +const quxElement = getByText('qux'); |
| 55 | + |
| 56 | +// call directly something different than Testing Library query |
| 57 | +getByNonTestingLibraryVariant('foo'); |
| 58 | +``` |
| 59 | + |
| 60 | +## Options |
| 61 | + |
| 62 | +This rule accepts a single options argument: |
| 63 | + |
| 64 | +- `customQueryNames`: this array option allows to extend default Testing |
| 65 | + Library queries with custom ones for including them into rule |
| 66 | + inspection. |
| 67 | + |
| 68 | + ```js |
| 69 | + "testing-library/prefer-expect-query-by": ["error", {"customQueryNames": ["getByIcon", "getBySomethingElse"]}], |
| 70 | + ``` |
| 71 | + |
| 72 | +## When Not To Use It |
| 73 | + |
| 74 | +If you prefer to use `getBy*` queries implicitly as an assert-like |
| 75 | +method itself, then this rule is not recommended. |
| 76 | + |
| 77 | +## Related Rules |
| 78 | + |
| 79 | +- [prefer-expect-query-by](docs/rules/prefer-expect-query-by.md) |
| 80 | + |
| 81 | +## Further Reading |
| 82 | + |
| 83 | +- [getBy query](https://testing-library.com/docs/dom-testing-library/api-queries#getby) |
0 commit comments