The uvu/assert module is a collection of assertion methods that, like uvu itself, work in Node.js and browser contexts. Additionally, uvu/assert is completely optional, allowing you to bring along existing favorites.
Because uvu operates through thrown Errors (or lack thereof), any Error-based utility can be used as an assertion. As a basic example, this is a completely valid uvu test:
import { test } from 'uvu';
test('this will fail', () => {
if (1 !== 2) throw new Error('Duh!');
});
test.run();With this, uvu will register that the "this will fail" test failed.
You will only be missing the detailed insights (aka, pretty diff'ing) that the included Assertion errors provide.
For all API methods listed:
Trepresents any data typeMessagecan be a string (for custom assertion message) or anErrorinstance
Assert that actual is a truthy value.
assert.ok(12345);
assert.ok(!false);
assert.ok('hello');Assert that actual strictly equals (===) the expects value.
assert.is('hello', 'hello');
const arr = [1, 2, 3];
assert.is(arr, [1, 2, 3]); //=> fails
assert.is(arr, arr); //=> passAssert that actual does not strictly equal (===) the expects value.
assert.is.not(123, '123');
assert.is.not(true, false);Assert that actual is deeply equal to the expects value.
Visit dequal for more information.
const input = {
foo: 123,
bar: [4, 5, 6]
};
assert.equal(input, {
foo: 123,
bar: [4, 5, 6]
});Assert that typeof actual is equal to the expects type.
Available Types are: string, number, boolean, object, undefined, and function.
assert.type(123, 'number');
assert.type('hello', 'string');
assert.type(assert.type, 'function');Assert that actual is an instanceof the expects constructor.
assert.instance(new Date, Date);
assert.instance([1, 2, 3], Array);
assert.instance(/foobar/gi, RegExp);Assert that actual matches the expects pattern.
When expects is a regular expression, it must match the actual value.
When expects is a string, it must exist within the actual value as a substring.
assert.match('hello world', 'wor');
assert.match('hello world', /^hel/);Assert that actual matches the expects multi-line string.
assert.snapshot(
JSON.stringify({ foo: 123 }, null, 2),
`{\n "foo": 123\n}`
);Assert that actual matches the expects multi-line string.
Equivalent to assert.snapshot except that line numbers are printed in the error diff!
assert.fixture(
JSON.stringify({ foo: 123, bar: 456 }, null, 2),
fs.readFileSync('fixture.json', 'utf8')
);Assert that the fn function throws an Error.
When expects is not defined, then any Error thrown satisfies the assertion.
When expects is a string, then the Error's message must contain the expects string.
When expects is a function, then expects will receive the thrown Error and must return a boolean determination.
Since expects is optional, you may also invoke the assert.throws(fn, msg) signature.
const OOPS = () => (null)[0];
assert.throws(() => OOPS());
assert.throws(() => OOPS(), /Cannot read property/);
assert.throws(() => OOPS(), err => err instanceof TypeError);If you are trying to assert that an async function throws an Error, the following approach is recommended:
try {
await asyncFnThatThrows();
assert.unreachable('should have thrown');
} catch (err) {
assert.instance(err, Error);
assert.match(err.message, 'something specific');
assert.is(err.code, 'ERROR123');
}Assert that a line should never be reached.
try {
throw new Error('Oops');
assert.unreachable('I will not run');
} catch (err) {
assert.is(err.message, 'Oops');
}Assert that actual is falsey.
assert.not(0);
assert.not(null);
assert.not(false);Assert that actual is not truthy.
This is an alias for assert.not.
Assert that actual does not deeply equal the expects value.
Visit dequal for more information.
const input = {
foo: 123,
bar: [4, 5, 6]
};
assert.not.equal(input, {
foo: 123
});Assert that typeof actual is not equal to the expects type.
Available Types are: string, number, boolean, object, undefined, and function.
assert.not.type(123, 'object');
assert.not.type('hello', 'number');
assert.not.type(assert.type, 'undefined');Assert that actual is not an instanceof the expects constructor.
assert.not.instance(new Date, Number);
assert.not.instance([1, 2, 3], String);
assert.not.instance(/foobar/gi, Date);Assert that actual does not match the expects pattern.
When expects is a regular expression, it must not match the actual value.
When expects is a string, it must not exist within the actual value as a substring.
assert.not.match('hello world', 'other');
assert.not.match('hello world', /other/g);Assert that actual does not match the expects snapshot.
assert.not.snapshot(
JSON.stringify({ foo: 123 }, null, 2),
`{"foo":123,"bar":456}`
);Assert that actual does not match the expects multi-line string.
Equivalent to assert.not.snapshot except that line numbers are printed in the error diff!
assert.not.fixture(
JSON.stringify({ foo: 123, bar: 456 }, null, 2),
fs.readFileSync('fixture.json', 'utf8')
);Assert that the fn function does not throw, or does not throw of expects type.
const PASS = () => {};
const FAIL = () => {
throw new Error('Oops');
};
assert.not.throws(() => PASS()); //=> pass
assert.not.throws(() => FAIL()); //=> fails
assert.not.throws(() => FAIL(), /Oops/); //=> pass
assert.not.throws(() => FAIL(), /foobar/); //=> fails
assert.not.throws(() => FAIL(), err => err.message.length > 0); //=> passThe base Assertion class, which extends Error directly.
Internally, uvu checks if thrown errors are Assertion errors as part of its formatting step.
Type: string
Required: true
The error message to print.
Note: By default, this is the generated default from each
uvu/assertmethod.
Type: string
Required: false
The detailed diff output, as generated by uvu/diff.
Type: boolean
Required: false
If the options.message was generated.
This will be false when an uvu/assert method received a custom message.
Type: string
Required: true
The assertion method name.
Type: any
Required: true
The expected value.
Type: any
Required: true
The actual value.