assertly
v1.0.2
Published
Assert class for BDD-style assertions
Downloads
1,253
Readme
assertly
Assert class for BDD-style assertions.
Assertly was inspired by expect.js and implements almost the same interface. Some additional inspiration for assertions came from the Chai Assert and Chai BDD API's as well.
Assertly was created to address these shortcomings in expect.js:
Why Not Chai?
Chai pretty much has the above covered, but the somewhat common (and troubling) practice of using "dangling getters" is something I think should be avoided. While their use is not essential, it is, as mentioned, common practice. For example:
expect(x).to.be.null; // dangling getter
IDE's and linters rightly warn that an expression like the above "has no side-effects" or "does nothing".
Installation
To install using npm
:
$ npm install assertly --save-dev
To install using yarn
:
$ yarn add assertly --dev
API
The Assertly API is based on BDD-style expectations. For example:
expect(x).to.be(2);
Where "x" is the "actual" value and 2 is the "expected" value. All things begin with
the call to the expect
method which returns an Assert
instance.
This instance has properties (like to
) that modify the conditions of the expectation
(called "modifiers") and methods (like be
) that test these conditions (called
"assertions").
Assertions
An assertion is a method that is called to perform a test for truth. The most common
assertion is be
:
expect(x).to.be(y); // compares x === y
Assertions can also be used as modifiers. Such usage, however, does not evaluate them for truthfulness. For example:
expect(x).to.be.above(2);
In this case, above
is the assertion and be
simply acts as a modifier.
Following are the supported assertions and their aliases ("aka" = "also known as").
a
(aka: "an")approx
(aka: "approximately")be
contain
empty
equal
falsy
greaterThan
(aka: "above", "gt")greaterThanOrEqual
(aka: "atLeast", "ge", "gte")in
key
(aka: "keys")length
lessThan
(aka: "below", "lt")lessThanOrEqual
(aka: "atMost", "le", "lte")match
nan
(aka: "NaN")property
same
throw
truthy
(aka: "ok")within
Modifiers
Modifiers are simply words that decorate assertions. Their presence typically alters the evaluation of assertions but they can sometimes just serve as grammatical aids to make the code readable.
There is no required order to modifiers. The following are equivalent:
expect(x).to.not.be(2);
expect(x).not.to.be(2);
Below are the modifiers provided by Assertly itself.
not
The not
modifier simply negates the result of the test. This is somewhat different
then expect.js in some cases, but pure
negation seems much more intuitive.
only
This modifier applies to keys
and property
assertions to restrict what is allowed
to match the criteria. The only
modifier restricts the assertion such that it will
fail if other keys or properties are present.
own
The own
modifier also applies to keys
and property
and restricts consideration
to "own properties" (as in hasOwnProperty()
).
All inherited properties are ignored when own
is specified.
exactly
Used with throw
to change the string matching behavior from sub-string match to
full string match.
flatly
Used with equal
and same
to flatten the prototype chains of objects and compare
all of the enumerable properties.
to
Serves only to aid readability.
Methods
Asserts can also provide methods. These methods look syntactically like assertions but do not evaluate truth claims. Instead they perform some more general operation.
Assertly provides these methods:
Conjunctions
A conjunction is a word that can be used to create a new Assert
instance based on
a previous instance.
For example:
expect(x).to.be.above(2).and.below(10);
Assertly defines and
by default.
Add-ons
Writing add-ons is easy! In fact it is easier the Chai (imo)!
The "hello world" of extending the assertly words:
const Assert = require('assertly');
Assert.register({
infinity (actual) {
return typeof actual === 'number' && !isFinite(actual);
}
});
expect(1 / 0).to.be.infinity();