The Test
object has a collection of assertion methods.
All assertion methods take optional message
and extra
arguments as
the last two params. The message
is the name of the test. The
extra
argument can contain any arbitrary data about the test, but
the following fields are "special".
todo
Set to boolean true
or a String to mark this as pendingskip
Set to boolean true
or a String to mark this as skippeddiagnostic
Set to boolean true
to show a yaml diagnostic block
even if the test point passes. (Failing asserts always show yaml
diagnostics.)at
Generated by the framework. The location where the assertion
was called. Do not set this field unless you know what you are
doing.stack
Generated by the framework. The stack trace to the point
where the assertion was called. Do not set this field unless you
know what you are doing.Note: There's no requirement that you use tap's built-in
assertions. You can also use any Error-throwing assertion library,
including Node.js's built-in assert
module. A throw fails a test,
so not-throwing passes. That does, however, mean that you won't
generate a test point in your output for each assertion run. You do
you.
Verifies that the object is truthy.
Verifies that the object is not truthy.
If the object is an error, then the assertion fails.
Note: if an error is encountered unexpectedly, it's often better to simply throw it. The Test object will handle this as a failure.
Verify that the event emitter emits the named event before the end of the test.
Returns a promise that resolves when the event is emitted.
Verifies that the promise (or promise-returning function) rejects. If an expected error is provided, then also verify that the rejection matches the expected error.
Note: since promises always reject and resolve asynchronously, this assertion is implemented asynchronously. As such, it does not return a boolean to indicate its passing status. Instead, it returns a Promise that resolves when it is completed.
Verifies that the promise (or promise-returning function) resolves, making no expectation about the value that the promise resolves to.
Note: since promises always reject and resolve asynchronously, this assertion is implemented asynchronously. As such, it does not return a boolean to indicate its passing status. Instead, it returns a Promise that resolves when it is completed.
Verifies that the promise (or promise-returning function) resolves,
and furthermore that the value of the promise matches the wanted
pattern using t.match
.
Note: since promises always reject and resolve asynchronously, this assertion is implemented asynchronously. As such, it does not return a boolean to indicate its passing status. Instead, it returns a Promise that resolves when it is completed.
Verifies that the promise (or promise-returning function) resolves, and furthermore that the value of the promise matches the snapshot.
Note: since promises always reject and resolve asynchronously, this assertion is implemented asynchronously. As such, it does not return a boolean to indicate its passing status. Instead, it returns a Promise that resolves when it is completed.
Expect the function to throw an error. If an expected error is provided, then also verify that the thrown error matches the expected error.
If the expected error is an object, then it's matched against the
thrown error using t.match(er, expectedError)
. If it's a function,
then the error is asserted to be a member of that class.
If the function has a name, and the message is not provided, then the function name will be used as the message.
If the function is not provided, then this will be treated as a todo
test.
Caveat: if you pass a extra
object to t.throws, then you MUST also
pass in an expected error, or else it will read the diag object as the
expected error, and get upset when your thrown error doesn't match
{skip:true}
or whatever.
For example, this will not work as expected:
// anti-example, do not use!
t.throws(function() {throw new Error('x')}, { skip: true })
But this is fine:
// this example is ok to use.
// note the empty 'expected error' object.
// since it has no fields, it'll only verify that the thrown thing is
// an object, not the value of any properties
t.throws(function() {throw new Error('x')}, {}, { skip: true })
The expected error is tested against the throw error using t.match
,
so regular expressions and the like are fine. If the expected error
is an Error
object, then the stack
field is ignored, since that
will generally never match.
Verify that the provided function does not throw.
If the function has a name, and the message is not provided, then the function name will be used as the message.
If the function is not provided, then this will be treated as a todo
test.
Note: if an error is encountered unexpectedly, it's often better to simply throw it. The Test object will handle this as a failure.
Expect the function to throw an uncaught exception at some point in the future, before the test ends. If the test ends without having thrown the expected error, then the test fails.
This is useful for verifying that an error thrown in some part of your code
will not be handled, which would normally result in a program crash, and
verify behavior in those scenarios. If the error is thrown synchronously,
or within a promise, then the t.throws()
or t.rejects()
methods are
usually more appropriate.
If called multiple times, then the uncaught exception errors must be emitted in the order called.
Example:
const t = require('tap')
t.test('sync throw', t => {
t.plan(1)
t.expectUncaughtException({ message: 'sync' })
setImmediate(() => {
throw new Error('sync')
})
})
t.test('async throw', t => {
t.plan(1)
t.expectUncaughtException({ message: 'async' })
setImmediate(async () => {
throw new Error('async')
})
})
t.test('multiple uncaughts must occur in the order specified', t => {
t.plan(2)
t.expectUncaughtException({ message: 'sync' })
t.expectUncaughtException({ message: 'async' })
process.nextTick(() => {
throw new Error('sync')
})
setTimeout(async () => {
throw new Error('async')
}, 100)
})
Note: This method will not properly link a thrown error to the
correct test object in some cases involving native modules on Node version
8, because the async_hooks
module does not track the execution context ID
across native boundaries.
Verify that the object found is exactly the same (that is, ===
) to
the object that is wanted.
Inverse of t.equal()
.
Verify that the object found is not exactly the same (that is, !==
) as
the object that is wanted.
Verify that the found object is deeply equivalent to the wanted
object. Use non-strict equality for scalars (ie, ==
). See:
tcompare
Inverse of t.same()
.
Verify that the found object is not deeply equivalent to the
unwanted object. Uses non-strict inequality (ie, !=
) for scalars.
Strict version of t.same()
.
Verify that the found object is deeply equivalent to the wanted
object. Use strict equality for scalars (ie, ===
).
Inverse of t.strictSame()
.
Verify that the found object is not deeply equivalent to the unwanted
object. Use strict equality for scalars (ie, ===
).
Verify that the found object contains all of the provided fields, and that they are of the same type and value as the pattern provided.
This does not do advanced/loose matching based on constructor, regexp
patterns, and so on, like t.match()
does. You may specify key:
undefined
in the pattern to ensure that a field is not defined in the
found object, but it will not differentiate between a missing property and
a property set to undefined
.
The inverse of t.hasStrict()
. Verifies that the found object does not
contain all of the provided fields, or if it does, that they are not the
same values and/or types.
Verify that the found object contains all of the provided fields, and that they coerce to the same values, even if the types do not match.
This does not do advanced/loose matching based on constructor, regexp
patterns, and so on, like t.match()
does. You may specify key:
undefined
in the pattern to ensure that a field is not defined in the
found object, but it will not differentiate between a missing property and
a property set to undefined
.
The inverse of t.has()
. Verifies that the found object does not contain
all of the provided fields, or if it does, that they do not coerce to the
same values.
Verifies that the object found
contains the property property
and that
it is not undefined
. Searches the prototype chain as well as "own"
properties.
property
must be a string, and found
must be an object.
Verifies that the object found
contains each of the property names in
propertyList
, and that they are not undefined
. Searches prototype
chain as well as "own" properties.
propertyList
must be an iterable object (eg, an Array or Set) of property
names, and found
must be an object.
Verifies that the object found
contains the property property
and that
it is not undefined
. Does not search the prototype chain.
property
must be a string, and found
can be any value other than null
or undefined
(though of course false
and true
have no ownProperties).
Verifies that the object found
contains the property names in
propertyList
, and that they are not undefined
. Does not search the
prototype chain.
propertyList
must be an iterable object (eg, an Array or Set) of property
names, and found
can be any value other than null
or undefined
(though of course false
and true
have no ownProperties).
Verify that the found object matches the pattern provided.
If pattern is a regular expression, and found is a string, then verify that the string matches the pattern.
If the pattern is a string, and found is a string, then verify that the pattern occurs within the string somewhere.
If pattern is an object, then verify that all of the (enumerable)
fields in the pattern match the corresponding fields in the object
using this same algorithm. For example, the pattern {x:/a[sdf]{3}/}
would successfully match {x:'asdf',y:'z'}
.
This is useful when you want to verify that an object has a certain set of required fields, but additional fields are ok.
See tcompare for the full details on how this works.
Inverse of match()
Verify that the found object does not match the pattern provided.
Verify that the object is of the type provided.
Type can be a string that matches the typeof
value of the object, or
the string name of any constructor in the object's prototype chain, or
a constructor function in the object's prototype chain.
For example, all the following will pass:
t.type(new Date(), 'object')
t.type(new Date(), 'Date')
t.type(new Date(), Date)