readme.md

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

   assert
   
   	equal
   	notEqual
   	deepEqual
   	notDeepEqual
   	strictEqual
   	notStrictEqual
   	throws
   	doesNotThrow
       ifError

Additional API

• has / hasNot

  Subset matching

   // 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

   
   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

   	// 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:

   	'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)

   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)

   	$.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:

   // <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.

     	// ! 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

     // ! 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

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

©️ MIT - The Atma.js Project