Testing For Equality In JavaScript

Posted on october 20th, 2008

This article is about the function that drives the same test assertion in the QUnit JavaScript test framework. The function is called equiv and it has been created for test suites purposes. It is mostly useful for JavaScript tests but it can be also very useful in other circumstances because it is very powerful.

Hope this place can be a resource and a platform for improovement of such code. May it be for the manner it should be used in QUnit also. This article, the examples and the code on that page will evolve with time as equiv change and gets better. Help is welcome.

What does equiv do?

It compares two ore more values together and returns true when they are all equivalent, false otherwise. It is able to work on any JavaScript types, even when they are compared together, without returning unexpected results. It knows how to deals with specific bugs, or call it deficiencies in the language implementation. Of course it traverses recursive structure, it knows how to deal with references and it tries to be the more efficient and performant as possible. It's free, well documented and well tested. You'll find everything in the download page.

About equiv

equiv is the service function behind the QUnit same assertion API. It has been implemented to behave the most naturally possible about comparing "things" together.

About it's name

"equiv" is short for "equivalent". I don't think it should be call "equals" if we want to be precise for the following reasons.

• It goes beyond object references and compare content by inspecting them.
• Closures makes that some content is lock forever and not accessible, so it is impossible to know at which point objects are really equals.
• Because functions can be values (e.g. anonymous function) and there is no way to compare them but by their references.

Input Supported

undefined null NaN Infinity -Infinity Boolean Number String Date RegExp Array Object Function*
* With some limitations.

How does it deals with functions?

Earlier version of equiv were skipping function. Now it does both skipping and aborting following some rules.

Same references will always be considered equals whatever happens (naturally).

// EQUIVALENCE
function a() {}
var b = a;
equiv(a, b); // => true, same references

// EQUIVALENCE
function outerScope (x) { return x; }
var o3 = {
    fn: outerScope
};
var o4 = {
    fn: outerScope
};
equiv(o3, o4); // => true, same function references, within the same scope.
               // This is a real world example.

Abort when in an object literal*. Abort when not a property value.

*instances of the Object constructor.

// NOT A PROPERTY VALUE: ABORT
equiv(function () {}, function() {}); // => false, anonymous function have
                                      // unique references and then they are different


// IN AN OBJECT LITERAL: ABORT
var o1 = {
    fn: function (x) { return x; }
    /*, more properties ... */
};
var o2 = {
    fn: function (x) { return x; } 
    /*, more properties ... */
};
equiv(o1, o2); // => false, again anonymous functions, but in an object literal.
               // It isn't a real world example. Not a good practice anyway.
               // So we should not be penalize by this behavior.

Skip functions that are instances of any contructor but the Object constructor.

// AN INSTANCE NOT FROM Object: SKIP
function A() {
    this.fn = function () {};
} 
var a1 = new A(); 
var a2 = new A(); 
equiv(a1, a2); // => true, otherwise it won't be possible to compare instances
               //    because of that true statement: a1.fn !== a2.fn

The rules does apply in recursive structure and behave as expected.

Language deficiencies and traps to be aware of

// Consider those problems. All statements return true.

// typeof operator
typeof {} === "object";
typeof [] === "object"; // Oops! It isn't "array"
typeof function(){} === "function";
typeof "myString" === "string";
typeof 5 === "number";
typeof true === "boolean";
typeof null === "object"; // Oops! It isn't null
typeof undefined === "undefined";


// Date
var d1 = new Date();
var d2 = new Date();
d1.setMilliseconds(0);
d2.setMilliseconds(0);
d1.valueOf() === d2.valueOf();  // Yes they are the same date
d1 !== d2;                      // Oops!


// RegExp
var a = /./;
a instanceof Object;        // Oops
a instanceof RegExp;
typeof a === "function";    // Oops, false in IE and Opera, true in FF and Safari ("object")


// object literal
var o1 = {};
var o2 = {
    foo: undefined
};
o1["foo"] === o2["foo"]; // Oops!


// Number
1/0 !== 1/0; // Oops! NaN doesn't equals itself!
             // Well it may be ok, or not, it still confusing


// == operator
"1" == true; // Oops! use === not ==


// === operator
new Number(4) !== 4;         // Oops!
new String('foo') !== 'foo'; // Oops!
new Boolean(true) !== true;  // Oops! ...
                             // Must use the == operator or valueOf() instead
                             // being careful about comparing same type together

Avoiding Unexpected Results

Because testing is something serious, you cannot assume anything about the code you are testing right? Not even that a function that return a boolean will always return a boolean. What if you have you missed somewhere the return statement? What if your all your tests passed when your function return undefined instead?. It would be a bad thing.

In JavaScript particularly you have to be very careful when comparing "things" together because there is some traps that you could easily fall in (see above). Just as an example comparing {} with [] is not quite simple. A lot of code that you may find comparing objects and/or arrays could failed this one.

Let's see how the code of a function that expect only objects* could be error prone:
*By objects I mean the object reprented by the literal {} and key: value pairs.

// Don't use that code!
function equal(a, b) {
    return a === b || a && b &&
        typeof a == 'object' && typeof b == 'object' &&
        equalObjects( a, b );
}

function equalObjects(a, b) {
    var k;
    for(k in a) {
            if(!equal(a[k],b[k]))
                return false;
    }
    for(k in b) {
            if(!equal(a[k],b[k]))
                return false;
    }
    return true;
}

equalObjects(null, {}); // => mistakenly true
equalObjects([], {});   // => mistakenly true

// Extending the array's prototype makes the iteration over
// the empty array property (e.g. foobar) to differ from the
// empty object properties which doesn't exists.
Array.prototype.foobar = function(){};
equalObjects([], {});   // => now correctly false

equalObjects(1, 2);     // => mistakenly true
equalObjects(true, false); // => mistakenly true

The problem for the first 2 tests (line #21, #22) is that none of null, {} or [] doesn't have any properties, so they are considered equal because no difference were found when comparing them. Same for comparing number (line #30) or boolean (line #31) which each doesn't have any properties. Comparing strings though behave correctly because strings can be accessed with the subscript notation of it's index (e.g. as an array).

But extending the array's prototype(line #27) with a dummy function "foobar" was enough to make [] differs from {} because the object's prototype didn't hold the "foobar" property.

The code above is just bad for testing suites purposes because it can't deals with unexpected type values which is unacceptable for a test framework.

QUnit assertions deprecation warning

ok is expecting a JavaScript truthy value or expression. It's quite simple and it gives enough flexibility. It isn't error prone unless it is used by someone who doesn't understand well truthy VS falsy JavaScript expression e.g. it would behave differently for "" and [], for 1 and 0. It has the disadvantage not to be precise and though makes the tests less efficient. You have to know what you are doing.

equals compares booleans numbers and strings together. Unfortunately it isn't strict on type checking. It is error prone if you pass unexpected types as arguments.

// Unexpected type values lead to unexpected results because
// equals does not use the '===' operator to compare values.
equals(false, 0);   // => true, test passed
equals(1, "1");     // => true, test passed
equals([], 0);      // => true, test passed
equals(null, undefined); // => true, test passed

Assumptions is error prone

In my opinion, assuming certains type of values when writing test suites isn't the way to ensures robust tests. Sometimes some application's functions can return different type of data depending on the input. Or sometimes, a return statement may have been omitted, leaving the default return value to undefined. This is where equals fails when comparing null with undefined, returning true instead of false.

same can replace ok, equals and all other QUnit test assertions

same (based on equiv) being more precise than any other precedent QUnit assertions can be use to replace them. ok being different, should be use if you know what you are doing and you don't need precision when expecting truthy expressions. For the reasons I've already mentioned, those assertions should be deprecated: equals, compare(already deprecated), compare2(already deprecated), isSet and isObject.

The code

hoozit.js: needed to determine the type of a value

// Determine what is o.
function hoozit(o) {
    if (o.constructor === String) {
        return "string";

    } else if (o.constructor === Boolean) {
        return "boolean";

    } else if (o.constructor === Number) {

        if (isNaN(o)) {
            return "nan";
        } else {
            return "number";
        }

    } else if (typeof o === "undefined") {
        return "undefined";

    // consider: typeof null === object
    } else if (o === null) {
        return "null";

    // consider: typeof [] === object
    } else if (o instanceof Array) {
        return "array";

    // consider: typeof new Date() === object
    } else if (o instanceof Date) {
        return "date";

    // consider: /./ instanceof Object;
    //           /./ instanceof RegExp;
    //          typeof /./ === "function"; // => false in IE and Opera,
    //                                          true in FF and Safari
    } else if (o instanceof RegExp) {
        return "regexp";

    } else if (typeof o === "object") {
        return "object";

    } else if (o instanceof Function) {
        return "function";
    } else {
        return undefined;
    }
}

// Call the o related callback with the given arguments.
function bindCallbacks(o, callbacks, args) {
    var prop = hoozit(o);
    if (prop) {
        if (hoozit(callbacks[prop]) === "function") {
            return callbacks[prop].apply(callbacks, args);
        } else {
            return callbacks[prop]; // or undefined
        }
    }
}

equiv.js

About arguments

• when < 2 : return true. There is nothing to compare with.
• when 2 : return true if 1st is equivalent to 2nd
• when > 2 : return true if
  • 1st is equivalent to 2nd and ...
  • 2nd is equivalent to 3rd and ...
  • 3rd is equivalent to 4th ... and so on.

// Test for equality any JavaScript type.
// Discussions and reference: http://philrathe.com/articles/equiv
// Test suites: http://philrathe.com/tests/equiv
// Author: Philippe Rathé <prathe@gmail.com>

var equiv = function () {

    var innerEquiv; // the real equiv function
    var callers = []; // stack to decide between skip/abort functions


    var callbacks = function () {

        // for string, boolean, number and null
        function useStrictEquality(b, a) {
            if (b instanceof a.constructor || a instanceof b.constructor) {
                // to catch short annotaion VS 'new' annotation of a declaration
                // e.g. var i = 1;
                //      var j = new Number(1);
                return a == b;
            } else {
                return a === b;
            }
        }

        return {
            "string": useStrictEquality,
            "boolean": useStrictEquality,
            "number": useStrictEquality,
            "null": useStrictEquality,
            "undefined": useStrictEquality,

            "nan": function (b) {
                return isNaN(b);
            },

            "date": function (b, a) {
                return hoozit(b) === "date" && a.valueOf() === b.valueOf();
            },

            "regexp": function (b, a) {
                return hoozit(b) === "regexp" &&
                    a.source === b.source && // the regex itself
                    a.global === b.global && // and its modifers (gmi) ...
                    a.ignoreCase === b.ignoreCase &&
                    a.multiline === b.multiline;
            },

            // - skip when the property is a method of an instance (OOP)
            // - abort otherwise,
            //   initial === would have catch identical references anyway
            "function": function () {
                var caller = callers[callers.length - 1];
                return caller !== Object &&
                        typeof caller !== "undefined";
            },

            "array": function (b, a) {
                var i;
                var len;

                // b could be an object literal here
                if ( ! (hoozit(b) === "array")) {
                    return false;
                }

                len = a.length;
                if (len !== b.length) { // safe and faster
                    return false;
                }
                for (i = 0; i < len; i++) {
                    if( ! innerEquiv(a[i], b[i])) {
                        return false;
                    }
                }
                return true;
            },

            "object": function (b, a) {
                var i;
                var eq = true; // unless we can proove it
                var aProperties = [], bProperties = []; // collection of strings

                // comparing constructors is more strict than using instanceof
                if ( a.constructor !== b.constructor) {
                    return false;
                }

                // stack constructor before traversing properties
                callers.push(a.constructor);

                for (i in a) { // be strict: don't ensures hasOwnProperty and go deep

                    aProperties.push(i); // collect a's properties

                    if ( ! innerEquiv(a[i], b[i])) {
                        eq = false;
                    }
                }

                callers.pop(); // unstack, we are done

                for (i in b) {
                    bProperties.push(i); // collect b's properties
                }

                // Ensures identical properties name
                return eq && innerEquiv(aProperties.sort(), bProperties.sort());
            }
        };
    }();

    innerEquiv = function () { // can take multiple arguments
        var args = Array.prototype.slice.apply(arguments);
        if (args.length < 2) {
            return true; // end transition
        }

        return (function (a, b) {
            if (a === b) {
                return true; // catch the most you can
            } else if (a === null || b === null || typeof a === "undefined" || typeof b === "undefined" || hoozit(a) !== hoozit(b)) {
                return false; // don't lose time with error prone cases
            } else {
                return bindCallbacks(a, callbacks, [b, a]);
            }

        // apply transition with (1..n) arguments
        })(args[0], args[1]) && arguments.callee.apply(this, args.splice(1, args.length -1));
    };

    return innerEquiv;

}();

Open up the testrunner in a new page. Visit the download page.

Examples of use

Most common use

// compare anything together without unexpected results
var a = {a: undefined, b: null, c: {}, d: [[1,2, [3, {a: 0}]]], e: b};
var b = {a: undefined, b: null, c: {}, d: [[1,2, [3, {a: 0}]]], e: b};
var z = {a: undefined, b: null, c: {}, d: [[1,2, [3, {a: 1}]]], e: b};

// with 2 arguments
equiv(a, b);    // => true
equiv(a, z);    // => false
equiv({}, {});  // => true
equiv({}, []);  // => false
equiv({}, null);    // => false
equiv(false, 0);    // => false

// with multiple arguments
equiv(a, b, a, b, b);    // => true
equiv(true, true, true, false, true); // => false
equiv(a, b, z, a, b);    // => false

Multiple arguments: using apply and the array argument

// Useful when you don't know about the number of
// arguments that will be passed

// Generates an array of a sequence of numbers to power 0
function genPowerZero(from, to) {
    var results = [];
    for (var i = to; i >= from; i--) {
        results.push(Math.pow(i, 0));
    }
    return results;
}

// Generates an array of a sequence of numbers divided by 0
function genDivisionByZero(from, to) {
    var results = [];
    for (var i = to; i >= from; i--) {
        results.push((i / 0));
    }
    return results;
}


// Compare many strings
equiv.apply(this, ["many strings", "many strings", "many strings", "many strings"]); // => true

// All number from 1 to 100 power 0 equals 1
equiv.apply(this, genPowerZero(1,100)); // => true

// All number from 1 to 10 divided by 0 equals infinity
equiv.apply(this, genDivisionByZero(1,10)); // => true

// All number from 0 to 10 divided by 0 equals infinity
equiv.apply(this, genDivisionByZero(0,10)); // => false for 0/0 (NaN)

Multiple arguments: QUnit integration

For now same only allows the comparison of 2 arguments. It would be nice if we could use multiple arguments. Because of the last optional message argument of same, it isn't possible. But another assertion should support it. It could be call "allSame".

Add allSame to the testrunner

// allSame public method inclusion in QUnit
$.extend(window, {

// ...

allSame: function(a, message) {
    // there is no a and b argument,
    // instead a list of arguments to test 2 by 2
    if (a instanceof Array) {
        push(equiv.apply(undefined, a), a, message);
    } else {
        throw "allSame 1st argument must be an array";
    }
},

// ...

or download testrunner.js using allSame

allSame examples of use

test("allSame.", function() {
    
    // Generates an array of a sequence of numbers divided by 0
    function genDivisionByZero(from, to) {
        var results = [];
        for (var i = to; i >= from; i--) {
            results.push((i / 0));
        }
        return results;
    }

    allSame(genDivisionByZero(1,10), "All number from 1 to 10 divided by 0 equals infinity"); // pass
    allSame([true, true, true, true, false, true]); // fail
    allSame([1/0, 2/0, 3/0], "All Infinity number operations"); // pass
});

Improvements

Do you consider that having a negative version of same and allSame could be useful?

If you feel like equiv could be better share your ideas or solutions in the comments form.

You will find in the download page, the sources, the test suites, and the QUnit test runner source (including allSame).

Updated on october 30th, 2008