feat(matchers): Add value-in-list assertion

Adds a way to test if a value appears in a flat list. Compliments
`include.members` to reverse the order of the input. Now the list
appears in the assertion, as opposed to the `expect`.

Closes #532

Author: Droogans

lib/chai/core/assertions.js

@@ -1531,6 +1531,39 @@ module.exports = function (chai, _) {
     );
   });
 
+  /**
+   * ### .oneOf(list)
+   *
+   * Assert that a non-array, non-object value appears somewhere in the flat array `list`.
+   *
+   *     expect('a').to.be.oneOf(['a', 'b', 'c']);
+   *     expect(9).to.not.be.oneOf(['z']);
+   *
+   * @name oneOf
+   * @param {Array<*>} list
+   * @param {String} message _optional_
+   * @api public
+   */
+
+  function oneOf (list, msg) {
+    if (msg) flag(this, 'message', msg);
+    var expected = flag(this, 'object');
+    new Assertion(list).to.be.an('array');
+    new Assertion(expected).to.not.be.an('array');
+    new Assertion(expected).to.not.be.an('object');
+
+    this.assert(
+        list.indexOf(expected) > -1
+      , 'expected #{this} to be in #{exp}'
+      , 'expected #{this} to not be in #{exp}'
+      , list
+      , expected
+    );
+  }
+
+  Assertion.addMethod('oneOf', oneOf);
+
+
   /**
    * ### .change(function)
    *

lib/chai/interface/assert.js

@@ -1165,7 +1165,7 @@ module.exports = function (chai, util) {
   assert.closeTo = function (act, exp, delta, msg) {
     new Assertion(act, msg).to.be.closeTo(exp, delta);
   };
-  
+
   /**
    * ### .approximately(actual, expected, delta, [message])
    *
@@ -1242,6 +1242,24 @@ module.exports = function (chai, util) {
     new Assertion(superset, msg).to.include.members(subset);
   }
 
+  /**
+   * ### .oneOf(inList, list, [message])
+   *
+   * Asserts that non-object, non-array value `inList` appears in the flat array `list`.
+   *
+   *     assert.oneOf(1, [ 2, 1 ], 'Not found in list');
+   *
+   * @name oneOf
+   * @param {*} inList
+   * @param {Array<*>} list
+   * @param {String} message
+   * @api public
+   */
+
+  assert.oneOf = function (inList, list, msg) {
+    new Assertion(inList, msg).to.be.oneOf(list);
+  }
+
    /**
    * ### .changes(function, object, property)
    *

test/assert.js

@@ -713,7 +713,7 @@ describe('assert', function () {
       assert.closeTo(1.5, 1.0, true);
     }, "the arguments to closeTo or approximately must be numbers");
   });
-  
+
   it('approximately', function(){
     assert.approximately(1.5, 1.0, 0.5);
     assert.approximately(10, 20, 20);
@@ -768,6 +768,31 @@ describe('assert', function () {
     }, 'expected [ 1, 54 ] to have the same members as [ 6, 1, 54 ]');
   });
 
+  it('oneOf', function() {
+    assert.oneOf(1, [1, 2, 3]);
+
+    err(function() {
+      assert.oneOf([1], []);
+    }, 'expected [ 1 ] not to be an array');
+
+    err(function() {
+      assert.oneOf({a: 1}, []);
+    }, 'expected { a: 1 } not to be an object');
+
+    err(function() {
+      assert.oneOf(1, 1);
+    }, 'expected 1 to be an array');
+
+    err(function() {
+      assert.oneOf(1, {a: 1});
+    }, 'expected { a: 1 } to be an array');
+
+    err(function() {
+      assert.oneOf(9, [1, 2, 3], 'Message');
+    }, 'Message: expected 9 to be in [ 1, 2, 3 ]');
+
+  });
+
   it('above', function() {
     assert.isAbove(5, 2, '5 should be above 2');
 

test/expect.js

@@ -1052,7 +1052,7 @@ describe('expect', function () {
       expect(1.5).to.be.closeTo(1.0, true);
     }, "the arguments to closeTo or approximately must be numbers");
   });
-  
+
   it('approximately', function(){
     expect(1.5).to.be.approximately(1.0, 0.5);
     expect(10).to.be.approximately(20, 20);
@@ -1079,6 +1079,11 @@ describe('expect', function () {
     }, "the arguments to closeTo or approximately must be numbers");
   });
 
+  it('oneOf', function() {
+    expect(1).to.be.oneOf([1, 2, 3]);
+    expect('1').to.not.be.oneOf([1, 2, 3]);
+  });
+
   it('include.members', function() {
     expect([1, 2, 3]).to.include.members([]);
     expect([1, 2, 3]).to.include.members([3, 2]);

test/should.js

@@ -457,6 +457,13 @@ describe('should', function() {
     }, "blah: expected 'foobar' to not contain 'bar'");
   });
 
+  it('oneOf()', function(){
+    'foo'.should.be.oneOf(['foo', 'bar']);
+    'bar'.should.be.oneOf(['foo', 'bar']);
+    'baz'.should.not.be.oneOf(['foo', 'bar']);
+    'baz'.should.not.be.oneOf([]);
+  });
+
   it('include()', function(){
     ['foo', 'bar'].should.include('foo');
     ['foo', 'bar'].should.contain('foo');
@@ -881,7 +888,7 @@ describe('should', function() {
       (1.5).should.be.closeTo(1.0, true);
     }, "the arguments to closeTo or approximately must be numbers");
   });
-  
+
   it('approximately', function(){
     (1.5).should.be.approximately(1.0, 0.5);