Merge pull request #25 from astorije/astorije/issue-24

Precisions around deep equality

README.md

@@ -62,6 +62,12 @@ var b = List.of(1, 2, 3);
 expect(a).to.equal(b);
 ```
 
+Immutable data structures should only contain other immutable data
+structures (unlike `Array`s and `Object`s) to be considered immutable and
+properly work against `.equal()`. See
+[this issue](https://github.com/astorije/chai-immutable/issues/24) for
+more information.
+
 ### .include(value)
 
 - **@param** *{ Mixed }* val
@@ -149,15 +155,21 @@ expect(List.of(1, 2, 3)).to.have.sizeOf(3);
 - **@param** *{ Collection }* expected
 
 Asserts that the values of the target are equvalent to the values of
-`collection`. Note that `.strictEqual` and `.deepEqual` assert exactly like
-`.equal` in the context of Immutable data structures.
+`collection`. Note that `.strictEqual()` and `.deepEqual()` assert
+exactly like `.equal()` in the context of Immutable data structures.
 
 ```js
 var a = List.of(1, 2, 3);
 var b = List.of(1, 2, 3);
 assert.equal(a, b);
 ```
 
+Immutable data structures should only contain other immutable data
+structures (unlike `Array`s and `Object`s) to be considered immutable and
+properly work against `.equal()`, `.strictEqual()` or `.deepEqual()`. See
+[this issue](https://github.com/astorije/chai-immutable/issues/24) for
+more information.
+
 ### .sizeOf(collection, length)
 
 - **@param** *{ Collection }* collection

chai-immutable.js

@@ -74,9 +74,16 @@
      * expect(a).to.equal(b);
      * ```
      *
+     * Immutable data structures should only contain other immutable data
+     * structures (unlike `Array`s and `Object`s) to be considered immutable and
+     * properly work against `.equal()`. See
+     * [this issue](https://github.com/astorije/chai-immutable/issues/24) for
+     * more information.
+     *
      * @name equal
      * @alias equals
      * @alias eq
+     * @alias eql
      * @alias deep.equal
      * @param {Collection} value
      * @api public
@@ -101,6 +108,7 @@
     Assertion.overwriteMethod('equal', assertCollectionEqual);
     Assertion.overwriteMethod('equals', assertCollectionEqual);
     Assertion.overwriteMethod('eq', assertCollectionEqual);
+    Assertion.overwriteMethod('eql', assertCollectionEqual);
 
     /**
      * ### .include(value)
@@ -438,15 +446,21 @@
      * ### .equal(actual, expected)
      *
      * Asserts that the values of the target are equvalent to the values of
-     * `collection`. Note that `.strictEqual` and `.deepEqual` assert exactly like
-     * `.equal` in the context of Immutable data structures.
+     * `collection`. Note that `.strictEqual()` and `.deepEqual()` assert
+     * exactly like `.equal()` in the context of Immutable data structures.
      *
      * ```js
      * var a = List.of(1, 2, 3);
      * var b = List.of(1, 2, 3);
      * assert.equal(a, b);
      * ```
      *
+     * Immutable data structures should only contain other immutable data
+     * structures (unlike `Array`s and `Object`s) to be considered immutable and
+     * properly work against `.equal()`, `.strictEqual()` or `.deepEqual()`. See
+     * [this issue](https://github.com/astorije/chai-immutable/issues/24) for
+     * more information.
+     *
      * @name equal
      * @param {Collection} actual
      * @param {Collection} expected

test/test.js

@@ -20,6 +20,10 @@ var Stack = Immutable.Stack;
 
 describe('chai-immutable (' + typeEnv + ')', function () {
   var list3 = List.of(1, 2, 3);
+  var deepMap = new Map({
+    foo: 'bar',
+    list: List.of(1, 2, 3)
+  });
 
   describe('BDD interface', function () {
     describe('empty property', function () {
@@ -62,6 +66,8 @@ describe('chai-immutable (' + typeEnv + ')', function () {
         expect(list3).to.not.equals(new List());
         expect(list3).to.eq(List.of(1, 2, 3));
         expect(list3).to.not.eq(new List());
+        expect(list3).to.eql(List.of(1, 2, 3));
+        expect(list3).to.not.eql(new List());
         expect(list3).to.deep.equal(List.of(1, 2, 3));
         expect(list3).to.not.deep.equal(new List());
       });
@@ -73,6 +79,32 @@ describe('chai-immutable (' + typeEnv + ')', function () {
         expect({ foo: 'bar' }).to.not.equal({ foo: 'bar' });
         expect({ foo: 'bar' }).to.deep.equal({ foo: 'bar' });
       });
+
+      it('should work on deep structures that are equal', function () {
+        var sameDeepMap = new Map({
+          foo: 'bar',
+          list: List.of(1, 2, 3)
+        });
+
+        expect(deepMap).to.equal(sameDeepMap);
+        expect(deepMap).to.equals(sameDeepMap);
+        expect(deepMap).to.eq(sameDeepMap);
+        expect(deepMap).to.eql(sameDeepMap);
+        expect(deepMap).to.deep.equal(sameDeepMap);
+      });
+
+      it('should work on deep structures that are not equal', function () {
+        var differentDeepMap = new Map({
+          foo: 'bar',
+          list: List.of(42)
+        });
+
+        expect(deepMap).to.not.equal(differentDeepMap);
+        expect(deepMap).to.not.equals(differentDeepMap);
+        expect(deepMap).to.not.eq(differentDeepMap);
+        expect(deepMap).to.not.eql(differentDeepMap);
+        expect(deepMap).to.not.deep.equal(differentDeepMap);
+      });
     });
 
     describe('include method', function () {
@@ -347,6 +379,28 @@ describe('chai-immutable (' + typeEnv + ')', function () {
       });
     });
 
+    it('should work on deep structures that are equal', function () {
+      var sameDeepMap = new Map({
+        foo: 'bar',
+        list: List.of(1, 2, 3)
+      });
+
+      assert.equal(deepMap, sameDeepMap);
+      assert.strictEqual(deepMap, sameDeepMap);
+      assert.deepEqual(deepMap, sameDeepMap);
+    });
+
+    it('should work on deep structures that are not equal', function () {
+      var differentDeepMap = new Map({
+        foo: 'bar',
+        list: List.of(42)
+      });
+
+      assert.notEqual(deepMap, differentDeepMap);
+      assert.notStrictEqual(deepMap, differentDeepMap);
+      assert.notDeepEqual(deepMap, differentDeepMap);
+    });
+
     describe('sizeOf assertion', function () {
       it('should be true when given the right size', function () {
         assert.sizeOf(List.of(1, 2, 3), 3);