Create test helper that does deepEqual for circular references

Since the objects returned by `htmlparser2.parseDOM` have circular
references, this makes `assert.deepEqual` testing difficult.

As a result, a test helper was created to handle this issue.
`deepEqualCircular` walks through the objects and taints the
visited ones to prevent the call stack from being overwhelmed.

A unit test was also created to check that the helper logic is
consistent.

Author: remarkablemark

test/helpers.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+var assert = require('assert');
+var helpers = require('./helpers/');
+
+/**
+ * Tests for the test helpers.
+ */
+describe('test helper', function() {
+
+    describe('`deepEqualCircular`', function() {
+        var deepEqualCircular = helpers.deepEqualCircular;
+
+        it('works like `assert.deepStrictEqual`', function() {
+            var obj1;
+            var obj2;
+
+            obj1 = { foo: 'bar', baz: ['qux', 42, null], obj: {} };
+            obj2 = { obj: {}, baz: ['qux', 42, null], foo: 'bar' };
+            deepEqualCircular(obj1, obj2);
+
+            obj1 = { foo: 'bar', baz: ['qux', 42, null], obj: { ject: 'ion!' } };
+            assert.throws(function() { deepEqualCircular(obj1, obj2); });
+        });
+
+        it('does not break with circular references', function() {
+            var obj1;
+            var obj2;
+
+            var obj1 = { foo: 'bar', baz: ['qux', 42, null], obj: {} };
+            obj1.ref = obj1.obj;
+            var obj2 = { obj: {}, baz: ['qux', 42, null], foo: 'bar' };
+            obj2.ref = obj2.obj;
+            deepEqualCircular(obj1, obj2);
+        });
+
+    });
+
+});

test/helpers/index.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+var assert = require('assert');
+
+/**
+ * Test for deep equality between objects that have circular references.
+ *
+ * @param {Object} actual   - The actual object.
+ * @param {Object} expected - The expected object.
+ */
+function deepEqualCircular(actual, expected) {
+    var IS_VISITED_KEY = '_isVisited';
+
+    var actualKeys = Object.keys(actual).sort();
+    var expectedKeys = Object.keys(expected).sort();
+
+    // remove extraneous properties (if applicable)
+    var isVisitedKeyIndex = actualKeys.indexOf(IS_VISITED_KEY);
+    if (isVisitedKeyIndex > -1) {
+        actualKeys.splice(isVisitedKeyIndex, 1);
+    }
+
+    // compare object keys (sanity check)
+    assert.deepStrictEqual(actualKeys, expectedKeys);
+
+    // compare actual against expected
+    expectedKeys.forEach(function(key) {
+        var actualValue = actual[key];
+        var expectedValue = expected[key];
+
+        if (actualValue !== null && typeof actualValue === 'object') {
+            // actual and expected are not the same type
+            if (expectedValue !== null && typeof expectedValue.constructor === 'object') {
+                throw new Error(
+                    'Actual value: ' + util.inspect(actualValue) +
+                    '\n\nExpected value: ' +
+                    util.inspect(expectedValue)
+                );
+            }
+
+            // no need to revisit an already visited object
+            // this is to mitigate exceeding maximum call stack with circular reference
+            if (actualValue[IS_VISITED_KEY]) {
+                return;
+
+            // otherwise, walk through it
+            } else {
+                // taint the object to denote that it's been visited
+                actualValue[IS_VISITED_KEY] = true;
+                return deepEqualCircular(actualValue, expectedValue);
+            }
+
+        // compare the values as is
+        } else {
+            assert.deepStrictEqual(actualValue, expectedValue);
+        }
+    });
+}
+
+/**
+ * Export assert helpers.
+ */
+module.exports = {
+    deepEqualCircular: deepEqualCircular
+};