prefer-screen-queries rule

[00:00 - 00:19] In this lesson we are going to talk about the preferred screen queries rule. As we can see in the supported rules table, this rule is enabled and supported by all the tested library frameworks available in ESLint planning tested library.

[00:20 - 00:41] So we don't have to manually enable this rule since we are using the tested library React preset. However, if we want to manually enable this rule, it's as simple as going to our ESLint config file, then we went to the rules section of the override in our case.

[00:42 - 00:56] Then we have here testing library slash, remember all rules from the plugin are pre-fixed with this tested library's last string. In the name of the rule and then the error level we want to set.

[00:57 - 01:07] But as we mentioned, this is not necessary because in the tested library React preset is already enabled for us. Tested library provides many queries to get elements from your UI.

[01:08 - 01:16] These queries can be obtained from two places. The destructure you choose return from the render or the screen object.

[01:17 - 01:23] These obtained from either way work similarly. However, it's recommended to use them from the screen object.

[01:24 - 01:39] Why? Because queries from the screen object are automatically profound to the document body, which makes it easier to query elements that might be rendered at different levels of the container of the testing component, like more or less tooltips or other elements rendered with fragments.

[01:40 - 01:49] And also, because querying the entire document body is very common. When the queries profound to the body provides an additional benefit for don't tested library.

[01:50 - 02:06] Since there is no render utility in don't tested library, all the queries are directly exported from the testing library don't package itself. When using the queries directly imported from here, you need to manually provide a container to indicate to don't tested library where to search for the desired elements.

[02:07 - 02:26] However, if you use queries from the screen object, you can skip the container parameters since querying the document is the most common scenario and those queries are profound to it. Another advantage of using the screen queries is not having to update the rendered cold structure every time we want to add or remove queries to be used.

[02:27 - 02:35] This makes it easier to write and maintain your test. You'll need to type screen. and let your auto-completion from your editor to do is magic to pick the desired query.

[02:36 - 02:45] Let's see with an example how to fix the errors reported by this rule. If we go to the example.test.jsx, we will find a test implemented for us.

[02:46 - 02:58] This test is just rendering the app and checking that the element containing this specific text is in the document. We can see getByTextQuery is underlined with the following error.

[02:59 - 03:18] In order to fix this, instead of getting the query from the rendered method, we need to delete it, import the screen object if it's not imported yet, and then use the query from the screen object. That's it, error solved.

[03:19 - 03:28] At the beginning of this lesson, we stated that the preferred screen queries rule will report all queries used that are not coming from the screen. But this is not entirely true.

[03:29 - 03:36] There are three exceptions to this. Item number one, using queries changed from the withinutil.

[03:37 - 03:48] The withinutil takes a DOM element and binds it to the raw query functions, allowing them to be used without specifying a container. This is useful when querying elements within a certain part of the DOM.

[03:49 - 03:57] The queries returned from within won't be reported since they have a different behavior from the screen one. They are bound to a different container.

[03:58 - 04:10] We can see an example in this case one. If we are rendering a component, then we obtain a dialogue element with a screen query and wrap it with within.

[04:11 - 04:20] Now we can obtain another get by text query from the within. This get by text will be bound to this dialogue.

[04:21 - 04:34] Then we find some element with some text, and this case is not reported by the rule exception number two, custom queries. The delivery exposes many of the helper functions that are used to implement the different queries.

[04:35 - 04:43] So you can use them to build custom ones. These custom queries can be added to the render return duties, but they won't be bound to the screen queries.

[04:44 - 04:53] So this rule won't report custom queries since it's not possible to use them from the screen usage. We can see an example in this test named case two.

[04:54 - 05:00] Here we are rendering a component, then using a custom query. Pay attention to the buy icon.

[05:01 - 05:08] This is not a built-in query. We are assuming there is an existing custom query in our model here.

[05:09 - 05:19] This case won't be reported by the rule exception number three, using queries when setting the container or the base element. This is an uncommon but valid scenario.

[05:20 - 05:27] By default, the distill library render method will create a div and append it to the document body. This is where your component will be rendered.

[05:28 - 05:45] As we mentioned before, the queries obtained from a screen are automatically bound to the document body, so everything works as expected. However, if we provide our own HTML element container via this option where rendered your component, it won't be appended to the document body automatically.

[05:46 - 06:02] Something similar happens if you provide a custom HTML element through base element option, which is used as the base element for the queries. The queries from the screen util can't be used in either of these cases, since they won't be available to find the corresponding elements within the body.

[06:03 - 06:17] In these two tests, you have some examples for x-section number three. In the first one, we are creating a table, then rendering our component, and passing as a container the table we just created before.

[06:18 - 06:35] In this case, it's valid to use the getby text query obtained from the render, since this one is tied to the table rather than the document body from the screen query. In this other scenario, which is quite similar, we rendered the component, passing as a base element, some table already existing.

[06:36 - 07:04] Then the getby text query obtained from the render will be tied to the table that we pass it in the base element, not like the screen queries that are tied to the document body, so this case is not reported either. When it should be enabled, since the screen object is available in all the testing library frameworks provided by this plugin, and its usage is preferred over using queries' destructor from the render_return value, this rule is always recommended.

[07:05 - 07:13] This is why the rule is enabled in all the shareable conflicts provided by the plugin. It's your time for practicing the errors reported by this rule.

[07:14 - 07:24] In the practice.test.jsx file, for the demo app for this lesson, you'll find some tests with ESLing errors reported by this rule. Try to figure out how to fix them.