/**
* jQuery QUnit CompletenessTest 0.4
*
* Tests the completeness of test suites for object oriented javascript
* libraries. Written to be used in environments with jQuery and QUnit.
* Requires jQuery 1.7.2 or higher.
*
* Built for and tested with:
* - Chrome 19
* - Firefox 4
* - Safari 5
*
* @author Timo Tijhof, 2011-2012
*/
( function ( mw, $ ) {
'use strict';
var util,
hasOwn = Object.prototype.hasOwnProperty,
log = ( window.console && window.console.log )
? function () { return window.console.log.apply( window.console, arguments ); }
: function () {};
// Simplified version of a few jQuery methods, except that they don't
// call other jQuery methods. Required to be able to run the CompletenessTest
// on jQuery itself as well.
util = {
keys: Object.keys || function ( object ) {
var key, keys = [];
for ( key in object ) {
if ( hasOwn.call( object, key ) ) {
keys.push( key );
}
}
return keys;
},
each: function ( object, callback ) {
var name;
for ( name in object ) {
if ( callback.call( object[ name ], name, object[ name ] ) === false ) {
break;
}
}
},
// $.type and $.isEmptyObject are safe as is, they don't call
// other $.* methods. Still need to be derefenced into `util`
// since the CompletenessTest will overload them with spies.
type: $.type,
isEmptyObject: $.isEmptyObject
};
/**
* CompletenessTest
*
* @constructor
* @example
* var myTester = new CompletenessTest( myLib );
* @param {Object} masterVariable The root variable that contains all object
* members. CompletenessTest will recursively traverse objects and keep track
* of all methods.
* @param {Function} [ignoreFn] Optionally pass a function to filter out certain
* methods. Example: You may want to filter out instances of jQuery or some
* other constructor. Otherwise "missingTests" will include all methods that
* were not called from that instance.
*/
function CompletenessTest( masterVariable, ignoreFn ) {
var warn,
that = this;
// Keep track in these objects. Keyed by strings with the
// method names (ie. 'my.foo', 'my.bar', etc.) values are boolean true.
this.injectionTracker = {};
this.methodCallTracker = {};
this.missingTests = {};
this.ignoreFn = ignoreFn === undefined ? function () { return false; } : ignoreFn;
// Lazy limit in case something weird happends (like recurse (part of) ourself).
this.lazyLimit = 2000;
this.lazyCounter = 0;
// Bind begin and end to QUnit.
QUnit.begin( function () {
// Suppress warnings (e.g. deprecation notices for accessing the properties)
warn = mw.log.warn;
mw.log.warn = $.noop;
that.walkTheObject( masterVariable, null, masterVariable, [] );
log( 'CompletenessTest/walkTheObject', that );
// Restore warnings
mw.log.warn = warn;
warn = undefined;
} );
QUnit.done( function () {
that.populateMissingTests();
log( 'CompletenessTest/populateMissingTests', that );
var toolbar, testResults, cntTotal, cntCalled, cntMissing;
cntTotal = util.keys( that.injectionTracker ).length;
cntCalled = util.keys( that.methodCallTracker ).length;
cntMissing = util.keys( that.missingTests ).length;
function makeTestResults( blob, title, style ) {
var elOutputWrapper, elTitle, elContainer, elList, elFoot;
elTitle = document.createElement( 'strong' );
elTitle.textContent = title || 'Values';
elList = document.createElement( 'ul' );
util.each( blob, function ( key ) {
var elItem = document.createElement( 'li' );
elItem.textContent = key;
elList.appendChild( elItem );
} );
elFoot = document.createElement( 'p' );
elFoot.innerHTML = '<em>— CompletenessTest</em>';
elContainer = document.createElement( 'div' );
elContainer.appendChild( elTitle );
elContainer.appendChild( elList );
elContainer.appendChild( elFoot );
elOutputWrapper = document.getElementById( 'qunit-completenesstest' );
if ( !elOutputWrapper ) {
elOutputWrapper = document.createElement( 'div' );
elOutputWrapper.id = 'qunit-completenesstest';
}
elOutputWrapper.appendChild( elContainer );
util.each( style, function ( key, value ) {
elOutputWrapper.style[ key ] = value;
} );
return elOutputWrapper;
}
if ( cntMissing === 0 ) {
// Good
testResults = makeTestResults(
{},
'Detected calls to ' + cntCalled + '/' + cntTotal + ' methods. No missing tests!',
{
backgroundColor: '#D2E0E6',
color: '#366097',
paddingTop: '1em',
paddingRight: '1em',
paddingBottom: '1em',
paddingLeft: '1em'
}
);
} else {
// Bad
testResults = makeTestResults(
that.missingTests,
'Detected calls to ' + cntCalled + '/' + cntTotal + ' methods. ' + cntMissing + ' methods not covered:',
{
backgroundColor: '#EE5757',
color: 'black',
paddingTop: '1em',
paddingRight: '1em',
paddingBottom: '1em',
paddingLeft: '1em'
}
);
}
toolbar = document.getElementById( 'qunit-testrunner-toolbar' );
if ( toolbar ) {
toolbar.insertBefore( testResults, toolbar.firstChild );
}
} );
return this;
}
/* Public methods */
CompletenessTest.fn = CompletenessTest.prototype = {
/**
* CompletenessTest.fn.walkTheObject
*
* This function recursively walks through the given object, calling itself as it goes.
* Depending on the action it either injects our listener into the methods, or
* reads from our tracker and records which methods have not been called by the test suite.
*
* @param {String|Null} currName Name of the given object member (Initially this is null).
* @param {mixed} currVar The variable to check (initially an object,
* further down it could be anything).
* @param {Object} masterVariable Throughout our interation, always keep track of the master/root.
* Initially this is the same as currVar.
* @param {Array} parentPathArray Array of names that indicate our breadcrumb path starting at
* masterVariable. Not including currName.
*/
walkTheObject: function ( currObj, currName, masterVariable, parentPathArray ) {
var key, currVal, type,
ct = this,
currPathArray = parentPathArray;
if ( currName ) {
currPathArray.push( currName );
currVal = currObj[ currName ];
} else {
currName = '(root)';
currVal = currObj;
}
type = util.type( currVal );
// Hard ignores
if ( this.ignoreFn( currVal, this, currPathArray ) ) {
return null;
}
// Handle the lazy limit
this.lazyCounter++;
if ( this.lazyCounter > this.lazyLimit ) {
log( 'CompletenessTest.fn.walkTheObject> Limit reached: ' + this.lazyCounter, currPathArray );
return null;
}
// Functions
if ( type === 'function' ) {
// Don't put a spy in constructor functions as it messes with
// instanceof etc.
if ( !currVal.prototype || util.isEmptyObject( currVal.prototype ) ) {
this.injectionTracker[ currPathArray.join( '.' ) ] = true;
this.injectCheck( currObj, currName, function () {
ct.methodCallTracker[ currPathArray.join( '.' ) ] = true;
} );
}
}
// Recursively. After all, this is the *completeness* test
// This also traverses static properties and the prototype of a constructor
if ( type === 'object' || type === 'function' ) {
for ( key in currVal ) {
if ( hasOwn.call( currVal, key ) ) {
this.walkTheObject( currVal, key, masterVariable, currPathArray.slice() );
}
}
}
},
populateMissingTests: function () {
var ct = this;
util.each( ct.injectionTracker, function ( key ) {
ct.hasTest( key );
} );
},
/**
* CompletenessTest.fn.hasTest
*
* Checks if the given method name (ie. 'my.foo.bar')
* was called during the test suite (as far as the tracker knows).
* If not it adds it to missingTests.
*
* @param {String} fnName
* @return {Boolean}
*/
hasTest: function ( fnName ) {
if ( !( fnName in this.methodCallTracker ) ) {
this.missingTests[ fnName ] = true;
return false;
}
return true;
},
/**
* CompletenessTest.fn.injectCheck
*
* Injects a function (such as a spy that updates methodCallTracker when
* it's called) inside another function.
*
* @param {Object} masterVariable
* @param {Array} objectPathArray
* @param {Function} injectFn
*/
injectCheck: function ( obj, key, injectFn ) {
var spy,
val = obj[ key ];
spy = function () {
injectFn();
return val.apply( this, arguments );
};
// Make the spy inherit from the original so that its static methods are also
// visible in the spy (e.g. when we inject a check into mw.log, mw.log.warn
// must remain accessible).
// XXX: https://github.com/jshint/jshint/issues/2656
/*jshint ignore:start */
/*jshint proto:true */
spy.__proto__ = val;
/*jshint ignore:end */
// Objects are by reference, members (unless objects) are not.
obj[ key ] = spy;
}
};
/* Expose */
window.CompletenessTest = CompletenessTest;
}( mediaWiki, jQuery ) );