Merge pull request #73 from cjihrig/master

change default comparison behavior

Author: hueniverse

API.md

@@ -88,19 +88,18 @@ expect(6).to.be.in.range(5, 6);
 ### Flags
 
 The following words toggle a status flag for the current assertion:
-- `deep` - performs a deep comparison instead of simple equality (`===`). Required when trying to compare
-  objects to an identical copy that is not the same reference. Used by `equal()` and `include()`.
 - `not` - inverses the expected result of any assertion.
 - `once` - requires that inclusion matches appear only once in the provided value. Used by `include()`.
 - `only` - requires that only the provided elements appear in the provided value. Used by `include()`.
 - `part` - allows a partial match when asserting inclusion. Used by `include()`.
+- `shallow` - performs a comparison using strict equality (`===`). Code defaults to deep comparison. Used by `equal()` and `include()`.
 
 ```js
 const Code = require('code');
 const expect = Code.expect;
 
 expect(10).to.not.be.above(20);
-expect([{ a: 1 }]).to.deep.include({ a: 1 });
+expect([1, 2, 3]).to.shallow.include(3);
 expect([1, 1, 2]).to.only.include([1, 2]);
 expect([1, 2]).to.once.include([1, 2]);
 expect([1, 2, 3]).to.part.include([1, 4]);
@@ -256,7 +255,7 @@ expect({ a: '1' }).to.be.an.object();
 
 #### Values
 
-Asserts that the reference value is equals to a predefined value.
+Asserts that the reference value is equal to a predefined value.
 
 ##### `true()`
 
@@ -308,8 +307,7 @@ Aliases: `includes()`, `contain()`, `contains()`
 
 Asserts that the reference value (a string, array, or object) includes the provided values where:
 - `values` - a single or array of values. If the reference value is a string, the values must be strings.
-  If the reference value is an array, the values can be any array member (`deep` is required to compare
-  non-literal types). If the reference value is an object, the values can be key names, or a single object
+  If the reference value is an array, the values can be any array member. If the reference value is an object, the values can be key names, or a single object
   with key-value pairs to match.
 
 ```js
@@ -324,13 +322,13 @@ expect('abc').to.include(['a', 'c']);
 expect('abc').to.part.include(['a', 'd']);
 
 expect([1, 2, 3]).to.include(1);
-expect([{ a: 1 }]).to.deep.include({ a: 1 });
+expect([{ a: 1 }]).to.include({ a: 1 });
 expect([1, 2, 3]).to.include([1, 2]);
-expect([{ a: 1 }]).to.deep.include([{ a: 1 }]);
+expect([{ a: 1 }]).to.include([{ a: 1 }]);
 expect([1, 1, 2]).to.only.include([1, 2]);
 expect([1, 2]).to.once.include([1, 2]);
 expect([1, 2, 3]).to.part.include([1, 4]);
-expect([[1], [2]]).to.deep.include([[1]]);
+expect([[1], [2]]).to.include([[1]]);
 
 expect({ a: 1, b: 2, c: 3 }).to.include('a');
 expect({ a: 1, b: 2, c: 3 }).to.include(['a', 'c']);
@@ -339,7 +337,7 @@ expect({ a: 1, b: 2, c: 3 }).to.include({ a: 1 });
 expect({ a: 1, b: 2, c: 3 }).to.include({ a: 1, c: 3 });
 expect({ a: 1, b: 2, c: 3 }).to.part.include({ a: 1, d: 4 });
 expect({ a: 1, b: 2, c: 3 }).to.only.include({ a: 1, b: 2, c: 3 });
-expect({ a: [1], b: [2], c: [3] }).to.deep.include({ a: [1], c: [3] });
+expect({ a: [1], b: [2], c: [3] }).to.include({ a: [1], c: [3] });
 ```
 
 #### `startWith(value)`
@@ -417,21 +415,19 @@ expect('abcd').to.have.length(4);
 
 Aliases: `equals()`
 
-Asserts that the reference value equals the provided value (`deep` is required to compare non-literal
-types) where:
+Asserts that the reference value equals the provided value where:
 - `value` - the value to compare to.
-- `options` - optional object specifying comparison options. This is only used on
-deep comparisons, and is ignored otherwise.
+- `options` - optional object specifying comparison options. This is ignored on `shallow` comparisons.
 
 ```js
 const Code = require('code');
 const expect = Code.expect;
 
 expect(5).to.equal(5);
-expect({ a: 1 }).to.deep.equal({ a: 1 });
+expect({ a: 1 }).to.equal({ a: 1 });
 ```
 
-Deep comparisons are performed using
+Deep comparisons (the default) are performed using
 [`Hoek.deepEqual()`](https://github.com/hapijs/hoek/blob/master/API.md#deepequalb-a-options). The
 optional `options` argument is passed directly to `Hoek.deepEqual()`. An example
 deep comparison which ignores object prototypes is shown below.
@@ -440,7 +436,17 @@ deep comparison which ignores object prototypes is shown below.
 const Code = require('code');
 const expect = Code.expect;
 
-expect(Object.create(null)).to.deep.equal({}, { prototype: false });
+expect(Object.create(null)).to.equal({}, { prototype: false });
+```
+
+Strict equality can be checked using the `shallow` modifier. This yields the same output as a `===` check.
+
+```js
+const Code = require('code');
+const expect = Code.expect;
+
+expect(5).to.shallow.equal(5);
+expect({ a: 1 }).to.shallow.equal({ a: 1 }); // fails as they are not the same reference
 ```
 
 #### `above(value)`
@@ -680,18 +686,21 @@ const expect = Code.expect;
 const foo = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
 
 Code.settings.truncateMessages = false;
-expect(foo).to.deep.equal([]);
+expect(foo).to.equal([]);
 ```
 
 #### `comparePrototypes`
 
-A boolean value that, when `false`, ignores object prototypes when doing a deep comparison. Defaults to `true`.
+A Boolean value that, when `false`, ignores object prototypes when doing a deep comparison. Defaults to `false`.
 
 ```js
 const Code = require('code');
 const expect = Code.expect;
 const foo = Object.create(null);
 
-Code.setting.comparePrototypes = false;
-expect(foo).to.deep.equal({});
+Code.settings.comparePrototypes = false;
+expect(foo).to.equal({});
+
+Code.settings.comparePrototypes = true;
+expect(foo).to.equal({}); // fails
 ```

lib/index.js

@@ -9,7 +9,7 @@ const Hoek = require('hoek');
 // Declare internals
 
 const internals = {
-    flags: ['deep', 'not', 'once', 'only', 'part'],
+    flags: ['not', 'once', 'only', 'part', 'shallow'],
     grammar: ['a', 'an', 'and', 'at', 'be', 'have', 'in', 'to'],
     locations: {},
     count: 0
@@ -18,7 +18,7 @@ const internals = {
 
 exports.settings = {
     truncateMessages: false,
-    comparePrototypes: true
+    comparePrototypes: false
 };
 
 
@@ -197,6 +197,7 @@ internals.addMethod('error', function (/*type, message*/) {
 
 internals.include = function (value) {
 
+    this._flags.deep = !this._flags.shallow;
     return this.assert(Hoek.contain(this._ref, value, this._flags), 'include ' + internals.display(value));
 };
 
@@ -260,8 +261,8 @@ internals.equal = function (value, options) {
     options = options || {};
     const settings = Hoek.applyToDefaults({ prototype: exports.settings.comparePrototypes }, options);
 
-    const compare = this._flags.deep ? (a, b) => Hoek.deepEqual(a, b, settings)
-                                     : (a, b) => a === b;
+    const compare = this._flags.shallow ? (a, b) => a === b
+                                        : (a, b) => Hoek.deepEqual(a, b, settings);
 
     return this.assert(compare(this._ref, value), 'equal specified value', this._ref, value);
 };

test/index.js

@@ -320,17 +320,30 @@ describe('expect()', () => {
         try {
 
             const obj = Object.create(null);
-            Code.expect({}).to.deep.equal(obj);
+            Code.expect({}).to.equal(obj);
             obj.foo = 'bar';
-            Code.expect({ foo: 'bar' }).to.deep.equal(obj);
-            Code.expect({ foo: 'bar' }).to.deep.equal({ foo: 'bar' });
+            Code.expect({ foo: 'bar' }).to.equal(obj);
+            Code.expect({ foo: 'bar' }).to.equal({ foo: 'bar' });
         }
         catch (err) {
             exception = err;
         }
 
         Code.settings.comparePrototypes = origPrototype;
         Hoek.assert(!exception, exception);
+        Code.settings.comparePrototypes = true;
+
+        try {
+
+            const obj = Object.create(null);
+            Code.expect({}).to.equal(obj);
+        }
+        catch (err) {
+            exception = err;
+        }
+
+        Code.settings.comparePrototypes = origPrototype;
+        Hoek.assert(exception.message === 'Expected {} to equal specified value', exception);
         done();
     });
 
@@ -985,11 +998,17 @@ describe('expect()', () => {
                 let exception = false;
                 try {
                     Code.expect('abc').to.include('ab');
+                    Code.expect('abc').to.shallow.include('ab');
                     Code.expect('abc').to.only.include('abc');
+                    Code.expect('abc').to.only.shallow.include('abc');
                     Code.expect('aaa').to.only.include('a');
+                    Code.expect('aaa').to.only.shallow.include('a');
                     Code.expect('abc').to.once.include('b');
+                    Code.expect('abc').to.once.shallow.include('b');
                     Code.expect('abc').to.include(['a', 'c']);
+                    Code.expect('abc').to.shallow.include(['a', 'c']);
                     Code.expect('abc').to.part.include(['a', 'd']);
+                    Code.expect('abc').to.part.shallow.include(['a', 'd']);
                 }
                 catch (err) {
                     exception = err;
@@ -1004,13 +1023,14 @@ describe('expect()', () => {
                 let exception = false;
                 try {
                     Code.expect([1, 2, 3]).to.include(1);
-                    Code.expect([{ a: 1 }]).to.deep.include({ a: 1 });
+                    Code.expect([1, 2, 3]).to.shallow.include(1);
+                    Code.expect([{ a: 1 }]).to.include({ a: 1 });
                     Code.expect([1, 2, 3]).to.include([1, 2]);
-                    Code.expect([{ a: 1 }]).to.deep.include([{ a: 1 }]);
+                    Code.expect([{ a: 1 }]).to.include([{ a: 1 }]);
                     Code.expect([1, 1, 2]).to.only.include([1, 2]);
                     Code.expect([1, 2]).to.once.include([1, 2]);
                     Code.expect([1, 2, 3]).to.part.include([1, 4]);
-                    Code.expect([[1], [2]]).to.deep.include([[1]]);
+                    Code.expect([[1], [2]]).to.include([[1]]);
                 }
                 catch (err) {
                     exception = err;
@@ -1020,18 +1040,33 @@ describe('expect()', () => {
                 done();
             });
 
+            it('invalidates arrays (shallow)', (done) => {
+
+                let exception = false;
+                try {
+                    Code.expect([{ a: 1 }]).to.shallow.include({ a: 1 });
+                }
+                catch (err) {
+                    exception = err;
+                }
+
+                Hoek.assert(exception.message === 'Expected [ { a: 1 } ] to include { a: 1 }', exception);
+                done();
+            });
+
             it('validates objects', (done) => {
 
                 let exception = false;
                 try {
                     Code.expect({ a: 1, b: 2, c: 3 }).to.include('a');
+                    Code.expect({ a: 1, b: 2, c: 3 }).to.shallow.include('a');
                     Code.expect({ a: 1, b: 2, c: 3 }).to.include(['a', 'c']);
                     Code.expect({ a: 1, b: 2, c: 3 }).to.only.include(['a', 'b', 'c']);
                     Code.expect({ a: 1, b: 2, c: 3 }).to.include({ a: 1 });
                     Code.expect({ a: 1, b: 2, c: 3 }).to.include({ a: 1, c: 3 });
                     Code.expect({ a: 1, b: 2, c: 3 }).to.part.include({ a: 1, d: 4 });
                     Code.expect({ a: 1, b: 2, c: 3 }).to.only.include({ a: 1, b: 2, c: 3 });
-                    Code.expect({ a: [1], b: [2], c: [3] }).to.deep.include({ a: [1], c: [3] });
+                    Code.expect({ a: [1], b: [2], c: [3] }).to.include({ a: [1], c: [3] });
                 }
                 catch (err) {
                     exception = err;
@@ -1041,6 +1076,20 @@ describe('expect()', () => {
                 done();
             });
 
+            it('invalidates objects (shallow)', (done) => {
+
+                let exception = false;
+                try {
+                    Code.expect({ a: [1] }).to.shallow.include({ a: [1] });
+                }
+                catch (err) {
+                    exception = err;
+                }
+
+                Hoek.assert(exception.message === 'Expected { a: [ 1 ] } to include { a: [ 1 ] }', exception);
+                done();
+            });
+
             it('validates aliases', (done) => {
 
                 let exception = false;
@@ -1386,6 +1435,13 @@ describe('expect()', () => {
                 let exception = false;
                 try {
                     Code.expect('abc').to.equal('abc');
+                    Code.expect(['abc']).to.equal(['abc']);
+                    Code.expect({ a: 1 }).to.equal({ a: 1 });
+                    Code.expect({}).to.not.equal({ a: 1 });
+                    Code.expect({ a: 1 }).to.not.equal({});
+                    Code.expect(Object.create(null)).to.not.equal({}, { prototype: true });
+                    Code.expect(Object.create(null)).to.equal({}, { prototype: false });
+                    Code.expect(Object.create(null)).to.equal({});
                 }
                 catch (err) {
                     exception = err;
@@ -1409,16 +1465,29 @@ describe('expect()', () => {
                 done();
             });
 
-            it('validates assertion (deep)', (done) => {
+            it('invalidates assertion', (done) => {
 
                 let exception = false;
                 try {
-                    Code.expect(['abc']).to.deep.equal(['abc']);
-                    Code.expect({ a: 1 }).to.deep.equal({ a: 1 });
-                    Code.expect({}).to.not.deep.equal({ a: 1 });
-                    Code.expect({ a: 1 }).to.not.deep.equal({});
-                    Code.expect(Object.create(null)).to.not.deep.equal({});
-                    Code.expect(Object.create(null)).to.deep.equal({}, { prototype: false });
+                    Code.expect({ foo: 1 }).to.equal({ foo: 2 });
+                }
+                catch (err) {
+                    exception = err;
+                }
+
+                Hoek.assert(exception.message === 'Expected { foo: 1 } to equal specified value', exception);
+                done();
+            });
+
+            it('validates assertion (shallow)', (done) => {
+
+                let exception = false;
+                try {
+                    const foo = { bar: 'baz' };
+
+                    Code.expect('a').to.shallow.equal('a');
+                    Code.expect(1).to.shallow.equal(1);
+                    Code.expect(foo).to.shallow.equal(foo);
                 }
                 catch (err) {
                     exception = err;
@@ -1428,11 +1497,11 @@ describe('expect()', () => {
                 done();
             });
 
-            it('invalidates assertion', (done) => {
+            it('invalidates assertion (shallow)', (done) => {
 
                 let exception = false;
                 try {
-                    Code.expect(['a']).to.equal(['a']);
+                    Code.expect(['a']).to.shallow.equal(['a']);
                 }
                 catch (err) {
                     exception = err;