31 KiB
Bupkis API Reference
Complete reference for all built-in Bupkis assertions. This document is organized by assertion category.
Table of Contents
- Core Concepts
- Primitive Assertions
- Numeric Assertions
- String & Pattern Assertions
- Collection Assertions
- Object Assertions
- Function Assertions
- Equality & Comparison Assertions
- Error Assertions
- Date & Time Assertions
- Promise Assertions
- Other Assertions
Core Concepts
Natural Language Assertions
Bupkis uses natural language phrases instead of method chaining:
// Instead of:
expect(actual).toEqual(expected);
// Write:
expect(actual, 'to equal', expected);
expect(actual, 'is', expected);
expect(actual, 'to be', expected);
Anatomy of an Assertion
expect(subject, 'phrase', [parameter?, phrase?, parameter?, ...]);
- Subject: The value being tested (first parameter)
- Phrase: String describing the assertion (e.g., 'to be', 'to equal')
- Parameter: Optional values for comparison or validation
Negation
ANY assertion can be negated by prepending not to the first phrase:
expect(42, 'to be', 42); // passes
expect(42, 'not to be', '42'); // passes
expect('hello', 'not to be a number'); // passes
Concatenation with 'and'
Chain multiple assertions on the same subject:
expect(
user,
'to be an object',
'and',
'to have property',
'name',
'and',
'to satisfy',
{ age: expect.it('to be greater than', 18) },
);
Embeddable Assertions with expect.it()
Use expect.it() to embed assertions within "to satisfy" patterns:
expect(user, 'to satisfy', {
name: expect.it('to be a string'),
email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, // RegExp works too
age: expect.it('to be greater than', 18),
roles: [expect.it('to be a string')], // Each element must be a string
});
Primitive Assertions
{unknown} to be a string
Aliases: None
Checks: Value is a string primitive or String object
expect('hello', 'to be a string'); // ✓
expect(42, 'to be a string'); // ✗
expect(42, 'not to be a string'); // ✓
{unknown} to be a boolean
Aliases: to be a bool, to be boolean
Checks: Value is a boolean primitive or Boolean object
expect(true, 'to be a boolean'); // ✓
expect(0, 'to be a boolean'); // ✗
expect(0, 'not to be a boolean'); // ✓
{unknown} to be a number
Aliases: to be finite
Checks: Value is a finite number (NaN and Infinity excluded)
expect(42, 'to be a number'); // ✓
expect(NaN, 'to be a number'); // ✗ (NaN not considered a number)
expect(Infinity, 'to be a number'); // ✗ (Infinity not considered a number)
{unknown} to be a bigint
Aliases: None
Checks: Value is a BigInt
expect(9007199254741991n, 'to be a bigint'); // ✓
expect(42, 'to be a bigint'); // ✗
{unknown} to be a symbol
Aliases: None
Checks: Value is a Symbol
expect(Symbol('foo'), 'to be a symbol'); // ✓
expect('foo', 'to be a symbol'); // ✗
{unknown} to be null
Aliases: None
Checks: Value is exactly null
expect(null, 'to be null'); // ✓
expect(undefined, 'to be null'); // ✗
{unknown} to be undefined
Aliases: None
Checks: Value is exactly undefined
expect(undefined, 'to be undefined'); // ✓
expect(null, 'to be undefined'); // ✗
{unknown} to be a primitive
Aliases: None
Checks: Value is a primitive (string, number, boolean, null, undefined, symbol, bigint)
expect('hello', 'to be a primitive'); // ✓
expect(42, 'to be a primitive'); // ✓
expect({}, 'to be a primitive'); // ✗
Numeric Assertions
{unknown} to be infinite
Aliases: None
Checks: Value is Infinity or -Infinity
expect(Infinity, 'to be infinite'); // ✓
expect(-Infinity, 'to be infinite'); // ✓
expect(42, 'to be infinite'); // ✗
{unknown} to be Infinity
Aliases: None
Checks: Value is exactly positive Infinity
expect(Infinity, 'to be Infinity'); // ✓
expect(-Infinity, 'to be Infinity'); // ✗
{unknown} to be -Infinity
Aliases: None
Checks: Value is exactly negative Infinity
expect(-Infinity, 'to be -Infinity'); // ✓
expect(Infinity, 'to be -Infinity'); // ✗
{unknown} to be positive
Aliases: to be a positive number
Checks: Value is a positive finite number (excludes 0)
expect(42, 'to be positive'); // ✓
expect(0, 'to be positive'); // ✗ (zero is not positive)
expect(-5, 'to be positive'); // ✗
{unknown} to be a positive integer
Aliases: to be a positive int
Checks: Value is a positive integer (excludes 0)
expect(42, 'to be a positive integer'); // ✓
expect(3.14, 'to be a positive integer'); // ✗ (not an integer)
expect(0, 'to be a positive integer'); // ✗ (zero excluded)
{unknown} to be negative
Aliases: to be a negative number
Checks: Value is a negative finite number (excludes 0)
expect(-42, 'to be negative'); // ✓
expect(0, 'to be negative'); // ✗
expect(5, 'to be negative'); // ✗
{unknown} to be a negative integer
Aliases: to be a negative int
Checks: Value is a negative integer (excludes 0)
expect(-42, 'to be a negative integer'); // ✓
expect(-3.14, 'to be a negative integer'); // ✗ (not an integer)
{unknown} to be NaN
Aliases: None
Checks: Value is NaN
expect(NaN, 'to be NaN'); // ✓
expect(42, 'to be NaN'); // ✗
{unknown} to be an integer
Aliases: to be a safe integer, to be an int, to be a safe int
Checks: Value is a safe integer
expect(42, 'to be an integer'); // ✓
expect(3.14, 'to be an integer'); // ✗
{unknown} to be greater than {number}
Aliases: None
Checks: Value is strictly greater than the parameter
expect(10, 'to be greater than', 5); // ✓
expect(5, 'to be greater than', 10); // ✗
{unknown} to be less than {number}
Aliases: to be lt
Checks: Value is strictly less than the parameter
expect(5, 'to be less than', 10); // ✓
expect(10, 'to be less than', 5); // ✗
{unknown} to be greater than or equal to {number}
Aliases: to be at least, to be gte
Checks: Value is greater than or equal to the parameter
expect(10, 'to be at least', 10); // ✓
expect(15, 'to be at least', 10); // ✓
expect(5, 'to be at least', 10); // ✗
{unknown} to be less than or equal to {number}
Aliases: to be at most, to be lte
Checks: Value is less than or equal to the parameter
expect(10, 'to be at most', 10); // ✓
expect(5, 'to be at most', 10); // ✓
expect(15, 'to be at most', 10); // ✗
{number} to be between {number} and {number}
Aliases: to be within
Checks: Value is between two numbers (inclusive)
expect(5, 'to be between', 1, 10); // ✓
expect(15, 'to be between', 1, 10); // ✗
{number} to be close to {number} within {number}
Aliases: None
Checks: Value is within tolerance of target
Parameters: (subject, target, tolerance)
expect(1.0, 'to be close to', 1.1, 0.2); // ✓ (diff = 0.1)
expect(3.14159, 'to be close to', 3.14, 0.01); // ✓
expect(1.0, 'to be close to', 2.0, 0.5); // ✗ (diff = 1.0)
String & Pattern Assertions
{string} to begin with {string}
Aliases: to start with
Checks: String starts with the specified prefix
expect('hello world', 'to begin with', 'hello'); // ✓
expect('hello world', 'to start with', 'world'); // ✗
{string} to end with {string}
Aliases: None
Checks: String ends with the specified suffix
expect('hello world', 'to end with', 'world'); // ✓
expect('hello world', 'to end with', 'hello'); // ✗
{string} to match {RegExp}
Aliases: None
Checks: String matches the regular expression
expect('hello123', 'to match', /\d+/); // ✓
expect('JavaScript', 'to match', /^Java/); // ✓
expect('hello', 'to match', /\d+/); // ✗
{string} to be empty
Aliases: None
Checks: String has zero length
expect('', 'to be empty'); // ✓
expect('hello', 'to be empty'); // ✗
{string} to be non-empty
Aliases: None
Checks: String has at least one character
expect('hello', 'to be non-empty'); // ✓
expect(' ', 'to be non-empty'); // ✓ (whitespace counts)
expect('', 'to be non-empty'); // ✗
{string} includes {string}
Aliases: contains
Checks: String contains the substring
expect('hello world', 'includes', 'world'); // ✓
expect('hello', 'includes', 'world'); // ✗
{unknown} to be a RegExp
Aliases: to be a regex, to be a regexp
Checks: Value is a RegExp object
expect(/hello/, 'to be a RegExp'); // ✓
expect(new RegExp('world'), 'to be a regex'); // ✓
expect('hello', 'to be a RegExp'); // ✗
Collection Assertions
{unknown} to be an array
Aliases: to be array
Checks: Value is an Array
expect([], 'to be an array'); // ✓
expect([1, 2, 3], 'to be an array'); // ✓
expect('hello', 'to be an array'); // ✗
{arraylike} to be empty
Aliases: None
Checks: Array/string/collection has zero length
expect([], 'to be empty'); // ✓
expect([1, 2, 3], 'to be empty'); // ✗
{array} to have length {nonnegative-integer}
Aliases: to have size
Checks: Array/string has exact length
expect([1, 2, 3], 'to have length', 3); // ✓
expect('hello', 'to have length', 5); // ✓
expect([1, 2], 'to have length', 3); // ✗
{arraylike} to be non-empty
Aliases: None
Checks: Array/string has at least one element
expect([1, 2, 3], 'to be non-empty'); // ✓
expect([], 'to be non-empty'); // ✗
{array} to contain {any}
Aliases: to include
Checks: Array contains the value
expect([1, 2, 3], 'to contain', 2); // ✓
expect(['a', 'b'], 'to include', 'c'); // ✗
{Map} to contain {any}
Aliases: to include
Checks: Map contains the key
const map = new Map([['key1', 'value1']]);
expect(map, 'to contain', 'key1'); // ✓
expect(map, 'to contain', 'key2'); // ✗
{Map} to have size {nonnegative-integer}
Aliases: None
Checks: Map has exact size
const map = new Map([
['a', 1],
['b', 2],
]);
expect(map, 'to have size', 2); // ✓
expect(map, 'to have size', 3); // ✗
{Map} to be empty
Aliases: None
Checks: Map has no entries
expect(new Map(), 'to be empty'); // ✓
expect(new Map([['a', 1]]), 'to be empty'); // ✗
{Set} to contain {any}
Aliases: to include
Checks: Set contains the value
const set = new Set([1, 2, 3]);
expect(set, 'to contain', 2); // ✓
expect(set, 'to contain', 5); // ✗
{Set} to have size {nonnegative-integer}
Aliases: None
Checks: Set has exact size
const set = new Set([1, 2, 3]);
expect(set, 'to have size', 3); // ✓
expect(set, 'to have size', 5); // ✗
{Set} to be empty
Aliases: None
Checks: Set has no elements
expect(new Set(), 'to be empty'); // ✓
expect(new Set([1]), 'to be empty'); // ✗
{unknown} to be a Set
Aliases: None
Checks: Value is a Set
expect(new Set(), 'to be a Set'); // ✓
expect([1, 2, 3], 'to be a Set'); // ✗
{WeakMap} to contain {object | symbol}
Aliases: to include
Checks: WeakMap contains the key
const obj = {};
const wm = new WeakMap([[obj, 'value']]);
expect(wm, 'to contain', obj); // ✓
{unknown} to be a WeakMap
Aliases: None
Checks: Value is a WeakMap
expect(new WeakMap(), 'to be a WeakMap'); // ✓
expect(new Map(), 'to be a WeakMap'); // ✗
{WeakSet} to contain {object | symbol}
Aliases: to include
Checks: WeakSet contains the value
const obj = {};
const ws = new WeakSet([obj]);
expect(ws, 'to contain', obj); // ✓
{unknown} to be a WeakSet
Aliases: None
Checks: Value is a WeakSet
expect(new WeakSet(), 'to be a WeakSet'); // ✓
expect(new Set(), 'to be a WeakSet'); // ✗
Object Assertions
{unknown} to be an object
Aliases: None
Checks: Value is an object (includes arrays, excludes null)
expect({}, 'to be an object'); // ✓
expect([], 'to be an object'); // ✓ (arrays are objects)
expect(new Date(), 'to be an object'); // ✓
expect(null, 'to be an object'); // ✗
expect('hello', 'to be an object'); // ✗
Note: to be an object already implies non-null. No need for redundant null checks.
{unknown} to be a record
Aliases: to be a plain object
Checks: Value is a plain object (excludes arrays, dates, etc.)
expect({}, 'to be a record'); // ✓
expect({ a: 1 }, 'to be a plain object'); // ✓
expect([], 'to be a record'); // ✗
expect(new Date(), 'to be a record'); // ✗
{object} to be empty
Aliases: None
Checks: Object has no own enumerable properties
expect({}, 'to be empty'); // ✓
expect({ a: 1 }, 'to be empty'); // ✗
{object} to have keys {array}
Aliases: to have properties, to have props, to include keys, to include properties, to include props, to contain keys, to contain properties, to contain props
Checks: Object has all specified keys
expect({ a: 1, b: 2 }, 'to have keys', ['a', 'b']); // ✓
expect({ a: 1 }, 'to have keys', ['a', 'b']); // ✗ (missing 'b')
{object} to have key {keypath}
Aliases: to have property, to have prop, to include key, to include property, to include prop, to contain key, to contain property, to contain prop
Checks: Object has property at keypath (supports dot/bracket notation)
Keypath formats:
- Dot notation:
'prop.nested' - Bracket notation:
'arr[0]','obj["key"]' - Mixed:
'data.items[1].name'
const obj = {
foo: { bar: [{ baz: 'value' }] },
items: [{ id: 1 }, { id: 2 }],
};
expect(obj, 'to have property', 'foo.bar'); // ✓
expect(obj, 'to have key', 'foo.bar[0].baz'); // ✓
expect(obj, 'to have property', 'items[1].id'); // ✓
expect(obj, 'to have key', 'nonexistent.path'); // ✗
{object} to have exact key {string | number | symbol}
Aliases: to have exact property, to have exact prop
Checks: Object has direct property (no keypath traversal)
const sym = Symbol('test');
const obj = {
'key.with.dots': 'value', // literal key, not nested
'key[with]brackets': 'value', // literal key, not array
[sym]: 'symbol value',
};
expect(obj, 'to have exact key', 'key.with.dots'); // ✓ (literal key)
expect(obj, 'to have exact property', 'key[with]brackets'); // ✓
expect(obj, 'to have exact key', sym); // ✓
{object} to satisfy {any}
Aliases: to be like
Checks: Object contains at least the specified properties (partial match)
Special features:
- RegExp values test corresponding property as string
expect.it()embeds assertions- Ignores extra properties
expect({ a: 1, b: 2, c: 3 }, 'to satisfy', { a: 1, b: 2 }); // ✓
// Using RegExp
expect({ email: 'user@example.com', phone: '+1-555-0123' }, 'to satisfy', {
email: /^user@/,
phone: /^\+1-555/,
}); // ✓
// Using expect.it()
expect({ name: 'John', age: 30 }, 'to satisfy', {
name: expect.it('to be a string'),
age: expect.it('to be greater than', 18),
}); // ✓
{object} to have a null prototype
Aliases: to be a dictionary
Checks: Object was created with Object.create(null)
const obj = Object.create(null);
expect(obj, 'to have a null prototype'); // ✓
expect({}, 'to have a null prototype'); // ✗
{string | number | symbol} to be an enumerable property of {non-null}
Aliases: {non-null} to have enumerable property {string | number | symbol}
Checks: Property exists and is enumerable
const obj = { a: 1, b: 2 };
expect('a', 'to be an enumerable property of', obj); // ✓
Object.defineProperty(obj, 'c', { value: 3, enumerable: false });
expect('c', 'to be an enumerable property of', obj); // ✗
{unknown} to be sealed
Aliases: None
Checks: Object is sealed (Object.seal())
const obj = { a: 1 };
Object.seal(obj);
expect(obj, 'to be sealed'); // ✓
expect({}, 'to be sealed'); // ✗
{unknown} to be frozen
Aliases: None
Checks: Object is frozen (Object.freeze())
const obj = { a: 1 };
Object.freeze(obj);
expect(obj, 'to be frozen'); // ✓
expect({}, 'to be frozen'); // ✗
{unknown} to be extensible
Aliases: None
Checks: New properties can be added to object
expect({}, 'to be extensible'); // ✓
const obj = {};
Object.preventExtensions(obj);
expect(obj, 'to be extensible'); // ✗
Function Assertions
{unknown} to be a function
Aliases: None
Checks: Value is a function
expect(() => {}, 'to be a function'); // ✓
expect(Math.max, 'to be a function'); // ✓
expect('hello', 'to be a function'); // ✗
{unknown} to be an async function
Aliases: None
Checks: Value is an async function
expect(async () => {}, 'to be an async function'); // ✓
expect(() => {}, 'to be an async function'); // ✗
{unknown} to be a constructor
Aliases: to be constructible, to be a class
Checks: Function can be called with 'new'
Warning: Cannot reliably distinguish classes from regular functions
class MyClass {}
expect(MyClass, 'to be a class'); // ✓
expect(Date, 'to be a constructor'); // ✓
{function} to have arity {nonnegative-integer}
Aliases: None
Checks: Function has exact number of parameters
function add(a, b) {
return a + b;
}
expect(add, 'to have arity', 2); // ✓
expect(add, 'to have arity', 3); // ✗
{function} to throw [{any}]
Aliases: to throw an error satisfying
Checks: Function throws when called
Optional parameter: Uses "to satisfy" semantics (string/RegExp/object matching)
expect(() => {
throw new Error('oops');
}, 'to throw'); // ✓
// String matching
expect(
() => {
throw new Error('Specific error');
},
'to throw',
'Specific error',
); // ✓
// RegExp matching
expect(
() => {
throw new Error('Error: failed');
},
'to throw',
/failed/,
); // ✓
// Object matching
expect(
() => {
throw new Error('Custom error');
},
'to throw',
{ message: 'Custom error' },
); // ✓
{function} to throw a {constructor}
Aliases: to throw an
Checks: Function throws specific error type
expect(
() => {
throw new TypeError('type error');
},
'to throw a',
TypeError,
); // ✓
expect(
() => {
throw new TypeError('type error');
},
'to throw a',
RangeError,
); // ✗
{function} to throw a {constructor} satisfying {any}
Aliases: to throw an {constructor} satisfying
Checks: Function throws specific error type matching pattern
expect(
() => {
const err = new Error('Custom error');
err.code = 'CUSTOM_CODE';
throw err;
},
'to throw a',
Error,
'satisfying',
{ code: 'CUSTOM_CODE' },
); // ✓
Equality & Comparison Assertions
{unknown} to equal {any}
Aliases: to be, equals, is, is equal to, to strictly equal, is strictly equal to
Checks: Values are strictly equal (===)
expect(42, 'to be', 42); // ✓
expect('hello', 'to equal', 'hello'); // ✓
expect(42, 'is', '42'); // ✗ (different types)
expect({}, 'to equal', {}); // ✗ (different references)
{unknown} to deep equal {any}
Aliases: to deeply equal
Checks: Values are deeply equal (recursive comparison)
expect({ a: 1, b: 2 }, 'to deep equal', { a: 1, b: 2 }); // ✓
expect([1, 2, 3], 'to deeply equal', [1, 2, 3]); // ✓
expect({ a: 1 }, 'to deep equal', { a: 1, b: 2 }); // ✗
{unknown} to be one of {array}
Aliases: None
Checks: Value is in the array
expect(2, 'to be one of', [1, 2, 3]); // ✓
expect('blue', 'to be one of', ['red', 'green', 'blue']); // ✓
expect(5, 'to be one of', [1, 2, 3]); // ✗
{unknown} to be an instance of {constructor}
Aliases: to be a, to be an
Checks: Value is instance of constructor
expect(new Date(), 'to be an instance of', Date); // ✓
expect([], 'to be a', Array); // ✓
expect('hello', 'to be an instance of', Number); // ✗
{unknown} to be a {intrinsic-type}
Aliases: to be an, to have type
Checks: Value is of intrinsic type (case-insensitive)
Intrinsic types: string, number, boolean, bigint, symbol, undefined, object, function, null, Map, Set, WeakMap, WeakSet, WeakRef, Date, Error, Array, RegExp, Promise
expect(new Date(), 'to be a', 'Date'); // ✓
expect([], 'to be an', 'Array'); // ✓
expect(1, 'to be a', 'number'); // ✓
Error Assertions
{unknown} to be an Error
Aliases: to be a Error
Checks: Value is an Error instance
expect(new Error(), 'to be an Error'); // ✓
expect(new TypeError(), 'to be an Error'); // ✓
expect('error message', 'to be an Error'); // ✗
{Error} to have message {string}
Aliases: None
Checks: Error has exact message
const error = new Error('Something went wrong');
expect(error, 'to have message', 'Something went wrong'); // ✓
expect(error, 'to have message', 'Different message'); // ✗
{Error} to have message matching {RegExp}
Aliases: None
Checks: Error message matches pattern
const error = new Error('File not found: /path/to/file.txt');
expect(error, 'to have message matching', /File not found/); // ✓
expect(error, 'to have message matching', /\.txt$/); // ✓
Date & Time Assertions
{unknown} to be a Date
Aliases: to be a date
Checks: Value is a Date object
expect(new Date(), 'to be a Date'); // ✓
expect('2024-01-01', 'to be a Date'); // ✗
expect(1704067200000, 'to be a Date'); // ✗ (timestamp)
{unknown} to be a valid date
Aliases: to be date-like
Checks: Value can be converted to a valid date
expect(new Date(), 'to be a valid date'); // ✓
expect('2024-01-01', 'to be date-like'); // ✓
expect(1704067200000, 'to be a valid date'); // ✓ (timestamp)
expect('invalid-date', 'to be a valid date'); // ✗
{date-like} to be before {date-like}
Aliases: None
Checks: Date is before another date
expect(new Date('2022-01-01'), 'to be before', new Date('2023-01-01')); // ✓
expect('2022-01-01', 'to be before', '2023-01-01'); // ✓
{date-like} to be after {date-like}
Aliases: None
Checks: Date is after another date
expect(new Date('2023-01-01'), 'to be after', new Date('2022-01-01')); // ✓
expect(Date.now(), 'to be after', new Date('2020-01-01')); // ✓
{date-like} to be between {date-like} and {date-like}
Aliases: None
Checks: Date is between two dates (inclusive)
expect(
new Date('2022-06-01'),
'to be between',
new Date('2022-01-01'),
new Date('2022-12-31'),
); // ✓
{date-like} to be the same date as {date-like}
Aliases: None
Checks: Dates represent the same calendar day (ignores time)
expect(
new Date('2023-01-01T10:00:00'),
'to be the same date as',
new Date('2023-01-01T15:30:00'),
); // ✓ (same date, different times)
{date-like} to equal {date-like} within {duration}
Aliases: None
Checks: Dates are within specified duration
Duration formats: "100 milliseconds", "30 seconds", "5 minutes", "2 hours", "7 days"
const date1 = new Date('2023-01-01T10:00:00.000Z');
const date2 = new Date('2023-01-01T10:00:00.500Z');
expect(date1, 'to equal', date2, 'within', '1 second'); // ✓ (500ms diff)
{unknown} to be a weekend
Aliases: None
Checks: Date is Saturday or Sunday (in UTC)
expect(new Date('2023-01-07'), 'to be a weekend'); // ✓ (Saturday)
expect(new Date('2023-01-09'), 'to be a weekend'); // ✗ (Monday)
{unknown} to be a weekday
Aliases: None
Checks: Date is Monday-Friday (in UTC)
expect(new Date('2023-01-09'), 'to be a weekday'); // ✓ (Monday)
expect(new Date('2023-01-07'), 'to be a weekday'); // ✗ (Saturday)
Promise Assertions
Note: All promise assertions require expectAsync() instead of expect()
{Promise} to resolve
Aliases: to fulfill
Checks: Promise resolves successfully
await expectAsync(Promise.resolve(42), 'to resolve'); // ✓
await expectAsync(async () => 'result', 'to resolve'); // ✓
await expectAsync(Promise.reject('error'), 'to resolve'); // ✗
{Promise} to reject
Aliases: None
Checks: Promise rejects
await expectAsync(Promise.reject('error'), 'to reject'); // ✓
await expectAsync(async () => {
throw new Error('failed');
}, 'to reject'); // ✓
await expectAsync(Promise.resolve(42), 'to reject'); // ✗
{Promise} to reject with a {constructor}
Aliases: to reject with an
Checks: Promise rejects with specific error type
await expectAsync(
Promise.reject(new TypeError('Type error')),
'to reject with a',
TypeError,
); // ✓
{Promise} to reject with error satisfying {any}
Aliases: None
Checks: Promise rejection matches pattern (string/RegExp/object)
// String matching
await expectAsync(
Promise.reject(new Error('Specific error')),
'to reject with',
'Specific error',
); // ✓
// RegExp matching
await expectAsync(
Promise.reject(new Error('Error: Something failed')),
'to reject with',
/Something failed/,
); // ✓
// Object matching
await expectAsync(
Promise.reject({ message: 'Custom error', code: 500 }),
'to reject with',
{ message: 'Custom error' },
); // ✓
{Promise} to resolve with value satisfying {any}
Aliases: to fulfill with value satisfying
Checks: Promise resolves to value matching pattern
// String matching
await expectAsync(
Promise.resolve('Hello World'),
'to fulfill with value satisfying',
'Hello World',
); // ✓
// RegExp matching
await expectAsync(
Promise.resolve('Success: Operation completed'),
'to resolve to value satisfying',
/Success/,
); // ✓
// Object matching
await expectAsync(
Promise.resolve({ status: 'ok', data: [1, 2, 3] }),
'to fulfill with value satisfying',
{ status: 'ok' },
); // ✓
Other Assertions
{unknown} to be truthy
Aliases: to exist, to be ok
Checks: Value is truthy
expect(1, 'to be truthy'); // ✓
expect('hello', 'to be truthy'); // ✓
expect(true, 'to exist'); // ✓
expect(0, 'to be truthy'); // ✗
expect('', 'to exist'); // ✗
expect(null, 'to be ok'); // ✗
{unknown} to be falsy
Aliases: None
Checks: Value is falsy
expect(0, 'to be falsy'); // ✓
expect('', 'to be falsy'); // ✓
expect(false, 'to be falsy'); // ✓
expect(null, 'to be falsy'); // ✓
expect(undefined, 'to be falsy'); // ✓
expect(1, 'to be falsy'); // ✗
{unknown} to be defined
Aliases: None
Checks: Value is not undefined
expect(0, 'to be defined'); // ✓
expect('', 'to be defined'); // ✓
expect(null, 'to be defined'); // ✓
expect(undefined, 'to be defined'); // ✗
Quick Reference Tables
Type Checking
| Phrase | Checks |
|---|---|
to be a string |
Is a string |
to be a number |
Is a finite number |
to be a boolean |
Is a boolean |
to be a bigint |
Is a BigInt |
to be a symbol |
Is a Symbol |
to be an object |
Is an object (non-null) |
to be a function |
Is a function |
to be an array |
Is an Array |
to be a Date |
Is a Date object |
to be an Error |
Is an Error |
to be null |
Is null |
to be undefined |
Is undefined |
to be defined |
Is not undefined |
Comparisons
| Phrase | Checks |
|---|---|
to equal, to be, is |
Strict equality (===) |
to deep equal |
Deep structural equality |
to be greater than |
Numeric > comparison |
to be less than |
Numeric < comparison |
to be between |
Within range (inclusive) |
to be one of |
Value in array |
Collections
| Phrase | Checks |
|---|---|
to be empty |
Length/size is 0 |
to have length |
Exact length/size |
to contain, to include |
Contains value |
to have property, to have key |
Has property (keypath support) |
to have properties, to have keys |
Has all specified keys |
Object Patterns
| Phrase | Checks |
|---|---|
to satisfy |
Partial object match with RegExp/expect.it() support |
to be like |
Alias for to satisfy |
Promises
| Phrase | Requires | Checks |
|---|---|---|
to resolve |
expectAsync() |
Promise resolves |
to reject |
expectAsync() |
Promise rejects |
to reject with |
expectAsync() |
Rejection matches pattern |
to resolve with value satisfying |
expectAsync() |
Resolution matches pattern |
Functions
| Phrase | Checks |
|---|---|
to throw |
Function throws |
to throw a {Type} |
Function throws specific error type |
to have arity |
Function parameter count |