Jest-dom: toBeInTheDOM name is misleading about what it really does

[gnapse]

As reported by @sompylasar in kentcdodds/dom-testing-library#9 .toBeInTheDOM is not really checking for what it name implies (because it does not have the concept of what "the DOM" is to being with). Right now is just a glorified .toBeInstanceOfClass(HTMLElement).

Refer to the original discussion for all suggested solutions. I'll mention here a few from there plus a new one:

// I kinda favor something like this (exact name is open for discussion)
expect(container).toContainElement(element)

// This makes me wonder if it only checks for direct parent-child relationship
// We could add it too, but not as a solution to this issue
expect(element).toBeAChildOf(parent)

// Keep .toBeInTheDOM allowing it to receive an optional element
// This still does not solve the problem when the container is not given, but I wouldn't rule it out
expect(element).toBeInTheDOM()
expect(element).toBeInTheDOM(container)

[kentcdodds]

I'm in favor of all three of these matchers, especially these two:

expect(container).toContainElement(element)
expect(element).toBeInTheDOM(container)

👍

[gnapse]

But .toBeInTheDOM receiving the container optionally, or always? I assume the former, so it does not become a breaking change, right?

[kentcdodds]

Yes, it would be optional 👍

[gnapse]

Ok, I should have time to work on some of these later this week, but if someone else can give it a crack, go for it.

(Maybe @sompylasar, since he originally reported it and was needing it?)

[gnapse]

BTW, I'd rule this out for the time being:

expect(element).toBeAChildOf(parent)

As its name suggest, it'd be checking only for a direct parent-child relationship between two nodes. This is not as useful and it's a bit more brittle than checking a more general ancestry relationship. After all, users on the screen do not really know about direct relationships. They generally care about seeing some elements inside others, and that's what .toContainElement expressed already.

[antsmartian]

@gnapse I can give it a shot on this, if I get some time tomorrow.

[gnapse]

@antoaravinth are you still up to get this?

[antsmartian]

@gnapse Sorry was busy.. Yeah should be able to close this when I get time :)

[gnapse]

Sure, no problem and no hurries, just wanted to check if your offer was still on.

[gnapse]

Closing as this was solved in #25