fluent-assert
fluent-assert is meant to be a better way of specifying your contract signatures, allowing you to fluently make your assertions for not only types, but different properties of those types.
Getting Started (Required Node >=4)
First install through npm
npm install --save fluent-assert
And then require it
var assert = require('fluent-assert');
Examples
The Basics
All of fluent-asserts entry point functions (as described below) take two arguments: name and value. The only odd man out is assert.custom
fluent-assert has the most of the familiar contract assertions found in other libraries, including:
assert.string(...)
assert.number(...)
assert.bool(...)
assert.object(...)
...
fluent-assert has other type contracts such as:
assert.array(...) // Only checks to make sure value is an array
assert.ok(...) // Asserts value is not null or undefined
assert.custom(name, value, predicate) // Checks if value passes the predicate function
...
Assert
Base assertions not tied to a specific type.
#ok(name, value)
Validates your value is not null
or undefined
ensuring your value is safe to operate on.
assert.ok('myVar', {});
assert.ok('myVar', null);
assert.ok('myVar', undefined);
#defined(name, value)
Validates your value is defined (including null). Useful for allowing null values as defaults for third party libraries,
assert.defined('myVar', {});
assert.defined('myVar', null);
assert.defined('myVar', undefined);
#custom(name, value, predicate)
Validates your value matches the given predicate. Useful when custom logic is needed specific to your own app not included in fluent-assert by default. The predicate function takes the value as an argument to minimize closures and leaves the function open for any extra checking that may be done by fluent-assert
assert.custom('myVar', 5, value => value === 5);
assert.custom('myVar', 5, {});
assert.custom('myVar', 5, value => value === 6);
#optional()
Allows all type assertions (not including those mentioned above) to allow undefined values. The optional flag will be applied throughout the entire assertion chain, so you can still make an assertion without the value being present.
assert.optional().string(undefined).matches(/[A-Z]*/);
Note Once the optional function has been called, the chain will no longer have an optional function, so something like assert.optional().optional()
will result in an error.
String
The string assertion utility has some useful functions for validating the contract on string parameters.
assert.string('myVar', 'test');
#matches(regexp: RegExp)
Validates your value against the supplied regular expression. Throws an assertion error if value does not match or if the argument for matches is not a regular expression.
assert.string('myVar', 'value').matches(/value/);
assert.string('myVar', 'value').matches(/banana/);
assert.string('myVar', 'value').matches('Not regex')
#notEmpty()
Validates your value is not an empty string. Throws an assertion error is string is empty. Only works for the empty string. Use #notWhiteSpace
for all other "empty" string values
assert.string('myVar', 'something').notEmpty();
assert.string('myVar', '').notEmpty();
#notWhiteSpace()
Validates your value is not only white space characters as dictated by JavaScripts RegExp. Will also validate value is not an empty string.
assert.string('myVar', 'something').notWhiteSpace();
assert.string('myVar', ' something ').notWhiteSpace();
assert.string('myVar', ' ').notWhiteSpace();
#uuid() (also guid())
Validates your string is a UUID/GUID. Throws an assertion error otherwise.
assert.string('myVar', 'a4558b56-af55-47e4-9980-28b29e4f81ef').uuid()
assert.string('myVar', 'a4558b56-af55-47e4-9980-28b29e4f81ef').guid()
assert.string('myVar', 'definitely-not-a-uuid').uuid()
Number
The number assertion helps you validate certain properties against numbers.
assert.number('myVar', 0);
#min(min)
Validates your value is equal to or above the min argument. Throws an assertion error if value is below min.
assert.number('myVar', 10).min(0);
assert.number('myVar', 10).min(10);
assert.number('myVar', 10).min(11);
#max(max)
Validates your value is equal to or below the max argument. Throws an assertion error if value is above max.
assert.number('myVar', 10).max(10);
assert.number('myVar', 10).max(100);
assert.number('myVar', 10).max(5);
#range(lower, upper)
Validates your value is within the specified range of [lower] and [upper]. Throws an assertion error if value is outside the range.
assert.number('myVar', 10).range(1, 100);
assert.number('myVar', 10).range(10, 100);
assert.number('myVar', 10).range(1, 10);
assert.number('myVar', 10).range(11, 100);
assert.number('myVar', 10).range(1, 9);
#even()
Validates your value is an even number. Throws an assertion error if value is odd.
assert.number('myVar', 0).even();
assert.number('myVar', 1).even();
#odd()
Validates your value is an odd number. Throws an assertion error if value is even.
assert.number('myVar', 1).odd();
assert.number('myVar', 0).odd();
#equal(compare)
Validates your value is the same as [compare]. Throws an assertion error is value is not equal to [compare].
assert.number('myVar', 10).equal(10);
assert.number('myVar', 10).equal(0);
#in(values)
Validates your value is within an array of given values. Throws an assertion error is value is not within the array.
assert.number('myVar', 10).in([2, 4, 6, 8 ,10]);
assert.number('myVar', 10).in([1, 3, 5, 7, 9]);
#finite()
Validates your value is a number of a finite value. Throws an assertion error otherwise
assert.number('myVar', 10).finite();
assert.number('myVar', Infinity).finite()
assert.number('myVar', -Infinity).finite()
assert.number('myVar', NaN).finite()
#positive()
Validates your value is a positive number. Throws an assertion error if your value is <= 0
assert.number('myVar', 10).positive()
assert.number('myVar', -10).positive()
assert.number('myVar', 0).positive()
#integer()
Validate your value is an integer. Throws an assertion error if your value is a float
assert.number('myVar', 10).integer()
assert.number('myVar', 10.0).integer()
assert.number('myVar', 10.1).integer()
#float()
Validate your value is a float. Throws an assertion error if your value is evaluated as a whole number
assert.number('myVar', 10.1).float()
assert.number('myVar', 10).float()
assert.number('myVar', 10.0).float()
#negative()
Validates your value is a negative number. Throws an assertion error if your value is >= 0
assert.number('myVar', -10).negative()
assert.number('myVar', 10).negative()
assert.number('myVar', 0).negative()
Boolean
Since boolean values are so simple, there are no use cases for assertion chains on booleans.
assert.bool('myVar', true);
assert.boolean('myVar', true);
assert.bool('myVar', {});
Buffer
I'm not that keen on how Buffers work, so for now, there isn't any chaining functionality for Buffers
assert.buffer('myVar', new Buffer(0));
Object
The object assertion helps you validate certain properties against objects.
assert.object('myVar', {});
#hasMember(member)
Validates your value has the specified [member]. Throws an assertion error if value does not have [member]
assert.object('myVar', {greeting: 'Hello'}).hasMember('greeting');
assert.object('myVar', {}).hasMember('greeting');
#instanceOf(type)
Validates your value is an instance of [type] using the instanceof
operator. Throws an assertion error is value is not an instance of [type]
assert.object('myVar', Object('test')).instanceOf(String);
assert.object('myVar', Object('test')).instanceOf(Number);
Array
The array assertion help you validate certain properties against array and its elements.
assert.array('myVar', []);
#of(type)
Validates your array is a consistently typed array of [type]
assert.array('myVar', [1, 2, 3]).of('number');
assert.array('myVar', [1, 2, 3]).of(Number);
assert.array('myVar', [1, 2, '3']).of('number');
assert.array('myVar', [1, 2, '3']).of(Number);
#contains(value)
Validates your array contains some value. Useful for checking required values passed as an array
assert.array('myVar', [1, 2, 3]).contains(2);
assert.array('myVar', [1, 2, 3]).contains(4);
Function
Functions are another of those simple types in js, so currently no useful assertions can be made of functions
assert.func('myVar', function() {});
assert.function('myVar', function() {});
Date
The date assertion helps you validate certain properties against js dates.
assert.date('myVar', new Date('January 1, 1970'));
#before(date)
Validates your date occurs before [date]
assert.date('myVar', new Date('January 1, 1970')).before(new Date('January 2, 1970'));
assert.date('myVar', new Date('January 1, 1970')).before(new Date('December 31, 1969'));
#after(date)
Validates your date occurs after [date]
assert.date('myVar', new Date('January 1, 1970')).after(new Date('December 31, 1969'));
assert.date('myVar', new Date('January 1, 1970')).after(new Date('January 2, 1970'));
#within(lower, upper)
Validates your date occurs between [lower] and [upper]
assert.date('myVar', new Date('January 1, 1970')).within(new Date('December 31, 1969'), new Date('January 2, 1970'));
assert.date('myVar', new Date('January 1, 1970')).within(new Date('January 1, 1970'), new Date('January 3, 1970'));
assert.date('myVar', new Date('January 1, 1970')).within(new Date('December 30, 1969'), new Date('January 1, 1970'));
assert.date('myVar', new Date('January 1, 1970')).within(new Date('January 2, 1970'), new Date('January 4, 1970'));
assert.date('myVar', new Date('January 1, 1970')).within(new Date('December 29, 1969'), new Date('December 31, 1969'));
#dayOf(day)
Validates your date occurs on the day of [day]
assert.date('myVar', new Date('January 1, 1970')).dayOf(1);
assert.date('myVar', new Date('January 1, 1970')).dayOf(2);
#monthOf(month)
Validates your date occurs on the month of [month]
assert.date('myVar', new Date('January 1, 1970')).monthOf(0);
assert.date('myVar', new Date('January 1, 1970')).monthOf('Jan');
assert.date('myVar', new Date('January 1, 1970')).monthOf('January');
assert.date('myVar', new Date('January 1, 1970')).monthOf(1);
assert.date('myVar', new Date('January 1, 1970')).monthOf('Feb');
assert.date('myVar', new Date('January 1, 1970')).monthOf('February');
#yearOf(year)
Validates your date occurs on the year of [year]
assert.date('myVar', new Date('January 1, 1970')).yearOf(1970);
assert.date('myVar', new Date('January 1, 1970')).yearOf(1969);