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
19 hasOwn
= Object
.prototype.hasOwnProperty
,
20 log
= (window
.console
&& window
.console
.log
)
21 ? function () { return window
.console
.log
.apply(window
.console
, arguments
); }
24 // Simplified version of a few jQuery methods, except that they don't
25 // call other jQuery methods. Required to be able to run the CompletenessTest
26 // on jQuery itself as well.
28 keys
: Object
.keys
|| function ( object
) {
30 for ( key
in object
) {
31 if ( hasOwn
.call( object
, key
) ) {
38 var options
, name
, src
, copy
,
39 target
= arguments
[0] || {},
41 length
= arguments
.length
;
43 for ( ; i
< length
; i
++ ) {
44 options
= arguments
[ i
];
45 // Only deal with non-null/undefined values
46 if ( options
!== null && options
!== undefined ) {
47 // Extend the base object
48 for ( name
in options
) {
50 copy
= options
[ name
];
52 // Prevent never-ending loop
53 if ( target
=== copy
) {
57 if ( copy
!== undefined ) {
58 target
[ name
] = copy
;
64 // Return the modified object
67 each: function ( object
, callback
) {
69 for ( name
in object
) {
70 if ( callback
.call( object
[ name
], name
, object
[ name
] ) === false ) {
75 // $.type and $.isEmptyObject are safe as is, they don't call
76 // other $.* methods. Still need to be derefenced into `util`
77 // since the CompletenessTest will overload them with spies.
79 isEmptyObject
: $.isEmptyObject
87 * var myTester = new CompletenessTest( myLib );
88 * @param masterVariable {Object} The root variable that contains all object
89 * members. CompletenessTest will recursively traverse objects and keep track
91 * @param ignoreFn {Function} Optionally pass a function to filter out certain
92 * methods. Example: You may want to filter out instances of jQuery or some
93 * other constructor. Otherwise "missingTests" will include all methods that
94 * were not called from that instance.
96 function CompletenessTest( masterVariable
, ignoreFn
) {
98 // Keep track in these objects. Keyed by strings with the
99 // method names (ie. 'my.foo', 'my.bar', etc.) values are boolean true.
100 this.injectionTracker
= {};
101 this.methodCallTracker
= {};
102 this.missingTests
= {};
104 this.ignoreFn
= undefined === ignoreFn
? function () { return false; } : ignoreFn
;
106 // Lazy limit in case something weird happends (like recurse (part of) ourself).
107 this.lazyLimit
= 2000;
108 this.lazyCounter
= 0;
112 // Bind begin and end to QUnit.
113 QUnit
.begin( function () {
114 that
.walkTheObject( null, masterVariable
, masterVariable
, [], CompletenessTest
.ACTION_INJECT
);
115 log( 'CompletenessTest/walkTheObject/ACTION_INJECT', that
);
118 QUnit
.done( function () {
119 that
.populateMissingTests();
120 log( 'CompletenessTest/populateMissingTests', that
);
122 var toolbar
, testResults
, cntTotal
, cntCalled
, cntMissing
;
124 cntTotal
= util
.keys( that
.injectionTracker
).length
;
125 cntCalled
= util
.keys( that
.methodCallTracker
).length
;
126 cntMissing
= util
.keys( that
.missingTests
).length
;
128 function makeTestResults( blob
, title
, style
) {
129 var elOutputWrapper
, elTitle
, elContainer
, elList
, elFoot
;
131 elTitle
= document
.createElement( 'strong' );
132 elTitle
.textContent
= title
|| 'Values';
134 elList
= document
.createElement( 'ul' );
135 util
.each( blob
, function ( key
) {
136 var elItem
= document
.createElement( 'li' );
137 elItem
.textContent
= key
;
138 elList
.appendChild( elItem
);
141 elFoot
= document
.createElement( 'p' );
142 elFoot
.innerHTML
= '<em>— CompletenessTest</em>';
144 elContainer
= document
.createElement( 'div' );
145 elContainer
.appendChild( elTitle
);
146 elContainer
.appendChild( elList
);
147 elContainer
.appendChild( elFoot
);
149 elOutputWrapper
= document
.getElementById( 'qunit-completenesstest' );
150 if ( !elOutputWrapper
) {
151 elOutputWrapper
= document
.createElement( 'div' );
152 elOutputWrapper
.id
= 'qunit-completenesstest';
154 elOutputWrapper
.appendChild( elContainer
);
156 util
.each( style
, function ( key
, value
) {
157 elOutputWrapper
.style
[key
] = value
;
159 return elOutputWrapper
;
162 if ( cntMissing
=== 0 ) {
164 testResults
= makeTestResults(
166 'Detected calls to ' + cntCalled
+ '/' + cntTotal
+ ' methods. No missing tests!',
168 backgroundColor
: '#D2E0E6',
172 paddingBottom
: '1em',
178 testResults
= makeTestResults(
180 'Detected calls to ' + cntCalled
+ '/' + cntTotal
+ ' methods. ' + cntMissing
+ ' methods not covered:',
182 backgroundColor
: '#EE5757',
186 paddingBottom
: '1em',
192 toolbar
= document
.getElementById( 'qunit-testrunner-toolbar' );
194 toolbar
.insertBefore( testResults
, toolbar
.firstChild
);
202 CompletenessTest
.ACTION_INJECT
= 500;
203 CompletenessTest
.ACTION_CHECK
= 501;
206 CompletenessTest
.fn
= CompletenessTest
.prototype = {
209 * CompletenessTest.fn.walkTheObject
211 * This function recursively walks through the given object, calling itself as it goes.
212 * Depending on the action it either injects our listener into the methods, or
213 * reads from our tracker and records which methods have not been called by the test suite.
215 * @param currName {String|Null} Name of the given object member (Initially this is null).
216 * @param currVar {mixed} The variable to check (initially an object,
217 * further down it could be anything).
218 * @param masterVariable {Object} Throughout our interation, always keep track of the master/root.
219 * Initially this is the same as currVar.
220 * @param parentPathArray {Array} Array of names that indicate our breadcrumb path starting at
221 * masterVariable. Not including currName.
222 * @param action {Number} What is this function supposed to do (ACTION_INJECT or ACTION_CHECK)
224 walkTheObject: function ( currName
, currVar
, masterVariable
, parentPathArray
, action
) {
226 var key
, value
, tmpPathArray
,
227 type
= util
.type( currVar
),
231 if ( this.ignoreFn( currVar
, that
, parentPathArray
) ) {
235 // Handle the lazy limit
237 if ( this.lazyCounter
> this.lazyLimit
) {
238 log( 'CompletenessTest.fn.walkTheObject> Limit reached: ' + this.lazyCounter
, parentPathArray
);
243 if ( type
=== 'function' ) {
245 if ( !currVar
.prototype || util
.isEmptyObject( currVar
.prototype ) ) {
247 if ( action
=== CompletenessTest
.ACTION_INJECT
) {
249 that
.injectionTracker
[ parentPathArray
.join( '.' ) ] = true;
250 that
.injectCheck( masterVariable
, parentPathArray
, function () {
251 that
.methodCallTracker
[ parentPathArray
.join( '.' ) ] = true;
255 // We don't support checking object constructors yet...
256 // ...we can check the prototypes fine, though.
258 if ( action
=== CompletenessTest
.ACTION_INJECT
) {
260 for ( key
in currVar
.prototype ) {
261 if ( hasOwn
.call( currVar
.prototype, key
) ) {
262 value
= currVar
.prototype[key
];
263 if ( key
=== 'constructor' ) {
267 // Clone and break reference to parentPathArray
268 tmpPathArray
= util
.extend( [], parentPathArray
);
269 tmpPathArray
.push( 'prototype' );
270 tmpPathArray
.push( key
);
272 that
.walkTheObject( key
, value
, masterVariable
, tmpPathArray
, action
);
281 // Recursively. After all, this is the *completeness* test
282 if ( type
=== 'function' || type
=== 'object' ) {
283 for ( key
in currVar
) {
284 if ( hasOwn
.call( currVar
, key
) ) {
285 value
= currVar
[key
];
287 // Clone and break reference to parentPathArray
288 tmpPathArray
= util
.extend( [], parentPathArray
);
289 tmpPathArray
.push( key
);
291 that
.walkTheObject( key
, value
, masterVariable
, tmpPathArray
, action
);
297 populateMissingTests: function () {
299 util
.each( ct
.injectionTracker
, function ( key
) {
305 * CompletenessTest.fn.hasTest
307 * Checks if the given method name (ie. 'my.foo.bar')
308 * was called during the test suite (as far as the tracker knows).
309 * If not it adds it to missingTests.
311 * @param fnName {String}
314 hasTest: function ( fnName
) {
315 if ( !( fnName
in this.methodCallTracker
) ) {
316 this.missingTests
[fnName
] = true;
323 * CompletenessTest.fn.injectCheck
325 * Injects a function (such as a spy that updates methodCallTracker when
326 * it's called) inside another function.
328 * @param masterVariable {Object}
329 * @param objectPathArray {Array}
330 * @param injectFn {Function}
332 injectCheck: function ( masterVariable
, objectPathArray
, injectFn
) {
333 var i
, len
, prev
, memberName
, lastMember
,
334 curr
= masterVariable
;
336 // Get the object in question through the path from the master variable,
337 // We can't pass the value directly because we need to re-define the object
338 // member and keep references to the parent object, member name and member
339 // value at all times.
340 for ( i
= 0, len
= objectPathArray
.length
; i
< len
; i
++ ) {
341 memberName
= objectPathArray
[i
];
344 curr
= prev
[memberName
];
345 lastMember
= memberName
;
348 // Objects are by reference, members (unless objects) are not.
349 prev
[lastMember
] = function () {
351 return curr
.apply( this, arguments
);
357 window
.CompletenessTest
= CompletenessTest
;