From dd25984838f10f566edd9dfe76b4db358a52ef74 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 3 Apr 2016 12:11:10 -0700 Subject: [PATCH] doc: note assert.throws() pitfall PR-URL: https://github.com/nodejs/node/pull/6029 Reviewed-By: Colin Ihrig Reviewed-By: James M Snell --- doc/api/assert.markdown | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index 6bbbf6bd629e22..35dbc3d2192209 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -361,8 +361,13 @@ If the values are not strictly equal, an `AssertionError` is thrown with a ## assert.throws(block[, error][, message]) -Expects the function `block` to throw an error. If specified, `error` can be a -constructor, [`RegExp`][], or validation function. +Expects the function `block` to throw an error. + +If specified, `error` can be a constructor, [`RegExp`][], or validation +function. + +If specified, `message` will be the message provided by the `AssertionError` if +the block fails to throw. Validate instanceof using constructor: @@ -402,6 +407,18 @@ assert.throws( ); ``` +Note that `error` can not be a string. If a string is provided as the second +argument, then `error` is assumed to be omitted and the string will be used for +`message` instead. This can lead to easy-to-miss mistakes: + +```js +// THIS IS A MISTAKE! DO NOT DO THIS! +assert.throws(myFunction, 'missing foo', 'did not throw with expected message'); + +// Do this instead. +assert.throws(myFunction, /missing foo/, 'did not throw with expected message'); +``` + [Locked]: documentation.html#documentation_stability_index [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message