justo.assert

An assertion library.

Developed in Dogma, compiled to JavaScript.

Engineered in Valencia, Spain, EU by Justo Labs.

Use

The package must be imported as follows:

import assert from "justo.assert";

Value assertions

To assert, we must wrap a value with the assert object for performing the check. Example:

assert(value).eq(123)

Type assertions

To check whether a value is of a type or another, we can use:

//string
assert(value).isText()
assert(value).isNotText()
assert(value).isString()
assert(value).isNotString()

//boolean
assert(value).isBool()
assert(value).isNotBool()

//number
assert(value).isNum()
assert(value).isNotNum()

//null
assert(value).isNil()
assert(value).isNotNil()

assert(value).isNull()
assert(value).isNotNull()

//object
assert(value).isMap()
assert(value).isNotMap()

assert(value).isObject()
assert(value).isNotObject()

//array
assert(value).isList()
assert(value).isNotList()

assert(value).isArray()
assert(value).isNotArray()

//set
assert(value).isSet()
assert(value).isNotSet()

//function
assert(value).isFn()
assert(value).isNotFn()

//callable object
assert(value).isCallable()
assert(value).isNotCallable()

//promise
assert(value).isPromise()
assert(value).isNotPromise()

For checking if a value is instance of a given class, we can use:

assert(value).isInstanceOf(className)
assert(value).isInstanceOf(class)

assert(value).isNotInstanceOf(className)
assert(value).isNotInstanceOf(class)

Instead of isInstanceOf() and isNotInstanceOf(), we also can use their alias is() and isNot().

eq(), ne(), lt(), le(), gt() and ge()

With eq(), ne(), lt(), le(), gt() and gt() we can check whether a value is equal to, not equal to, less than, less than or equal to, greater than and greater than or equal to another.

assert(value1).eq(value2)
assert(value1).ne(value2)
assert(value1).lt(value2)
assert(value1).le(value2)
assert(value1).gt(value2)
assert(value1).ge(value2)

sameAs() and notSameAs()

With sameAs() and notSameAs() we can check whether a value is same as other:

assert(value).sameAs(value)
assert(value).notSameAs(value)

similarTo() and notSimilarTo()

With similarTo() and notSimilarTo() we check whether an array is equal to another, not keeping in mind the order of the items:

assert(array1).similarTo(array2)
assert(array1).notSimilarTo(array2)

Examples:

assert({1, 2, 3}).similarTo({2, 1, 3})  //true
assert({1, 2, 3}).similarTo({3, 2, 1})  //true
assert({1, 2, 3}).similarTo({1, 3, 2})  //true
assert({1, 2, 3}).similarTo({1, 2, 4})  //false

between() and notBetween()

With between() and notBetween(), we check whether a value is into a range:

assert(value).between(start, end)
assert(value).notBetween(start, end)

includes(), notIncludes() and doesNotInclude()

With includes(), notIncludes() and doesNotInclude() we check whether a string contains a given text or an array contains an item:

assert(value).includes(item)
assert(value).notIncludes(item)
assert(value).doesNotInclude(item)

has(), notHas() and doesNotHave()

With has(), notHas() and doesNotHave() we can check whether an object contains one or several fields:

assert(value).has(field)
assert(value).has(fields)
assert(value).notHas(field)
assert(value).notHas(fields)
assert(value).doesNotHave(field)
assert(value).doesNotHave(fields)

Examples:

assert({one: 1, two: 2, three: 3}).has("one")
assert({one: 1, two: 2, three: 3}).has(["one", "two"])
assert({one: 1, two: 2, three: 3}).has({
  one: 1,
  two: 2
})

forEach()

When the value under asserting is a list, we can use forEach() for checking the items:

assert(value).forEach(fields)
assert(value).forEach(func)

When an object is passed as argument, the fields must have the given values. So, for example, the following one:

assert(dev.getUserWorks(work.user)).isList().isNotEmpty().forEach({user: work.user});

is similar to:

const ww = dev.getUserWorks(work.user);
assert(ww).isList().isNotEmpty();
for (let w of ww) assert(w).has({user: work.user});

When a function is passed, each item is passed to the function. Example:

assert(resp.json()).isList().isNotEmpty().forEach(function(o) {
  assert(o.req).isObject().mem("req").eq(req);
});

isEmpty() and isNotEmpty()

With isEmpty() and isNotEmpty() we can check whether an object is empty as for example a list or string:

assert(value).isEmpty()
assert(value).isNotEmpty()

len() and notLen()

With len() and notLen() we can check the string or array length:

assert(value).len(len)
assert(value).notLen(len)

Also possible getting the length from other list:

assert([1, 2, 3]).len([1, 3, 5])  //ok, both with length equal to 3
assert([1, 2, 3]).len([1, 5])     //nop, one with length 3; and other 2

like() and notLike()

With like() and notLike() we check whether a value matches a pattern:

assert(value).like(pattern)
assert(value).notLike(pattern)

startsWith(), notStartsWith() and doesNotStartWith()

With startsWith(), we check whether a value starts with a given prefix:

assert(value).startsWith(prefix)
assert(value).notStartsWith(prefix)
assert(value).doesNotStartWith(prefix)

endsWith(), notEndsWith() and doesNotEndWith()

With endsWith(), we check whether a value ends with a given suffix:

assert(value).endsWith(suffix)
assert(value).notEndsWith(suffix)
assert(value).doesNotEndWith(suffix)

Function assertions

To check whether a function raises an error, we can use raises(), notRaises() and doesNotRaise():

assert(fn).raises()
assert(fn).raises(err)
assert(fn).notRaises()
assert(fn).notRaises(err)
assert(fn).doesNotRaise()
assert(fn).doesNotRaise(err)

The function to check must not expect arguments.

Example:

assert(function() {
  //code
}).raises()

assert(function() {
  //code
}).raises("My custom error.")

File assertions

To work with files, we have to use the function assert.file():

assert.file(...path)

Next we can use assertion methods such as:

assert.file("/my/file.txt").exists()
assert.file("/my", "file.txt").doesNotExist()

exists(), notExists() and doesNotExist()

With exists(), notExists() and doesNotExist() we check whether a file exists:

assert.file(...path).exists()
assert.file(...path).notExists()
assert.file(...path).doesNotExist()

isEmpty() and isNotEmpty()

With isEmpty() and isNotEmpty() we check whether a file is empty:

assert.file(path).isEmpty()
assert.file(path).isNotEmpty()

includes(), notIncludes() and doesNotInclude()

With includes(), notIncludes() and doesNotInclude() we check whether a file contains a given content:

assert.file(path).includes(txt)
assert.file(path).notIncludes(txt)
assert.file(path).doesNotInclude(txt)

eq() and ne()

With eq() and ne() we check whether the file content is given one:

assert.file(path).eq(txt)
assert.file(path).ne(txt)

isJson()

With isJson() we can check if a file has a JSON format:

assert.file(path).isJson()

sameAs() and notSameAs()

With sameAs() and notSameAs() we check whether two files contains the same:

assert.file(path1).sameAs(path2)
assert.file(path1).notSameAs(path2)

Directory assertions

To work with directories, we have to use the function assert.dir():

assert.dir(...args)

Next we can use assertion methods such as:

assert.dir("/my/dir").exists()
assert.dir("/my", "dir").doesNotExist()

exists(), notExists() and doesNotExist()

With exists(), notExists() and doesNotExist() we check whether a directory exists:

assert.dir(path).exists()
assert.dir(path).notExists()
assert.dir(path).doesNotExist()

has(), notHas() and doesNotHave()

With has(), notHas() and doesNotHave() we check whether a directory has a child entry (such as a file or a dir):

assert.dir(path).has(name)
assert.dir(path).notHas(name)
assert.dir(path).doesNotHave(name)

Chaining assertions

We can chain assertion methods for the same value, directory or file such as the following example:

assert.file(path).exists().isNotEmpty()
//similar to
assert.file(path).exists()
assert.file(path).isNotEmpty()

assert(number).ge(10).le(25)
//similar to
assert(number).ge(10)
assert(number).le(25)

mem()

Sometimes, we need to assert multiple members of a source value. With the mem() method, we can get the value for one of its members:

mem(name:string) : ValueWrapper
mem(idx:number) : ValueWrapper
mem(...:string|number) : ValueWrapper

Examples:

value = {x: 123, y: 456};
assert(value).mem("x").eq(123);                                           //ok
assert(value).isMap().mem("x").isNum().eq(123).mem("y").isNum().eq(456);  //ok

value = ["zero", "one", "two", "three"];
assert(value).mem(1).eq("one").mem(0).eq("zero");                         //ok

value = {x: ["zero", "one", "two", "three"]};
assert(value).mem("x", 1).eq("one");                                      //ok

The mem() method always returns with respect to the source value passed to assert(). And the assertions are respect to the last member got from mem().