Enhance getByText query

[tylerthehaas]

Describe the feature you'd like:

Currently the getByText takes an HTML element to scope the search to and then a text matcher. This will return an HTML element. The issue I've run into with this is that say I provide the following.

const emptyHeader = container.querySelector('.emptyHeader');

expect(getByText(emptyHeader, /createOneOnOne/).toBeInTheDocument();

I would get the following error:

 Unable to find an element with the text: createOneOnOneTemplate.oneOnOne. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.

    <h3
      class="emptyHeader"
    >
      createOneOnOneTemplate.oneOnOne
    </h3>

This is because I've scoped it to the element that I expect the text to appear in so it will search for elements within that h3 that contain the text matching my text matcher. However there is no other elements in this case just a text node. So I can fix this by just getting the parent of the h3 and everything works. There is an issue however if my text node is at the root of the document. Then I can't get a parent. I actually haven't come across that case where I have a text node at the root of the document but it is possible to happen. However I do think that it is a more intuitive api to scope it to the element you expect the text to be be contained in whether that has children that contain the text or not and it would return a boolean value.

Suggested implementation:

as mentioned above we can scope it to any html element and then look if the text is contained anywhere within the html sub tree that has now been attached to the body of the document. We would then just return a boolean value rather than an html element | null.

Teachability, Documentation, Adoption, Migration Strategy:

I'm not sure how .toBeInTheDocument() is implemented but assuming that it checks for truthiness then the migration should be fairly straight forward. If not then we can think of alternate implementations to enhance how this query works.

[kentcdodds]

We should definitely consider the scoped element in the query along with all its children. I'd call that a bug. Anyone want to fix that?

[tylerthehaas]

Sorry for the delayed response. I'd love to work on this. Any objection to my proposed implementation? Also do you think we need to consider all queries to have this same bug?

[kentcdodds]

Yeah, so I think the implementation will basically be: "Does this match the scoped element? Yes? Return the scoped element. No? Do whatever we're currently doing"

An elegant way to do this may be to change this:

return Array.from(container.querySelectorAll(selector))

To this:

return [container, ...Array.from(container.querySelectorAll(selector))]

Though that presents the problem: "What if container does not match the selector?" So that may make things more tricky. I'll let you figure that out 😉