2 * jQuery QUnit CompletenessTest 0.4
4 * Tests the completeness of test suites for object oriented javascript
5 * libraries. Written to be used in environments with jQuery and QUnit.
6 * Requires jQuery 1.7.2 or higher.
8 * Built for and tested with:
13 * @author Timo Tijhof, 2011-2012
15 /*global jQuery, QUnit */
16 /*jshint eqeqeq:false, eqnull:false, forin:false */
21 hasOwn
= Object
.prototype.hasOwnProperty
,
22 log
= (window
.console
&& window
.console
.log
)
23 ? function () { return window
.console
.log
.apply(window
.console
, arguments
); }
26 // Simplified version of a few jQuery methods, except that they don't
27 // call other jQuery methods. Required to be able to run the CompletenessTest
28 // on jQuery itself as well.
30 keys
: Object
.keys
|| function ( object
) {
32 for ( key
in object
) {
33 if ( hasOwn
.call( object
, key
) ) {
40 var options
, name
, src
, copy
,
41 target
= arguments
[0] || {},
43 length
= arguments
.length
;
45 for ( ; i
< length
; i
++ ) {
46 // Only deal with non-null/undefined values
47 if ( (options
= arguments
[ i
]) != null ) {
48 // Extend the base object
49 for ( name
in options
) {
51 copy
= options
[ name
];
53 // Prevent never-ending loop
54 if ( target
=== copy
) {
58 if ( copy
!== undefined ) {
59 target
[ name
] = copy
;
65 // Return the modified object
68 each: function ( object
, callback
) {
70 for ( name
in object
) {
71 if ( callback
.call( object
[ name
], name
, object
[ name
] ) === false ) {
76 // $.type and $.isEmptyObject are safe as is, they don't call
77 // other $.* methods. Still need to be derefenced into `util`
78 // since the CompletenessTest will overload them with spies.
80 isEmptyObject
: $.isEmptyObject
89 * var myTester = new CompletenessTest( myLib );
90 * @param masterVariable {Object} The root variable that contains all object
91 * members. CompletenessTest will recursively traverse objects and keep track
93 * @param ignoreFn {Function} Optionally pass a function to filter out certain
94 * methods. Example: You may want to filter out instances of jQuery or some
95 * other constructor. Otherwise "missingTests" will include all methods that
96 * were not called from that instance.
98 var CompletenessTest = function ( masterVariable
, ignoreFn
) {
100 // Keep track in these objects. Keyed by strings with the
101 // method names (ie. 'my.foo', 'my.bar', etc.) values are boolean true.
102 this.injectionTracker
= {};
103 this.methodCallTracker
= {};
104 this.missingTests
= {};
106 this.ignoreFn
= undefined === ignoreFn
? function () { return false; } : ignoreFn
;
108 // Lazy limit in case something weird happends (like recurse (part of) ourself).
109 this.lazyLimit
= 2000;
110 this.lazyCounter
= 0;
114 // Bind begin and end to QUnit.
115 QUnit
.begin( function () {
116 that
.walkTheObject( null, masterVariable
, masterVariable
, [], CompletenessTest
.ACTION_INJECT
);
117 log( 'CompletenessTest/walkTheObject/ACTION_INJECT', that
);
120 QUnit
.done( function () {
121 that
.populateMissingTests();
122 log( 'CompletenessTest/populateMissingTests', that
);
124 var toolbar
, testResults
, cntTotal
, cntCalled
, cntMissing
;
126 cntTotal
= util
.keys( that
.injectionTracker
).length
;
127 cntCalled
= util
.keys( that
.methodCallTracker
).length
;
128 cntMissing
= util
.keys( that
.missingTests
).length
;
130 function makeTestResults( blob
, title
, style
) {
131 var elOutputWrapper
, elTitle
, elContainer
, elList
, elFoot
;
133 elTitle
= document
.createElement( 'strong' );
134 elTitle
.textContent
= title
|| 'Values';
136 elList
= document
.createElement( 'ul' );
137 util
.each( blob
, function ( key
) {
138 var elItem
= document
.createElement( 'li' );
139 elItem
.textContent
= key
;
140 elList
.appendChild( elItem
);
143 elFoot
= document
.createElement( 'p' );
144 elFoot
.innerHTML
= '<em>— CompletenessTest</em>';
146 elContainer
= document
.createElement( 'div' );
147 elContainer
.appendChild( elTitle
);
148 elContainer
.appendChild( elList
);
149 elContainer
.appendChild( elFoot
);
151 elOutputWrapper
= document
.getElementById( 'qunit-completenesstest' );
152 if ( !elOutputWrapper
) {
153 elOutputWrapper
= document
.createElement( 'div' );
154 elOutputWrapper
.id
= 'qunit-completenesstest';
156 elOutputWrapper
.appendChild( elContainer
);
158 util
.each( style
, function ( key
, value
) {
159 elOutputWrapper
.style
[key
] = value
;
161 return elOutputWrapper
;
164 if ( cntMissing
=== 0 ) {
166 testResults
= makeTestResults(
168 'Detected calls to ' + cntCalled
+ '/' + cntTotal
+ ' methods. No missing tests!',
170 backgroundColor
: '#D2E0E6',
174 paddingBottom
: '1em',
180 testResults
= makeTestResults(
182 'Detected calls to ' + cntCalled
+ '/' + cntTotal
+ ' methods. ' + cntMissing
+ ' methods not covered:',
184 backgroundColor
: '#EE5757',
188 paddingBottom
: '1em',
194 toolbar
= document
.getElementById( 'qunit-testrunner-toolbar' );
196 toolbar
.insertBefore( testResults
, toolbar
.firstChild
);
204 CompletenessTest
.ACTION_INJECT
= 500;
205 CompletenessTest
.ACTION_CHECK
= 501;
208 CompletenessTest
.fn
= CompletenessTest
.prototype = {
211 * CompletenessTest.fn.walkTheObject
213 * This function recursively walks through the given object, calling itself as it goes.
214 * Depending on the action it either injects our listener into the methods, or
215 * reads from our tracker and records which methods have not been called by the test suite.
217 * @param currName {String|Null} Name of the given object member (Initially this is null).
218 * @param currVar {mixed} The variable to check (initially an object,
219 * further down it could be anything).
220 * @param masterVariable {Object} Throughout our interation, always keep track of the master/root.
221 * Initially this is the same as currVar.
222 * @param parentPathArray {Array} Array of names that indicate our breadcrumb path starting at
223 * masterVariable. Not including currName.
224 * @param action {Number} What is this function supposed to do (ACTION_INJECT or ACTION_CHECK)
226 walkTheObject: function ( currName
, currVar
, masterVariable
, parentPathArray
, action
) {
228 var key
, value
, tmpPathArray
,
229 type
= util
.type( currVar
),
233 if ( this.ignoreFn( currVar
, that
, parentPathArray
) ) {
237 // Handle the lazy limit
239 if ( this.lazyCounter
> this.lazyLimit
) {
240 log( 'CompletenessTest.fn.walkTheObject> Limit reached: ' + this.lazyCounter
, parentPathArray
);
245 if ( type
=== 'function' ) {
247 if ( !currVar
.prototype || util
.isEmptyObject( currVar
.prototype ) ) {
249 if ( action
=== CompletenessTest
.ACTION_INJECT
) {
251 that
.injectionTracker
[ parentPathArray
.join( '.' ) ] = true;
252 that
.injectCheck( masterVariable
, parentPathArray
, function () {
253 that
.methodCallTracker
[ parentPathArray
.join( '.' ) ] = true;
257 // We don't support checking object constructors yet...
258 // ...we can check the prototypes fine, though.
260 if ( action
=== CompletenessTest
.ACTION_INJECT
) {
262 for ( key
in currVar
.prototype ) {
263 if ( hasOwn
.call( currVar
.prototype, key
) ) {
264 value
= currVar
.prototype[key
];
265 if ( key
=== 'constructor' ) {
269 // Clone and break reference to parentPathArray
270 tmpPathArray
= util
.extend( [], parentPathArray
);
271 tmpPathArray
.push( 'prototype' );
272 tmpPathArray
.push( key
);
274 that
.walkTheObject( key
, value
, masterVariable
, tmpPathArray
, action
);
283 // Recursively. After all, this is the *completeness* test
284 if ( type
=== 'function' || type
=== 'object' ) {
285 for ( key
in currVar
) {
286 if ( hasOwn
.call( currVar
, key
) ) {
287 value
= currVar
[key
];
289 // Clone and break reference to parentPathArray
290 tmpPathArray
= util
.extend( [], parentPathArray
);
291 tmpPathArray
.push( key
);
293 that
.walkTheObject( key
, value
, masterVariable
, tmpPathArray
, action
);
299 populateMissingTests: function () {
301 util
.each( ct
.injectionTracker
, function ( key
) {
307 * CompletenessTest.fn.hasTest
309 * Checks if the given method name (ie. 'my.foo.bar')
310 * was called during the test suite (as far as the tracker knows).
311 * If not it adds it to missingTests.
313 * @param fnName {String}
316 hasTest: function ( fnName
) {
317 if ( !( fnName
in this.methodCallTracker
) ) {
318 this.missingTests
[fnName
] = true;
325 * CompletenessTest.fn.injectCheck
327 * Injects a function (such as a spy that updates methodCallTracker when
328 * it's called) inside another function.
330 * @param masterVariable {Object}
331 * @param objectPathArray {Array}
332 * @param injectFn {Function}
334 injectCheck: function ( masterVariable
, objectPathArray
, injectFn
) {
335 var i
, len
, prev
, memberName
, lastMember
,
336 curr
= masterVariable
;
338 // Get the object in question through the path from the master variable,
339 // We can't pass the value directly because we need to re-define the object
340 // member and keep references to the parent object, member name and member
341 // value at all times.
342 for ( i
= 0, len
= objectPathArray
.length
; i
< len
; i
++ ) {
343 memberName
= objectPathArray
[i
];
346 curr
= prev
[memberName
];
347 lastMember
= memberName
;
350 // Objects are by reference, members (unless objects) are not.
351 prev
[lastMember
] = function () {
353 return curr
.apply( this, arguments
);
358 window
.CompletenessTest
= CompletenessTest
;