Add `withDescription` helper method about qunit-dom HOT 5 CLOSED

Sounds like an interesting idea. Unfortunately I don't see how this could be implemented. By the time the withDescription() method is called, the assertion has already run.

The position of the description is consistent btw. It's always the last argument.

from qunit-dom.

@Turbo87 I see - but "always the last argument" can be limiting for long-term growth of the API for an argument that is optional for every assertion. I know a few weeks ago when I looked at this library (when evaluating it for our use case) the exists method didn't contain the options argument, which it now does (to support count).

This could've been solved by making a backwards incompatible change, but that still would've required me (the app developer) to go through and replace/codemod all exists('my description') with exists({}, 'my description').

Since it sounds like the assertion is run in the - I guess I'll call it - assertion method? What if we change the order on this? I can think of three possible options:

1. assert.dom('.my-toggle', 'The toggle button was clicked').exists();
2. assert.dom('.my-toggle', { description: 'The toggle button was clicked' }).exists();
3. assert.dom('.my-toggle').describedBy('The toggle button was clicked').exists()

As someone on the outside looking in, I believe I would prefer 2 over 1, but 3 would also be a very comfortable solution.

Thoughts?

from qunit-dom.

@seanjohnson08 as you can see in https://github.com/simplabs/qunit-dom/blob/a2c26d8bf3fa6cb33f968e1fe5577d79476c5d65/lib/assertions/exists.ts#L6-L9 the exists() assertion also supports being called with just a description, so there was no backwards incompatible change.

RE 1) and 2) the issue is that the description describes the assertion, not the element that the assertion runs on so the description would be on the wrong thing

RE 3) can be confusing if people expect it to work in the other order too and has similar problems as above too

from qunit-dom.

Hmm, I see. I guess now that I know more about the conventions established:

1. message is always the last argument, not always some N argument
2. for lists of optional arguments, type checking is used to provide "overloading" to ensure all combinations are supported

I would be happy with closing this issue and maybe just adding the above ^ to the API.md as a way to educate / communicate this convention.

from qunit-dom.

@seanjohnson08 sounds like a good idea, yeah. the API.md is auto-generated from the code comments though, so I'm not sure exactly where to add that comment, but feel free to experiment with it. I'll go ahead and close this issue as you're original concern seems to be addressed.

from qunit-dom.