How do I extend QUnit with new assertion functions?

Question

I'd like to add new assertions to QUnit. I've done something this:

QUnit.extend(QUnit.assert, {
  increases: function(measure, block, message){
    var before = measure();
    block();
    var after = measure();
    var passes = before < after;
    QUnit.push(passes, after, "< " + before, message);
  }
});

When I use increases(foo,bar,baz) in my test, I get

ReferenceError: increases is not defined

From the browser console I can see increases is found in QUnit.assert along with all the other standard functions: ok, equal, deepEqual, etc.

From the console, running:
test("foo", function(){console.log(ok) });
I see the source of ok.

Running:
test("foo", function(){console.log(increases) });
I am told increases is not defined.

What is the magic required to use my increases in a test? Also, where (if anywhere) is the documentation for that?

Thanks

Answer 1

I have found the solution is to accept a parameter in the test callback function. That parameter will have the extra assertion type. So we can call it like so:

//the assert parameter accepted by the callback will contain the 'increases' assertion
test("adding 1 increases a number", function(assert){
    var number = 42;
    function measure(){return number;}
    function block(){number += 1;}
    assert.increases(measure, block);
});

Answer 2

I tried to add a custom assertion today and came to the same problem. Only Original assertions functions are defined also in the global object. Custom assertions are not.

From debugging QUnit code it seems the original assertions functions are placed on the global scope - the window variable - intentionally. This happens at the initialization of QUnit, so it only applies to the original assertions functions already defined at that time.

1.QUnit.js : Definition of the original assertions functions

assert = QUnit.assert = {
  ok: function( result, msg ) {

...

2.QUnit.js : Original assertions function -> QUnit.constructor.prototype

extend( QUnit.constructor.prototype, assert );

3.QUnit.js : QUnit.constructor.prototype -> window

// For browser, export only select globals
if ( typeof window !== "undefined" ) {
    extend( window, QUnit.constructor.prototype );
    window.QUnit = QUnit;
}

Solution

So as you answered, in order to use custom assertion function, one needs to:

1. Catch the assert argument that is passed to each assert function and use it. ex.

   test("test name", function(assert) {
     assert.cosutomAssertion(..); 
   ...});
   

2. Or use the full namespace to reach the assert function. ex.

   QUnit.assert.customAssertion(..)