assertion v1.3.35

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

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](https://github.com/atmajs/assertion/blob/master/test/has.test)
  
  	```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
  	// <div class='container' id='foo'>
  	//		<h4>Baz</h4>
  	//		<span>Qux</span>
  	// </div>
  
  	$('.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