doc,assert: document stackStartFunction in fail · nodejs/node@abf6355

@@ -192,29 +192,47 @@ If the values are not equal, an `AssertionError` is thrown with a `message`

192192

property set equal to the value of the `message` parameter. If the `message`

193193

parameter is undefined, a default error message is assigned.

194194195-

## assert.fail(actual, expected, message, operator)

195+

## assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])

196196

<!-- YAML

197197

added: v0.1.21

198198

-->

199199

* `actual` {any}

200200

* `expected` {any}

201201

* `message` {any}

202202

* `operator` {string}

203+

* `stackStartFunction` {function} (default: `assert.fail`)

203204204205

Throws an `AssertionError`. If `message` is falsy, the error message is set as

205206

the values of `actual` and `expected` separated by the provided `operator`.

206207

Otherwise, the error message is the value of `message`.

208+

If `stackStartFunction` is provided, all stack frames above that function will

209+

be removed from stacktrace (see [`Error.captureStackTrace`]).

207210208211

```js

209212

const assert = require('assert');

210213211214

assert.fail(1, 2, undefined, '>');

212215

// AssertionError: 1 > 2

213216217+

assert.fail(1, 2, 'fail');

218+

// AssertionError: fail

219+214220

assert.fail(1, 2, 'whoops', '>');

215221

// AssertionError: whoops

216222

```

217223224+

Example use of `stackStartFunction` for truncating the exception's stacktrace:

225+

```js

226+

function suppressFrame() {

227+

assert.fail('a', 'b', undefined, '!==', suppressFrame);

228+

}

229+

suppressFrame();

230+

// AssertionError: 'a' !== 'b'

231+

// at repl:1:1

232+

// at ContextifyScript.Script.runInThisContext (vm.js:44:33)

233+

// ...

234+

```

235+218236

## assert.ifError(value)

219237

<!-- YAML

220238

added: v0.1.97

@@ -492,5 +510,6 @@ assert.throws(myFunction, /missing foo/, 'did not throw with expected message');

492510

[`assert.ok()`]: #assert_assert_ok_value_message

493511

[`assert.throws()`]: #assert_assert_throws_block_error_message

494512

[`Error`]: errors.html#errors_class_error

513+

[`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt

495514

[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

496515

[`TypeError`]: errors.html#errors_class_typeerror