Kixx Assert

A functional assertion library for ECMAScript.

Created by Kris Walker 2017 - 2023.

Install in the browser:

AMD and Browserify are supported. Or include in your HTML:

<script src="./kixx-assert.js" type="text/javascript"></script>

Then use in your JavaScript:

var KixxAssert = window.KixxAssert;

Install in a Node.js project:

Install with NPM on the command line:

$ npm install --save kixx-assert

Then use in your project:

const KixxAssert = require('kixx-assert');

API

Errors

AssertionError

Assertions

isOk(subject, reason)
isNotOk(subject, reason)
isEqual(expected, actual, reason)
isNotEqual(expected, actual, reason)
isMatch(pattern, actual, reason)
isNotMatch(pattern, actual, reason)
isUndefined(subject, reason)
isDefined(subject, reason)
isEmpty(subject, reason)
isNotEmpty(subject, reason)
includes(item, subject, reason)
doesNotInclude(item, subject, reason)
has(key, subject, reason)
doesNotHave(key, subject, reason)
isGreaterThan(a, b, reason)
isLessThan(a, b, reason)
isNonEmptyString(subject, reason)
isNumberNotNaN(subject, reason)

helpers

identity(x)
complement(f)
type(v)
keys(x)
has(prop, x)
equal(a, b)
greaterThan(a, b)
lessThan(a, b)
match(matcher, x)
isPrimitive(x)
isString(x)
isNumber(x)
isBoolean(x)
isArray(x)
isObject(x)
isFunction(x)
isNull(x)
isUndefined(x)
isDefined(x)
isNumberNotNaN(x)
isNonEmptyString(x)
isEmpty(x)
isNotEmpty(x)
includes(item, list)
doesNotInclude(item, list)
toString(item, list)
printf(pattern, ..rest)
assertion1(guard, reason)
assertion2(guard, reason)

AssertionError

An Error constructor used to identify assertion errors. Passing in a caller can help isolate stack traces to make them more usable.

Access in browsers: window.KixxAssert.AssertionError;

Access in Node.js: require('kixx-assert').AssertionError;

// Example:
function myFunction() {
    throw new KixxAssert.AssertionError('test error', null, myFunction);
}

// Implementation:
function AssertionError (message, props, caller) {
    this.message = message || 'Unspecified AssertionError';
    caller = caller || AssertionError;
    Error.captureStackTrace(this, caller);
}

AssertionError.prototype = Object.create(Error.prototype);

AssertionError.prototype.name = 'AssertionError';

AssertionError.prototype.constructor = AssertionError;

Assertions

Access in browsers: window.KixxAssert.assert;

Access in Node.js: require('kixx-assert').assert;

assert.isOk

KixxAssert.assert.isOk(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject is truthy.

assert.isNotOk

KixxAssert.assert.isNotOk(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject is falsy.

assert.isEqual

KixxAssert.assert.isEqual(expected, actual, reason)

parameter	type	description
expected	any	The value to test against
actual	any	The test subject
reason	String	String used as the first part of the AssertionError message.

Passes if expected strictly equals === actual.

assert.isNotEqual

KixxAssert.assert.isNotEqual(expected, actual, reason)

parameter	type	description
expected	any	The value to test against
actual	any	The test subject
reason	String	String used as the first part of the AssertionError message

Passes if expected does not strictly equal === actual.

assert.isMatch

KixxAssert.assert.isMatch(pattern, actual, reason)

parameter	type	description
pattern	String or RegExp	The pattern to test
actual	any	The test subject
reason	String	String used as the first part of the AssertionError message

Passes if actual matches the pattern String or RegExp.

assert.isNotMatch

KixxAssert.assert.isNotMatch(pattern, actual, reason)

parameter	type	description
pattern	String or RegExp	The pattern to test
actual	any	The test subject
reason	String	String used as the first part of the AssertionError message

Passes if actual does not match the pattern String or RegExp.

assert.isUndefined

KixxAssert.assert.isUndefined(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject is undefined. Fails if the subject is null or false.

assert.isDefined

KixxAssert.assert.isDefined(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject is anything other than undefined.

assert.isEmpty

KixxAssert.assert.isEmpty(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject is an empty Array, String, or Object with no enumerable properties. Also passes for all primitives which are falsy.

assert.isNotEmpty

KixxAssert.assert.isNotEmpty(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject is a non empty Array, String, or Object with enumerable properties. Also passes for all primitives which are truthy.

assert.includes

KixxAssert.assert.includes(item, subject, reason)

parameter	type	description
item	any	The item expected to be found in the subject
subject	Array, Object, or String	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject contains the item. In the case of a String, the item must be a character contained in the subject. In the case of an Array, any primitive or object which strictly equals an item in the Array will pass. In the case of an Object, any primitive or object strictly equals an enumerable property of the Object will pass.

assert.doesNotInclude

KixxAssert.assert.doesNotInclude(item, subject, reason)

parameter	type	description
item	any	The item not expected to be found in the subject
subject	Array, Object, or String	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if the subject does not contain the item. In the case of a String, the item must be a character not in the subject. In the case of an Array, any primitive or object which strictly equals an item in the Array will fail. In the case of an Object, any primitive or object strictly equals an enumerable property of the Object will fail.

assert.has

KixxAssert.assert.has(key, subject, reason)

parameter	type	description
key	String	The name of the object property to test for
subject	Object	The Object to test
reason	String	String used as the first part of the AssertionError message.

Passes if subject has own property key.

assert.doesNotHave

KixxAssert.assert.doesNotHave(key, subject, reason)

parameter	type	description
key	String	The name of the object property to test for
subject	Object	The Object to test
reason	String	String used as the first part of the AssertionError message.

Passes if subject does not have own property key.

assert.isGreaterThan

KixxAssert.assert.isGreaterThan(a, b, reason)

parameter	type	description
a	any	The control value
b	any	The tested value
reason	String	String used as the first part of the AssertionError message.

Assertion will pass if b is greater than a.

assert.isLessThan

KixxAssert.assert.isLessThan(a, b, reason)

parameter	type	description
a	any	The control value
b	any	The tested value
reason	String	String used as the first part of the AssertionError message.

Assertion will pass if b is less than a.

assert.isNonEmptyString

KixxAssert.assert.isNonEmptyString(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if subject is a String with length greater than 0.

assert.isNumberNotNaN

KixxAssert.assert.isNumberNotNaN(subject, reason)

parameter	type	description
subject	any	The item to test
reason	String	String used as the first part of the AssertionError message.

Passes if subject is a Number but not NaN.

Helpers

Access in browsers: window.KixxAssert.helpers;

Access in Node.js: require('kixx-assert').helpers;

helpers.identity

KixxAssert.helpers.identity(x)

parameter	type	description
x	any	The value to return

Returns the input value x.

A function that does nothing but return the parameter supplied to it. Good as a default or placeholder function.

helpers.complement

KixxAssert.helpers.complement(f)

parameter	type	description
f	Function	The the Function to invert

Returns a new Function which will call f.

Takes a function f and returns a function g such that if called with the same arguments when f returns a "truthy" value, g returns false and when f returns a "falsy" value g returns true.

helpers.type

KixxAssert.helpers.type(v)

parameter	type	description
v	any	The value to test

Returns a String representing the type of the value.

Gives a single-word string description of the (native) type of a value, returning such answers as 'Object', 'Number', 'Array', or 'Null'. Does not attempt to distinguish user Object types any further, reporting them all as 'Object'.

helpers.keys

KixxAssert.helpers.keys(x)

parameter	type	description
x	Object	The object to extract property keys from

Returns an Array of the object's own enumerable property names.

Returns a list containing the names of all the enumerable own properties of the supplied object. Note that the order of the output array is not guaranteed to be consistent across different JS platforms.

helpers.has

KixxAssert.helpers.has(prop, x)

parameter	type	description
prop	String	The name of the property to check for
x	Object	The object to to check

Returns a Boolean indicating if the property exists.

Returns whether or not an object has an own property with the specified name.

helpers.equal

KixxAssert.helpers.equal(a, b)

parameter	type	description
a	any	Thing 1
b	any	Thing 2

Returns a Boolean indicating if a and b are strict equal.

Determine if both arguments are strict equal (===).

helpers.greaterThan

KixxAssert.helpers.greaterThan(a, b)

parameter	type	description
a	any	Thing 1
b	any	Thing 2

Returns a Boolean indicating if b is greater than (>) a.

Deterimine if the second argument is greater than the first.

helpers.lessThan

KixxAssert.helpers.lessThan(a, b)

parameter	type	description
a	any	Thing 1
b	any	Thing 2

Returns a Boolean indicating if b is less than (<) a.

Deterimine if the second argument is less than the first.

helpers.match

KixxAssert.helpers.match(matcher, x)

parameter	type	description
matcher	RegExp or String	Regular expression or String to match against
x	String	String to match

Returns a Boolean indicating if x matches matcher.

Determine if the second argument matches the first using a RegExp or String match. If the first argument is a String the second argument will be matched against it using ===. Otherwise the first argument is assumed to be a RegExp and will be matched using .test().

helpers.isPrimitive

KixxAssert.helpers.isPrimitive(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is not an Object or is null.

Indicate if the argument is not an object, or is null.

helpers.isString

KixxAssert.helpers.isString(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is a String.

Indicate if the argument is a String.

helpers.isNumber

KixxAssert.helpers.isNumber(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is a number.

Indicate if the argument is a number or NaN.

helpers.isBoolean

KixxAssert.helpers.isBoolean(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is a Boolean.

Indicate if the argument is a Boolean.

helpers.isArray

KixxAssert.helpers.isArray(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is an Array.

Indicate if the argument is an Array.

helpers.isObject

KixxAssert.helpers.isObject(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is a plain Object.

Indicate if the argument is a plain Object. It will return false for Dates, RegExp, Arrays, etc.

helpers.isFunction

KixxAssert.helpers.isFunction(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is a Function.

Indicate if the argument is a Function.

helpers.isNull

KixxAssert.helpers.isNull(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is null.

Indicate if the argument is null. It will return false for undefined.

helpers.isUndefined

KixxAssert.helpers.isUndefined(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is not defined.

Indicate if the argument is not defined using typeof x === 'undefined'.

helpers.isDefined

KixxAssert.helpers.isDefined(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating if x is defined.

Indicate if the argument is anything other than undefined, even null.

helpers.isNumberNotNaN

KixxAssert.helpers.isNumberNotNaN(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating that x is a Number but not NaN.

Indicate if the first argument is a Number, but not NaN.

helpers.isNonEmptyString

KixxAssert.helpers.isNonEmptyString(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating that x is a String with length greater than 0.

Indicate if the first argument is a String with length greater than zero.

helpers.isEmpty

KixxAssert.helpers.isEmpty(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating that x has its type's empty value.

Returns Boolean true if the first argument is an empty Array, String, or Object with no enumerable properties. Returns Boolean true for all primitives which are falsy and Boolean false for all primitives which are truthy.

helpers.isNotEmpty

KixxAssert.helpers.isNotEmpty(x)

parameter	type	description
x	any	Thing to check

Returns a Boolean indicating that x does not have its type's empty value.

Returns Boolean true if the first argument is an empty Array, String, or Object with more than zero enumerable properties. Returns Boolean true for all primitives which are truthy and Boolean false for all primitives which are falsy.

helpers.includes

KixxAssert.helpers.includes(item, list)

parameter	type	description
item	any	Thing to check
list	Array, String, or Object	List to check

Returns a Boolean indicating that item was found in list using the === comparator.

Returns Boolean true if the second argument is an Array, String, or Object which contains the first argument. In the case of a String, the first argument must be a character contained in the second argument to return true. In the case of an Array, any primitive or object which compares with === will return true. In the case of an Object, any primitive or object which is an enumerable property of the Object and compares wth === will return true.

helpers.doesNotInclude

KixxAssert.helpers.doesNotInclude(item, list)

parameter	type	description
item	any	Thing to check
list	Array, String, or Object	List to check

Returns a Boolean indicating that item was not found in list using the === comparator.

Returns Boolean true if the second argument is an Array, String, or Object which does not contain the first argument. In the case of a String, the first argument must be a character which is not contained in the second argument to return true. In the case of an Array, any primitive or object which compares with === will return false. In the case of an Object, any primitive or object which is an enumerable property of the Object and compares wth === will return false.

helpers.toString

KixxAssert.helpers.toString(x)

parameter	type	description
x	any	The thing to stringify

Returns a String representation of x.

console.log(helpers.toString('foo')); // String("foo")
console.log(helpers.toString(true)); // Boolean(true)
console.log(helpers.toString(99)); // Number(99)
console.log(helpers.toString()); // undefined
console.log(helpers.toString(null)); // null
console.log({}); // Object({})
console.log(Object.create(null)); // [object Object]
console.log(new Cat()); // Cat({})

helpers.printf

KixxAssert.helpers.printf(pattern, ...rest)

parameter	type	description
pattern	String	The pattern string using %d, %s, %x as placeholders for `...rest`
rest	any additional arguments	Any objects to replace in pattern String

Returns a String.

If the first argument is a string with replacement patterns (starting with "%") then the following arguments are stringified and replaced. If the first argument is a string with no replacement patterns it will be returned alone. If the first argument is not a string, then all arguments will simply be stringified, separated by spaces.

console.log(heleprs.printf('foo')); // foo
console.log(helpers.printf('foo %d %x'), 1, null); // foo Number(1) null
console.log(helpers.printf({foo: 'bar'}, 1, null)); // Object({}) Number(1) null

helpers.assertion1

KixxAssert.helpers.assertion1(guard, reason)

parameter	type	description
guard	Function	A Function which will be called with the assertion argument as the assertion test and is expected to return a Boolean.
reason	Function	A Function wich will be called with the assertion argument in the case of failure and is expected to return a String.

Returns a composed assertion Function.

The returned assertion Function will through an AssertionError if the call to the guard() returns false.

const isEmpty = assertion1(isEmpty, function (actual) {
    return printf('expected %x to be empty', actual);
});

isEmpty([1], 'Is it empty?'); // Will throw AssertionError

helpers.assertion2