Kixx Assert

A functional assertion library for ECMAScript.

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

KixxAssert.helpers.assertion1(guard, reason)

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

Returns a composed assertion Function.

The returned assertion Function will throw an AssertionError if the call to the guard() returns false. If the returned assertion function is called with only 1 argument, it will automatically curry, returning a function which will accept the remaining 2 arguments.

const isEqual = assertion2(helpers.equal, function (expected, actual) {
    return printf('expected %x to equal %x', actual, expected);
});

const isEqualToFoo = isEqual('foo');

isEqualToFoo('bar', 'is it equal to "foo"?'); // Will throw AssertionError

Copyright and License

Copyright: (c) 2017 - 2022 by Kris Walker (www.kixx.name)

Unless otherwise indicated, all source code is licensed under the MIT license. See MIT-LICENSE for details.