assert: improve assert.fail() API · nodejs/node@4917d8c

3 files changed

lines changed

Original file line number	Diff line number	Diff line change
@@ -194,14 +194,15 @@ If the values are not equal, an `AssertionError` is thrown with a `message`
`194`	`194`	property set equal to the value of the `message` parameter. If the `message`
`195`	`195`	`parameter is undefined, a default error message is assigned.`
`196`	`196`
	`197`	`+## assert.fail(message)`
`197`	`198`	`## assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])`
`198`	`199`	`<!-- YAML`
`199`	`200`	`added: v0.1.21`
`200`	`201`	`-->`
`201`	`202`	* `actual` {any}
`202`	`203`	* `expected` {any}
`203`	`204`	* `message` {any}
`204`		-* `operator` {string}
	`205`	+* `operator` {string} (default: '!=')
`205`	`206`	* `stackStartFunction` {function} (default: `assert.fail`)
`206`	`207`
`207`	`208`	Throws an `AssertionError`. If `message` is falsy, the error message is set as
`@@ -221,6 +222,12 @@ assert.fail(1, 2, 'fail');`
`221`	`222`
`222`	`223`	`assert.fail(1, 2, 'whoops', '>');`
`223`	`224`	`// AssertionError: whoops`
	`225`	`+`
	`226`	`+assert.fail('boom');`
	`227`	`+// AssertionError: boom`
	`228`	`+`
	`229`	`+assert.fail('a', 'b');`
	`230`	`+// AssertionError: 'a' != 'b'`
`224`	`231`	```
`225`	`232`
`226`	`233`	Example use of `stackStartFunction` for truncating the exception's stacktrace:

Original file line number	Diff line number	Diff line change
`@@ -77,6 +77,10 @@ function getMessage(self) {`
`77`	`77`	`// display purposes.`
`78`	`78`
`79`	`79`	`function fail(actual, expected, message, operator, stackStartFunction) {`
	`80`	`+if (arguments.length === 1)`
	`81`	`+message = actual;`
	`82`	`+if (arguments.length === 2)`
	`83`	`+operator = '!=';`
`80`	`84`	`throw new assert.AssertionError({`
`81`	`85`	`message: message,`
`82`	`86`	`actual: actual,`

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,36 @@`
`3`	`3`	`require('../common');`
`4`	`4`	`const assert = require('assert');`
`5`	`5`
	`6`	`+// no args`
	`7`	`+assert.throws(`
	`8`	`+() => { assert.fail(); },`
	`9`	`+/^AssertionError: undefined undefined undefined$/`
	`10`	`+);`
	`11`	`+`
	`12`	`+// one arg = message`
	`13`	`+assert.throws(`
	`14`	`+() => { assert.fail('custom message'); },`
	`15`	`+/^AssertionError: custom message$/`
	`16`	`+);`
	`17`	`+`
	`18`	`+// two args only, operator defaults to '!='`
	`19`	`+assert.throws(`
	`20`	`+() => { assert.fail('first', 'second'); },`
	`21`	`+/^AssertionError: 'first' != 'second'$/`
	`22`	`+);`
	`23`	`+`
	`24`	`+// three args`
	`25`	`+assert.throws(`
	`26`	`+() => { assert.fail('ignored', 'ignored', 'another custom message'); },`
	`27`	`+/^AssertionError: another custom message$/`
	`28`	`+);`
	`29`	`+`
	`30`	`+// no third arg (but a fourth arg)`
	`31`	`+assert.throws(`
	`32`	`+() => { assert.fail('first', 'second', undefined, 'operator'); },`
	`33`	`+/^AssertionError: 'first' operator 'second'$/`
	`34`	`+);`
	`35`	`+`
`6`	`36`	`// The stackFrameFunction should exclude the foo frame`
`7`	`37`	`assert.throws(`
`8`	`38`	`function foo() { assert.fail('first', 'second', 'message', '!==', foo); },`