assertion

Assertion Library for Browsers and NodeJS
----


Based on the API Interface of the NodeJS Assert module. And is part of the uTest Library.

_As a standalone module can be found in NPM repository_
``bash
npm install assertion
`

##### API

###### NodeJS API

- Assert Documentation

`javascript
assert

equal
notEqual
deepEqual
notDeepEqual
strictEqual
notStrictEqual
throws
doesNotThrow
ifError
`

###### Additional API

- has / hasNot

Subset matching
`javascript
// Substring search
assert.has(String, String | RegExp, ?message);

// Simple property existence check
assert.has(Object, String);

// Sub-object match
assert.has(Object, Object);

// Check if item exists in set
assert.has(Array, Primitive);

// Subset match
assert.has(Array, Array);
`

> When checking arrays or objects, deep matching is performed. See tests

`javascript

assert.has({
foo: 'foo',
bar: {
qux: {
qux: 'qux'
quux: 'quux'
},
baz: [1, 2, 3]
}
}, {
foo: null,
bar: {
baz: [1],
qux: {
qux: 'qux'
}
}
});

`

- is/isNot

Type check
`javascript
// Check by Typename
assert.is(Any, String, ?message)

// Check by Contructor (instanceof)
assert.is(Any, Function);
`
Typename is extracted from Object.prototype.toString.call, so these are:
`javascript
'String'
'Number'
'Null'
'Undefined'
'Function'
'RegExp'
'Date'
'Object' // any object will pass here
'HTML**' // DOM Node, e.g. HTMLBodyElement
'CustomEvent'
...
all other built-in types
`

- lessThan lessThanOrEqaul greaterThan greaterThanOrEqual

Compares two digits

- Aliases

There are also aliases (_which can be set to globals, to simplify the write-read of tests_)

`javascript
assert.eq_ === assert.equal
assert.notEq_ === assert.notEqual

assert.lt_ === assert.lessThan
assert.lte_ === assert.lessThanOrEqaul
assert.gt_ === assert.greaterThan
assert.gt_ === assert.greaterThanOrEqual

assert.deepEq_ === assert.deepEqual
assert.notDeepEq_ === assert.notDeepEqual
`


- jQuery

jQuery Assertion Extensions (_alias name syntax_)
`javascript
$.fn.eq_
$.fn.notEq_
$.fn.deepEq_
$.fn.notDeepEq_
$.fn.has_
$.fn.hasNot_
$.fn.lt_
$.fn.lte_
$.fn.gt_
$.fn.gte_
`
Functions API:
- Get Property
- ` (Key, Expected) `
- ` ([Key, Expected], message) `
- Function call
- ` (FnName [, ...arguments], Expected) `
- ` ([FnName [, ...arguments], Expected], message) `

has/hasNot
- Node Find/Filter Assertions
- ` (Selector, ?ExpectedCount) `


Example:
`javascript
//



$('.container')
.eq_('length', 1)
.eq_('attr', 'id', 'foo')
.eq_('hasClass', 'container', true)

.children()
.eq_('length', 2)
.has_('html', 'span')

.filter('h4')
.eq_('length', 1)
.eq_('text', 'Baz')

// addition sample
.is_('visible'),
.is_('hidden')
.eq_('css', 'border-left-width', '2px')
;

$('.container')
.has_('h4')
.hasNot_('h1')
;
`


- Assert callbacks calls

- await

_Wait for a callback_

Creates a wrapper function to ensure that the function is called.
`javascript
// ! Arguments order does not matter
var fn = assert.await(
String / optional - name of this wrapper/
Function / optional - wrap the function/,
Object / optional - use binded context/,
Number / optional - expectation count, default is 1/
);

// creates item in assert.callbacks
[
{
name: String,
error: Error, // to receive the stack trace
count: Number
}
];

// after the fn function is called count times, then the object is removed
// from the callbacks set


// Example
var fn = assert.await();
assert.callbacks.length === 1;
try {
throw new Error()
} catch {
fn();
}

assert.callbacks.length === 0;

`
- avoid

_Unexpect more then N function calls_
`javascript
// ! Arguments order does not matter
var fn = assert.avoid(
String / optional - name of this wrapper/
Function / optional - wrap the function/,
Object / optional - use binded context/,
Number / optional - amount of allowed calls, default is 0/
);

fooDfr()
.fail(assert.avoid())
.done(function(){
// ..
})


`

- Listener

You can attach listener to the assertions.
Event Types:
- start
- fail
> if fail type listener is attached, then exceptions are not thrown.
- success

`javascript
// sample
assert.on('fail', function(error){
error instanceof assert.AssertionError;
});
``

:copyright: MIT - The Atma.js Project