Conversation
Extend qunit.dom() to accept an object with an `elements` property so external objects that have their own DOM querying implementation like page objects can be plugged into qunit-dom's assertion API. The objects can also expose an `element` property for more performant first-matching-element DOM queries, as well as an `elementsDescription` property to provide a description of the query, e.g. a selector, for more readable assertion messages.
* update the documentation script to explicitly exclude the private query classes -- unfortunately adding `@private` annotations in the comments doesn't work because when the code is transpiled new `/** class */` comments are injected that cause documentation to emit entries for them regardless of what's in the .ts file * add info about the `ExternalQuery` interface to the documentation. As described in the comment in `documentation.yml` this required a bit of trickery
|
thanks for working on this first draft @bendemboski. we will need a bit of time to think about this though, so don't expect this to land in the very near future. you made a good point about the |
I'm just not sure how to adapt that if (this.target === null) {
return '<unknown>'; // !== this.targetDescription
} else {
return this.target; // === this.targetDescription
}To re-implement it using the query interface, we'd have to know the type of the if (this.query instanceof ElementQuery) {
return '<unknown>'; // !== this.targetDescription
} else {
return this.query.description; // === this.targetDescription
}or we'd have to add another property to the I suppose the way I'd probably do it is the latter -- add a |
|
I've opened an RFC to discuss this as a more general pattern that could be used in other testing libraries as well. |
Extend
qunit.dom()to accept an object with anelementsproperty so external objects that have their own DOM querying implementation like page objects can be plugged intoqunit-dom's assertion API.This is based on a Discord discussion with @Turbo87, and is aimed at supporting my new and still very much WIP page object library (see the tests for a rough idea of the usage patterns), and also at supporting any number of extensions to
qunit-dom's querying functionality like #864.Some notes:
Why
elementsDescription?I chose the name
elementsDescriptionrather than the more tersedescriptionto support page object implementations where the page object nodes are passed directly intoqunit-dom. In this case, any properties read byqunit-domneed to be reserved for "internal use" by the page object implementation, disallowing users from using those names for child nodes. This seems reasonable forelementsandelement, but much less so fordescription. For example, usingember-cli-page-object's API (imagining that it were extended to plug intoqunit-dom):I'm definitely open to other ideas for how to expose this information to
qunit-domin a way that isn't overly likely to cause page object footguns.<unknown>vs.<not found><unknown>was used for the assertion message whennullwas passed in as thetarget, but if a selector was passed in that didn't match anything, the selector string would be used. In the other assertion messages where the element was not found,<not found>was used. I couldn't figure out what value this distinction was providing (if any, maybe just an accident of how the code evolved?), so I couldn't figure out how to translate it to theDOMQueryabstraction, so I just eliminated it, meaning some of the assertion strings have changed (as you can see from the tests). If there's a reason to keep<unknown>I'm happy to discuss how to revive it.documentation
As mentioned in the second commit, updating the documentation was a bit of a PITA mainly, I think, because of some limitations of
documentation. I did try switching to generating the documentation off of the typescript so we don't have to hard-code theExternalQuerydocumentation indocumentation.yml, but then it generated a separate entry for each typescript function overload signature, which seemed less than helpful. Anyway, this is the best I could come up with but am happy to entertain other ideas.