visionmedia/should.js — pull request #34 by theycallmeswift (2012-01-09 17:35:13+00:00)
Title: Added optional failure description to several matchers

In a lot of my tests I was getting cryptic errors like "expected 1 to equal 0" without any indication of where the failure was really coming from. I added an optional failure description to several should matchers so the process of hunting down and fixing bugs would be a lot faster. Also, anyone reading through my tests can quickly figure out exactly what I was trying to test.

I added it to almost all of the methods that were functional properties except `keys` because I haven't figured out a clean way to do it yet. Also, would like to add optional failure message to the getters but I haven't quite figured that one out yet either.

Check out this example bellow and let me know if you have any questions.

Example:

(1).should.eql(0, 'some useful description')

AssertionError: expected 1 to equal 0 | some useful description
at Object.eql (/Users/swift/code/should.js/node_modules/should/lib/should.js:280:10)
...

The methods that support this optional description are: `eql`, `equal`, `within`, `a`, `instanceof`, `above`, `below`, `match`, `length`, `property`, `ownProperty`, `include`, `includeEql`, and `throw`.