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

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;
  });
  

:copyright: MIT - The Atma.js Project