Support assertions for each DOM query
benquarmby opened this issue · comments
Describe the feature you'd like:
TL;DR:
expect(element).toContainOneByRole("heading", {
name: "Attention"
});
Please consider adding jest assertions for each of the eight query types provided by @testing-library/dom
. Assertions based directly on DOM queries would make this advice much easier to follow.
Advice: If you want to assert that something exists, make that assertion explicit.
Problem Statement
In many tests, asserting on both the existence and absence of elements is key to proving correct behavior. While it's true that getBy*
and friends already throw excellent diagnostic information when something can't be found:
- Relying on the throwing side effect for the purpose of assertion does not make the intent of a test clear.
- The errors these queries throw don't help when asserting on the absence of an element.
- Wrapping queries in fake assertions to make the intent clear results in spurious test feedback.
Fabricated Example
An app needs to show and hide a warning within a dialog as validity changes. This is what the test might look like today.
const dialog = screen.getByRole("dialog");
const input = within(dialog).getByLabelText("Foo");
userEvent.type(input, "INVALID");
// Don't forget to use `getBy*` here, or we'll see a confusing null error.
expect(within(dialog).getByRole("heading", {name: "Attention"})).toBeInTheDocument();
userEvent.type(input, "VALID");
// Don't forget to use `queryBy*` here or it will fail before it can check for absence.
expect(within(dialog).queryByRole("heading", {name: "Attention"})).not.toBeInTheDocument();
Drawbacks
Having assertions that are tightly integrated with DOM queries would require a dependency on @testing-library/dom
which does not exist today. That said, the library is called @testing-library/jest-dom
, which implies the two are connected.
Suggested implementation:
Proposal
Using "by role" as an example:
- Add
toContainOneByRole
which passes when there is precisely one element. The negated versionnot.toContainOneByRole
passes when there are zero or more than one elements. This has some similarities withgetByRole
. - Add
toContainAnyByRole
which passes when there are one or more elements. The negated versionnot.toContainAnyByRole
passes when there are zero elements. This has some similarities withgetAllByRole
.
The assertion arguments would have exact symmetry with each query function. For example:
toContainOneByRole(role: ByRoleMatcher, options?: ByRoleOptions): void;
toContainAnyByRole(role: ByRoleMatcher, options?: ByRoleOptions): void;
Repeat for the other seven query types in @testing-library/dom
.
Sample Implementation
A hastily put together implementation can be found in this gist: https://gist.github.com/benquarmby/7510252ab701669c2eaf3c0156dd680c. There are holes, but it works for demonstration purposes.
Describe alternatives you've considered:
- Making a separate library, either official as
@testing-library/jest-dom-query
or unofficial. - Copy and pasting the custom matchers around.
Teachability, Documentation, Adoption, Migration Strategy:
Using the previous fabricated example, usage could look like this:
const dialog = screen.getByRole("dialog");
const input = within(dialog).getByLabelText("Foo");
userEvent.type(input, "INVALID");
expect(dialog).toContainOneByRole("heading", {name: "Attention"});
userEvent.type(input, "VALID");
expect(dialog).not.toContainAnyByRole("heading", {name: "Attention"});
I would be open to this. Sounds good.
Hopefully someone can take it to contribute this new feature before I or other maintainer do it, which may take a while.
Hopefully someone can take it to contribute this new feature before I or other maintainer do it, which may take a while.
I'm willing to make a contribution. My biggest concern is what I mentioned in the drawbacks section. These assertions would require a dependency on @testing-library/dom
. Would you be open to having that as a production or peer dependency?
Hmmm, good point.
@testing-library/core-maintainers thoughts?
peer would be the proper way to handle this
peer would be the proper way to handle this
Agreed. That's the way my local test implementation works.
We can assume most consumers of @testing-library/jest-dom
probably already have some version of @testing-library/dom
. That said, adding a new peer dependency is technically a breaking change; The new assertions will break without it.
I can get started on a PR if everyone is OK with:
- adding a peer dependency.
- accepting a breaking change.
I'm ok with that. But let's give it a day or two, to see what others have to say.
@benquarmby I say go for it.