Adding descriptions to assertions?

[tgoorden]

When doing something like:
expect(something).to.exist

the output of a failure tends to be:
AssertionError: expected undefined to exist

This is not very helpful if there is trouble with the stack-trace, something you can run into e.g. when using Chai+Mocha+Velocity+Meteor.

Ideally, there'd be something like an as(label) to add to the expectation:
expect(something).as('Foo').to.exist

which could then generate a more helpful output:
AssertionError: expected Foo to exist

[tgoorden]

(Note: apparently, you can do this with an assert, so my guess is it wouldn't be hard to include in expect as well.)

[keithamus]

Hey @tgoorden thanks for the issue!

You can do this with many expect methods, but not for properties. For example:

expect(something).to.not.equal(undefined, 'Foo');

My advice, if you want those messages, is to not use property assertions (like .to.exist).

The message is a simple flag on an assertion - so we could add a method such as your .as() idea, which would set the message, but I'm not sure there is a strong use-case given it already exists on method assertions.

[keithamus]

@tgoorden what are your thoughts about my above comment? Did this solve your issue satisfactorily?

[tgoorden]

Hmm. I just saw your comment now. We're using a mixture of asserts and expectations now. I remember this kind of "name chain element" from certain Java libraries. I think it might improve readability a little bit, but it's not crucial indeed. The as(...) reads more clearly as a label, whereas a second argument (which might or might not be available) is a bit more tricky. It would only be worth it if it was a universal option of course...

[keithamus]

I guess my main concern with as is that it can be such an ambiguous word. There could be many uses for an as function, and tying it up for the message flag could mean other useful functionality gets pushed to more esoteric names.

I'd be much more inclined to accept a patch if it was a slightly less obvious method name - perhaps something like withMessage() or asLabel(). Thoughts?

[abenhamdine]

I'm surprised, because in nodejs, i'm used to do :

 expect(something, 'Foo').to.be.a('string');

Why couldn't it be useful for your case ?

[keithamus]

@abenhamdine has a totally good point, and taught me something about Chai!

should is the only interface where you sometimes can't change the message (if you're using a property assertion like .to.exist), but if you're using expect, then you can use the second argument - as @abenhamdine suggests. Also every assertion that takes arguments (i.e. not property assertions like .to.exist) take the message as the last argument (as mentioned in my first reply)

As such, I think I'm going to close this one. If you feel this doesn't fix your problem though @tgoorden, please reply and I can re-open, or raise a new issue.

[wspringer]

I know this old, but can't help adding a comment here that Specs2 (Scala) is using aka(…), which I found useful, and is less likely to conflict with other things than as(…).

This is what it would look like in Chai:

expect(something).aka('the thing').to.be.a('string');

[keithamus]

aka is a pretty nice name. Let's see what others think.

[abenhamdine]

aka is pretty cool, imho ;)

[xbugster]

PHPUnit utilizing $this->assertEquals(value, expectation,message_on_assertion_fail)
From docs: ```assertEquals(mixed $expected, mixed $actual[, string $message = ''])``
https://phpunit.de/manual/6.5/en/appendixes.assertions.html