Request to add more practical example to the document query page

[m98]

I know the whole point of this testing library is to do testing "how a user would" and "how user see".

But imagine the time that we have multiple headlines on our page (ex, h2, h3, h4), h2 holds the product name, and h3 holds the product manufacturer. Just by getAllByRole('heading') we can't exactly address the specific tag we need to test (ex, product name), there is a need to exactly address which "heading" do we mean. I'm sure there are several good ways to React Testing Library to solve this problem easily, but the documentation is a problem. I saw many StackOverflow questions about the getByRole, and many user are even writing "role" even when it's not necessary. On the other hand, accessing by "getByRole" is not that clear for developers who used to work with Enzyme (and JQuery API)

When you look at the documentation, most of the examples are about images, input, label, and button. For edge cases like the example I provided (multiple headlines, how to address each exactly) does not have a good practical example there. Or what if there are several div, and user needs to access one (I mean without using data-testid, which is this library's main focus as long as possible)

The documentation page need some polishing and re-writing, and I would be glad to help

[eps1lon]

Thanks for the insight.

I'm just explaining what I could do and then we can see if there's some useful documentation we can extract:

For headings I would almost always recommend end-to-end testing on the full page. Knowing that a certain component renders a heading level 3 does not mean anything if the heading structure on your page is broken. testing-library/jest-dom#213 has a bit more context on the issue.

Ideally you would have an automated test that compares the heading structure against a snapshot. Since that is a primary way people navigate pages, knowing the changes to level and text increases your confidence by a lot. Especially since broken heading structures are extremely common on websites.

For edge cases like the example I provided (multiple headlines, how to address each exactly)

Could you explain these in more detail and what you think you should assert about these?

[m98]

@eps1lon Thanks for the explanation.

Heading was just an example, it can be any tag in any context. I don't have any problem with the React Testing Library way of writing tests, but I mean there are some parts of the documentation (especially this page) that can be improved by providing more practical examples or explaining the parameters of each method in more detail.

React official documentation can be a role model, because they used a simple writing style, and providing step-by-step codes that can help the reader to understand the subject much easier. It reminds me the Linus Torvalds's quote which says "talk is cheap, show me the code" :)

What is the problem?

Unfortunately, many documents don't see the document subject from the readers' perspective. Some might believe developers come to the page, and read the page from start to end. But that's wrong, most developers user (let's say, at least) 10 different tools for each project, they can't read all the documents of all the tools from start to end. They search on Google. The art of writing a good document is to write what the developer is looking for, as simple as possible, with the best code examples which cover real situations.

As we know many developers are familiar with the JQuery API or are migrating from Enzyme to React Testing Library, then a migration guide is needed. Or, the documentation have to be in a way that those developers feel comfortable with.

Please have a look at the document page about at all available queries on React Testing Library, and see as a developer's perspective who has a page with multiple "div" and "span" which each holds dynamic value, the developer on the documentation page, might search for "span", or "div" by using browser ctrl+f function. (again, imagine it's a product component, and each element has one of the product entities). The developer can't simply find the correct solution on how to access each of its desired elements by using role (because of lack of practical examples)

How it can be improved?

The document can have an imaginary component which holds a different type of tags (let's say it's a blog post component or a single product component), examples can be about this component which the code is visible in the top of the page, and then we can write a test (by the standard and recommended way) and users can learn faster because it just makes everything easier to have a component like their own (which has different tags, and it has a purpose)

[kentcdodds]

I think all the things you're saying are good. If you have the time to improve the documentation then your contribution would be greatly appreciated. I know the docs need improvement. Many contributors have poured many hours into what we have as it is but we all know they need more improvement. It's just a matter of time and the fact that we're not paid to maintain the documentation or projects themselves so it comes from our free time.

[m98]

Thanks @kentcdodds

I appreciate all the contributors' time on creating the project and its documentation. To be fair, all are good, but there is still something that can be fixed

I try to spend some time and contribute to the documentation.
I don't know how freely I can add/remove/improve things in the documentation, I think some rewrite is needed in some parts, but I'll try my best in the first place to simplify it

[m98]

@kentcdodds Just a question before contributing on documents

Is it fine to have a new page in documentation as "Migrate from Enzyme" to explain things for those who understand Enzyme and JQuery API? Or do you prefer those changes to be made on the query list page?

[kentcdodds]

A new page would be welcome 👍

[m98]

Okay, I'll take care of this.
Hopefully, a new page will be available in around 10 days from now.

[m98]

As discussed earlier, I'm working on a new page as "migrate from Enzyme (or jQuery API)"

I need some information for the new page, and the following list is based on the Enzyme documentation and I'm looking for best practice alternatives for Enzyme queries. I can think of some, but your help is needed for a better, easier, and more completed documentation page. I prefer to present React Testing Library's queries which do not add any additional complexity (preferably not using data-testid)

Please provide the alternative for each query by the following order (for some of them I provide the RTL example, but if there is any problem you can correct me):

1. how to render a component

Enzyme's shallow wrapping doesn’t descend down to sub-components, RTL's render is more like mount

• Enzyme: mount(<MyComponent />)
• RTL: render(<MyComponent />)

2. How to find a component in another component

• Enzyme: wrapper.find(Foo) (Foo is imported and it's another component)
• RTL: ???

3. Debugging

• Enzyme: console.log(wrap.debug())
• RTL: screen.debug() (console.log is not needed)

4. Get text output from the component

• Enzyme: expect(wrap.text()).toEqual('I am Groot')
• RTL: expect(screen).toHaveTextContent('I am Groot')

5. Test by the element content text

• Enzyme: expect(wrap.text()).toEqual('I am Groot')
• RTL: (1) expect(screen).toHaveTextContent('I am Groot')
• RTL: (2) expect(screen.getByText('I am Groot')) // it only pass the test if it can find the "I am Groot" in the given context

6. Find element containing the given element

Is there any better option to just pass screen instead of using "getByTestId"?

• Enzyme: expect( wrap.containsMatchingElement(<span>I am groot</span>) ).toBeTruthy()
• RTL: expect(screen.getByTestId('special-id')).toContainHTML('<span>I am groot</span>')

7. Test a required attribute

• Enzyme: expect(companySelect.find('input[type="submit"]').props()["disabled"]).toBe(true)
• RTL: expect(screen.getByText('Submit')).toBeDisabled()

8. Simulating events

• Enzyme: wrap.find('button').simulate('click')
• RTL: fireEvent.click(screen.getByText('Submit'))

---

What does the new "Migration" page contain?

Here are the potential sections:

1. Philosophy
2. Why React Testing Library instead of others (Enzyme, etc)
3. How to install
4. How to migrate your current tests to RTL? (The list above and some other will be presented)
5. Conclusion

---

If you have any idea, please let me know

---

Mention some of the contributors since I'll need their help and ideas
@kentcdodds @eps1lon @gnapse @smacpherson64 @alexkrolick

[kentcdodds]

Hi @m98, thanks for your work on this so far.

One thing to keep in mind that there's not really a one-to-one mapping of enzyme features to React Testing Library features. This is because many enzyme features result in bad tests. So it's often not as simple as changing a few function calls and more often it's a matter of rewriting the tests entirely (but it's totally worth doing this because you're trading tests that slow you down for tests that give you confidence). That might be worth mentioning.

There's no way to "find a component" with React Testing Library because "components" are an implementation detail. People should be looking for elements on the page like their users will (by text).

expect(screen).toHaveTextContent('I am Groot') is incorrect. You shouldn't (and can't really) pass screen to expect and make a useful assertion. It would be more correct to say: expect(screen.getByText('I am Groot')).toBeInTheDocument() (Note that using expect without an assertion is technically a useless function call).

I don't see much of a difference between your 4th and 5th points.

For point 6, that's one that you just wouldn't bother with. There's nothing useful about an assertion like that. The user doesn't care about the HTML output. That said, the user does care about the role an element has. So, if you change the example to look for a button then the RTL example could be: const submit = screen.getByRole('button', {name: /submit/i})

I suggest you read up on Which query should I use? as well as Common mistakes with React Testing Library. Among other things you'll learn that we should focus on *ByRole queries, so for point 7, it should be expect(screen.getByRole('button', {name: /submit/i})).toBeDisabled(). This gives you confidence that the element with the text "submit" has the right role for a user to actually click on it, and also that it's currently disabled.

Point 8 should be changed to *ByRole and should also be using userEvent.click (from @testing-library/user-event) rather than fireEvent.click. Also, it may be useful to note that this fires actual browser events, not simulated events.

In the docs, do you want to address act (and the fact that people shouldn't have to call it most of the time with RTL) as well as wrapper.update() (and the fact that RTL doesn't need anything like that).

Thanks for working on this!

[m98]

Thank you so much @kentcdodds

I'm still working on it.

Something that I personally did not get about getAllByRole and it would be perfect if you can clarify it, is:
Imagine there are several H1, H2, H3, ... tags on the page, each contain a dynamic text (let's say a number, or an article title, author name, or etc). In this situation, if we use getAllByRole('headling') we get an array of element we could find on the page, in this case, shall we use the array index to access each of the elements? (then it would like Enzyme, and we will have inefficient tests which slow us down)

I just think the getByRole is not explained well, and I hope to first really get and understand it, then I can work better around it, even on the other pages

[eps1lon]

if we use getAllByRole('headling') we get an array of element we could find on the page, in this case, shall we use the array index to access each of the elements? (then it would like Enzyme, and we will have inefficient tests which slow us down)

The difference is that the order of the headings on a page is actually important to the user. Enzyme would return the order of the elements in the component tree which isn't necessarily the same.

But for headings structures I would generally recommend an actual e2e test that creates a snapshot of the heading structure. The headings in an individual component don't matter that much if they don't fit into a full page.

Also to note: testing-library consists of a different approach to testing and an API that enables it (as a pit of success). You can implement the testing approach with enzyme. They have similar tools available. They're just not as extensive at some points and include methods that we consider problematic.

So a possible migration strategy could be to first not use problematic enzmye APIs (i.e. not query by component name and only query by tagNames and DOM attributes) and then switch to testing-library. This is essentially what we did in Material-UI so that the changes were reviewable. That way you also get an understanding why cetain methods exist in testing-library.

[m98]

@eps1lon Thank you for your good answer.

Testing by the order of the elements would have the same inefficiency that reduces the development speed, and each simple change in the page might affect the sort of the elements, and a rewriting test would be needed...

Conversations here help to write more efficient document page.

[eps1lon]

a rewriting test would be needed...

That isn't a very valueable goal though. If the behavior for your user changes then your test should reflect that. A test that doesn't break if the behavior for a user changes is not all that valueable. If this is your goal then you wouldn't want to assert headings in the first place.

I mentioned snapshots specifically since they're ideal for headings where they're easily updated and provide a diff that includes no noise (which is oftentimes what bad snapshots have).

[m98]

@eps1lon Thanks a lot. Again very helpful comment.

That isn't a very valueable goal though

What would be the most valuable goal?

I'm listing some reasons why to use React Testing Library instead of the Enzyme. Something about Enzyme is that some developers also mentioned in communities is that when you write tests in Enzyme, it slows you down since every small change in the component, would need re-writing for your tests.

Would you please let me know what are the reasons users should use React Testing Library instead of Enzyme?