assert-throws
assert-throws
is an assertion method for Node.js which checks if a synchronous or asynchronous function throws. It can also compare properties of the error (such as message
, code
and stack
and any other) with expected ones using string strict equality, a regular expression, or a function.
yarn add -D assert-throws
Table of Contents
API
The package exports the default throws
function.
async throws(
config: {
fn: function,
args?: any|any[],
context?: any,
message?: Assertion,
code?: Assertion,
error?: Assertion,
[prop]?: Assertion,
},
): Error
Checks if a function throws an error. As a minimum, the function should be passed in the fn
property. If the assertion passes, the method returns the error which was thrown by the tested function.
!(string|RegExp|!Function)
_assertThrows.Assertion
: An assertion to perform.
_assertThrows.Config
: Parameters to the assert-throws
method.
Name | Type | Description |
---|---|---|
fn* | !Function | The function to test, either sync or async. |
args | (* \ | !Array<*>) |
context | * | The context in which to execute the function. Global context will be set by default. |
message | _assertThrows.Assertion | A string, regex, or function to test the message. |
code | _assertThrows.Assertion | A string, regex, or function to test the code. |
stack | _assertThrows.Assertion | A string, regex, or function to test the stack. |
prop | _assertThrows.Assertion | A string, regex, or function to test any other property of the error. |
error | Error | An error to perform strict comparison against. |
{ await throw 'test-error'} { // 1. TEST a throwing function. await // 2. TEST a throwing function (alternative syntax). await console}
Everything passed.
const testThrows = async { await } { try await catch stack console }
Error: Function testThrows should have thrown.
at example (/Users/zavr/adc/assert-throws/example/throws-fail.js:9:11)
at Object.<anonymous> (/Users/zavr/adc/assert-throws/example/throws-fail.js:15:3)
at Module.r._compile (/Users/zavr/adc/assert-throws/node_modules/alamode/depack/depack-lib.js:836:20)
at Object.l.(anonymous function).E._extensions.(anonymous function) [as .js] (/Users/zavr/adc/assert-throws/node_modules/alamode/depack/depack-lib.js:839:7)
Arguments
To pass arguments to the tested function, the args
properties can be used.
const testThrows = async { if shouldThrow throw message} { try // 1. TEST that a function with arguments throws (pass). await // 2. TEST that a function with an argument throws (pass). await // 2. TEST that a function with arguments throws (alternative) (pass). await // 3. TEST that a function with arguments throws (fail). await catch stack console }
Error: Function testThrows should have thrown.
at example (/Users/zavr/adc/assert-throws/example/args.js:29:11)
at <anonymous>
Context
To pass a context to the function, the context
properties can be set. Otherwise, it will use the global context, unless it was bound.
{ if thisshouldThrow throw 'An error occurred.'} { try // 1. TEST a function with context (pass). await // 2. TEST a function with a context (fail). await catch stack console }
Error: Function testThrows should have thrown.
at example (/Users/zavr/adc/assert-throws/example/context.js:16:11)
at <anonymous>
Assertions
If a function throws, any of the error properties can be tested. Every property specified in the configuration will test a property of the error, e.g., message
, code
and others.
String Equality
It is possible to check that any property of a thrown error is equal to a given string.
{ await throw 'test-error'} { try // 1. TEST that a function throws with a string (pass). await // 2. TEST that a function throws with a string (fail). await catch stack console }
Error: testwrong-error
test-error != wrong-error
at example (/Users/zavr/adc/assert-throws/example/string.js:17:11)
at <anonymous>
RegExp Test
Moreover, a regular expression can be used to validate an error's property.
{ await const error = 'test-error' errorcode = 'ENOENT' throw error} { try // 1. TEST that a function throws with a regexp (pass). await // 2. TEST that a function throws with a regexp (fail). await catch stack console }
Error: ENOENT does not match regular expression /ENOEXMPL/
at example (/Users/zavr/adc/assert-throws/example/regexp.js:19:11)
at <anonymous>
Function Evaluation
For more advanced usage, a function can be used to test a property. It will receive the property of the error and should throw when an assertion does not pass.
{ await const error = 'test-error' throw error} { try // 1. TEST that a function throws with a function (pass). await // 2. TEST that a function throws with a function (fail). await catch stack console }
Error: The function has an anonymous call stack line.
at example (/Users/zavr/adc/assert-throws/example/function.js:22:11)
at <anonymous>
Multiple Assertions
Any number of assertions can be added at the same time, and they will all be executed. However, only the first failing assertion will be presented.
{ const err = 'test-error' errcode = 'ENOTEST' erractual = -1 errexpected = Infinity await errstack = throw err} { try // 1. TEST that a function throws with a regexp (pass). await // 2. TEST that a function throws with a regexp (fail). await catch stack console }
Error: -Infinity
Infinity != -Infinity
at example (/Users/zavr/adc/assert-throws/example/multiple.js:31:11)
at <anonymous>
Strict Equality
assert-throws
allows to assert on a strict equality of an error.
const error = 'test-error' { await throw error} { try // 1. TEST that a function throws the correct error (pass). await // 1. TEST that a function throws the correct error (fail). await catch stack console }
Error: Error: test-error is not strict equal to Error: Another error..
at example (/Users/zavr/adc/assert-throws/example/strict.js:19:11)
at <anonymous>
Copyright
(c) Context Testing 2019