ToBeEmpty assertion in jest-dom is also used in jest-extended

[DanielaValero]

Describe the feature you'd like:

Jest-Extended has an assertion named the same as jest-dom's one:

-> https://github.com/jest-community/jest-extended#tobeempty
-> https://github.com/testing-library/jest-dom#tobeempty

When both libs are used in the same project, the version of jest-extended overwrites the one from jest-dom.

Describe alternatives you've considered:

Maybe an option is to add an alias for toBeEmpty named toBeEmptyNode ?

Teachability, Documentation, Adoption, Migration Strategy:

I am not sure at this moment how the things work, could it be an option to have 2 names for the same assertion?

If yes, then the documentation could say:
"if you are using jest-extended, then use toBeEmptyNode" or something like this

edit
I have raised a feature request in Jest Itself asking for a feat that warns the user about the name collision and points out to a link where is documented a way to rename one of the colliding names in the project where the situation happens.

jestjs/jest#9678

It could be that the warning and the documentation of how to solve it in projects, might be enough to address this and similar situations like this one.

[gnapse]

I noticed this a while ago and even brought it up as an issue with jest: jestjs/jest#6243

I could see us providing an alias as you suggest.

[darekkay]

I've also encountered this issue today after introducing jest-dom into a large project.

When both libs are used in the same project, the version of jest-extended overwrites the one from jest-dom.

This depends on the import order. In my case, it's jest-dom that overrides jest-extended. So the proposed solution to add an alias still requires the correct import order.

Another way to solve it is to actually support other "empty" checks, similar to what lodash considers "empty". As jest-dom concentrates on the DOM aspect, the proposed alias solution seems to be a better one, though.

As a workaround, one can write a custom, third toBeEmpty extension that uses one of the library implementation based on the object type.

[gnapse]

I honestly don't know how to solve this properly. IMO it lies on the jest side of things. Can you all at least comment in the linked issue in jest (jestjs/jest#6243) so that this gets some visibility: I doubt it could have a quick fix, but this is something they should address. and there are mentions there of proposed solutions and maybe even a workaround?

[gnapse]

Though I'd be open to add an alias toBeEmptyDOMElement or something along those lines.

[KevinHerklotz]

Adding an alias like toBeEmptyDOMElement sounds good to me.
Maybe even renaming toBeEmpty to toBeEmptyDOMElement would be a better solution, because users will still face issues until they found out that they have to use toBeEmptyDOMElement. Yes this would be a breaking change for jest-dom, but I prefer to not have the same function names as Jest.
We need to remember that (according to the description of this library) js-dom "extends jest". It does not say it overwrites jest. And I also think we should not overwrite it. Also we can not expect from Jest to take care of all it's extending libraries that are out there.
So renaming the assertion function would be the best solution in my opinion.

[gnapse]

but I prefer to not have the same function names as Jest.

To be clear, we do not have the same function name that jest has. The clash is with another lib that also extends jest's custom matchers as we do, with their own, that are not related to checks to the DOM.

As for the breaking change approach, the impact of this issue so far has been proven fairly low. Few people have reported it. So I'd rather start with offering the alias, maybe even encouraging it and possibly even adding a deprecation warning in the console about it, and then in a subsequent breaking change release we fully remove it. That way we give folks the opportunity to learn about the upcoming change.

@testing-library/core-maintainers what do you think?

[kentcdodds]

I agree with you @gnapse!

[DanielaValero]

If you guys wouldn't mind, I'd volunteer to add the alias and the deprecation warning.

[gnapse]

Go for it @DanielaValero

[gnapse]

Closing this as it is solved by the new preferred alternative matcher toBeEmptyDOMElement (#254).