Mirrors/chai
2
0
Fork 0
mirror of https://github.com/chaijs/chai synced 2024-11-15 08:17:14 +00:00
Code Issues Projects Releases Packages Wiki Activity

comments / docs updates

Browse source
This commit is contained in:
Jake Luer 2012-05-14 20:32:53 -04:00
parent 03c4a0cb14
commit 9c63add86e
1 changed files with 103 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

157
lib/assertion.js
View file

@ -151,6 +151,11 @@ Object.defineProperty(Assertion.prototype, '_obj',
* *
* Negates any of assertions following in the chain. * Negates any of assertions following in the chain.
* *
* expect(foo).to.not.equal('bar');
* expect(goodFn).to.not.throw(Error);
* expect({ foo: 'baz' }).to.have.property('foo')
* .and.not.equal('bar');
*
* @name not * @name not
* @api public * @api public
*/ */
@ -166,10 +171,16 @@ Object.defineProperty(Assertion.prototype, 'not',
/** /**
* ### .a(type) * ### .a(type)
* *
* Assert typeof. Also can be used as a language chain. * The `a` and `an` assertions are aliases that can be
* used either as property languague chains or to assert
* typeof.
* *
* expect('test').to.be.a('string'); * // typeof
* expect(foo).to.be.an.instanceof(Foo); * expect('test').to.be.a('string');
* expect({ foo: 'bar' }).to.be.an('object');
*
* // language chain
* expect(foo).to.be.an.instanceof(Foo);
* *
* @name a * @name a
* @alias an * @alias an
@ -210,8 +221,10 @@ Object.defineProperty(Assertion.prototype, 'a',
/** /**
* ### .include(value) * ### .include(value)
* *
* Assert the inclusion of an object in an Array or substring in string. * The `include` and `contain` assertions can be used as either a property
* Also toggles the `contain` flag for the `keys` assertion if used as property. * based language chain or as a method to assert the inclusion of an object
* in an Array or substring in string. When used as a property langugae chain,
* it toggles the `contain` flag for the `keys` assertion.
* *
* expect([1,2,3]).to.include(2); * expect([1,2,3]).to.include(2);
* expect('foobar').to.contain('foo'); * expect('foobar').to.contain('foo');
@ -255,10 +268,11 @@ Object.defineProperty(Assertion.prototype, 'include',
* *
* Assert object truthiness. * Assert object truthiness.
* *
* expect('everthing').to.be.ok; * expect('everthing').to.be.ok;
* expect(false).to.not.be.ok; * expect(1).to.be.ok;
* expect(undefined).to.not.be.ok; * expect(false).to.not.be.ok;
* expect(null).to.not.be.ok; * expect(undefined).to.not.be.ok;
* expect(null).to.not.be.ok;
* *
* @name ok * @name ok
* @api public * @api public
@ -281,6 +295,9 @@ Object.defineProperty(Assertion.prototype, 'ok',
* *
* Assert object is true * Assert object is true
* *
* expect(true).to.be.true;
* expect(1).to.not.be.true;
*
* @name true * @name true
* @api public * @api public
*/ */
@ -304,6 +321,9 @@ Object.defineProperty(Assertion.prototype, 'true',
* *
* Assert object is false * Assert object is false
* *
* expect(false).to.be.false;
* expect(0).to.not.be.false;
*
* @name false * @name false
* @api public * @api public
*/ */
@ -327,6 +347,9 @@ Object.defineProperty(Assertion.prototype, 'false',
* *
* Assert object is null * Assert object is null
* *
* expect(null).to.be.null;
* expect(undefined).not.to.be.null;
*
* @name null * @name null
* @api public * @api public
*/ */
@ -350,6 +373,9 @@ Object.defineProperty(Assertion.prototype, 'null',
* *
* Assert object is undefined * Assert object is undefined
* *
* expect(undefined).to.be.undefined;
* expect(null).to.not.be.undefined;
*
* @name undefined * @name undefined
* @api public * @api public
*/ */
@ -373,10 +399,11 @@ Object.defineProperty(Assertion.prototype, 'undefined',
* *
* Assert object exists (null). * Assert object exists (null).
* *
* var foo = 'hi' * var foo = 'hi'
* , bar; * , bar;
* expect(foo).to.exist; *
* expect(bar).to.not.exist; * expect(foo).to.exist;
* expect(bar).to.not.exist;
* *
* @name exist * @name exist
* @api public * @api public
@ -398,9 +425,13 @@ Object.defineProperty(Assertion.prototype, 'exist',
/** /**
* ### .empty * ### .empty
* *
* Assert object's length to be 0. * Assert object's length to be `0`. For arrays, it check
* the length property. For objects it gets the count of
* enumerable keys.
* *
* expect([]).to.be.empty; * expect([]).to.be.empty;
* expect('').to.be.empty;
* expect({}).to.be.empty;
* *
* @name empty * @name empty
* @api public * @api public
@ -411,7 +442,7 @@ Object.defineProperty(Assertion.prototype, 'empty',
var obj = flag(this, 'object') var obj = flag(this, 'object')
, expected = obj; , expected = obj;
if (Array.isArray(obj)) { if (Array.isArray(obj) || 'string' === typeof object) {
expected = obj.length; expected = obj.length;
} else if (typeof obj === 'object') { } else if (typeof obj === 'object') {
expected = Object.keys(obj).length; expected = Object.keys(obj).length;
@ -432,9 +463,9 @@ Object.defineProperty(Assertion.prototype, 'empty',
* *
* Assert object is an instanceof arguments. * Assert object is an instanceof arguments.
* *
* function test () { * function test () {
* expect(arguments).to.be.arguments; * expect(arguments).to.be.arguments;
* } * }
* *
* @name arguments * @name arguments
* @api public * @api public
@ -459,9 +490,11 @@ Object.defineProperty(Assertion.prototype, 'arguments',
/** /**
* ### .equal(value) * ### .equal(value)
* *
* Assert strict equality. * Assert strict equality (===).
* *
* expect('hello').to.equal('hello'); * expect('hello').to.equal('hello');
* expect(42).to.equal(42);
* expect(1).to.not.equal(true);
* *
* @name equal * @name equal
* @param {Mixed} value * @param {Mixed} value
@ -483,7 +516,8 @@ Assertion.prototype.equal = function (val) {
* *
* Assert deep equality. * Assert deep equality.
* *
* expect({ foo: 'bar' }).to.eql({ foo: 'bar' }); * expect({ foo: 'bar' }).to.eql({ foo: 'bar' });
* expect([ 1, 2, 3 ]).to.eql([ 1, 2, 3 ]);
* *
* @name eql * @name eql
* @param {*} value * @param {*} value
@ -505,7 +539,7 @@ Assertion.prototype.eql = function (obj) {
* *
* Assert greater than `value`. * Assert greater than `value`.
* *
* expect(10).to.be.above(5); * expect(10).to.be.above(5);
* *
* @name above * @name above
* @alias gt * @alias gt
@ -527,7 +561,7 @@ Assertion.prototype.above = function (val) {
* *
* Assert less than `value`. * Assert less than `value`.
* *
* expect(5).to.be.below(10); * expect(5).to.be.below(10);
* *
* @name below * @name below
* @alias lt * @alias lt
@ -549,7 +583,7 @@ Assertion.prototype.below = function (val) {
* *
* Assert that a number is within a range. * Assert that a number is within a range.
* *
* expect(7).to.be.within(5,10); * expect(7).to.be.within(5,10);
* *
* @name within * @name within
* @param {Number} start lowerbound inclusive * @param {Number} start lowerbound inclusive
@ -574,10 +608,11 @@ Assertion.prototype.within = function (start, finish) {
* *
* Assert instanceof. * Assert instanceof.
* *
* var Tea = function (name) { this.name = name; } * var Tea = function (name) { this.name = name; }
* , Chai = new Tea('chai'); * , Chai = new Tea('chai');
* *
* expect(Chai).to.be.an.instanceof(Tea); * expect(Chai).to.be.an.instanceof(Tea);
* expect([ 1, 2, 3 ]).to.be.instanceof(Array);
* *
* @name instanceof * @name instanceof
* @param {Constructor} * @param {Constructor}
@ -599,11 +634,23 @@ Assertion.prototype.instanceOf = function (constructor) {
* ### .property(name, [value]) * ### .property(name, [value])
* *
* Assert that property of `name` exists, optionally with `value`. * Assert that property of `name` exists, optionally with `value`.
* Can use dot-notation for deep reference.
* *
* var obj = { foo: 'bar' } * // legacy / simple referencing
* expect(obj).to.have.property('foo'); * var obj = { foo: 'bar' }
* expect(obj).to.have.property('foo', 'bar'); * expect(obj).to.have.property('foo');
* expect(obj).to.have.property('foo').to.be.a('string'); * expect(obj).to.have.property('foo', 'bar');
* expect(obj).to.have.property('foo').to.be.a('string');
*
* // deep referencing
* var deepObj = {
* green: { tea: 'matcha' }
* , teas: [ 'chai', 'matcha', { tea: 'konacha' } ]
* };
* expect(deepObj).to.have.property('green.tea', 'matcha');
* expect(deepObj).to.have.property('teas[1]', 'matcha');
* expect(deepObj).to.have.property('teas[2].tea', 'konacha');
* *
* @name property * @name property
* @param {String} name * @param {String} name
@ -647,7 +694,7 @@ Assertion.prototype.property = function (name, val) {
* *
* Assert that has own property by `name`. * Assert that has own property by `name`.
* *
* expect('test').to.have.ownProperty('length'); * expect('test').to.have.ownProperty('length');
* *
* @name ownProperty * @name ownProperty
* @alias haveOwnProperty * @alias haveOwnProperty
@ -669,8 +716,8 @@ Assertion.prototype.ownProperty = function (name) {
* *
* Assert that object has expected length. * Assert that object has expected length.
* *
* expect([1,2,3]).to.have.length(3); * expect([1,2,3]).to.have.length(3);
* expect('foobar').to.have.length(6); * expect('foobar').to.have.length(6);
* *
* @name length * @name length
* @alias lengthOf * @alias lengthOf
@ -699,7 +746,7 @@ Assertion.prototype.length = function (n) {
* *
* Assert that matches regular expression. * Assert that matches regular expression.
* *
* expect('foobar').to.match(/^foo/); * expect('foobar').to.match(/^foo/);
* *
* @name match * @name match
* @param {RegExp} RegularExpression * @param {RegExp} RegularExpression
@ -722,7 +769,7 @@ Assertion.prototype.match = function (re) {
* *
* Assert inclusion of string in string. * Assert inclusion of string in string.
* *
* expect('foobar').to.have.string('bar'); * expect('foobar').to.have.string('bar');
* *
* @name string * @name string
* @param {String} string * @param {String} string
@ -744,10 +791,11 @@ Assertion.prototype.string = function (str) {
/** /**
* ### .keys(key1, [key2], [...]) * ### .keys(key1, [key2], [...])
* *
* Assert exact keys or the inclusing of keys using the `contain` modifier. * Assert exact keys or the inclusing of keys
* using the `include` or `contain` modifier.
* *
* expect({ foo: 1, bar: 2 }).to.have.keys(['foo', 'bar']); * expect({ foo: 1, bar: 2 }).to.have.keys(['foo', 'bar']);
* expect({ foo: 1, bar: 2, baz: 3 }).to.contain.keys('foo', 'bar'); * expect({ foo: 1, bar: 2, baz: 3 }).to.contain.keys('foo', 'bar');
* *
* @name keys * @name keys
* @alias key * @alias key
@ -815,22 +863,23 @@ Assertion.prototype.keys = function(keys) {
* (as determined using `instanceof`), optionally with a RegExp or string inclusion test * (as determined using `instanceof`), optionally with a RegExp or string inclusion test
* for the error's message. * for the error's message.
* *
* var err = new ReferenceError('This is a bad function.'); * var err = new ReferenceError('This is a bad function.');
* var fn = function () { throw err; } * var fn = function () { throw err; }
* expect(fn).to.throw(ReferenceError); * expect(fn).to.throw(ReferenceError);
* expect(fn).to.throw(Error); * expect(fn).to.throw(Error);
* expect(fn).to.throw(/bad function/); * expect(fn).to.throw(/bad function/);
* expect(fn).to.not.throw('good function'); * expect(fn).to.not.throw('good function');
* expect(fn).to.throw(ReferenceError, /bad function/); * expect(fn).to.throw(ReferenceError, /bad function/);
* expect(fn).to.throw(err); * expect(fn).to.throw(err);
* expect(fn).to.not.throw(new RangeError('Out of range.')); * expect(fn).to.not.throw(new RangeError('Out of range.'));
* *
* Please note that when a throw expectation is negated, it will check each * Please note that when a throw expectation is negated, it will check each
* parameter independently, starting with error constructor type. The appropriate way * parameter independently, starting with error constructor type. The appropriate way
* to check for the existence of a type of error but for a message that does not match * to check for the existence of a type of error but for a message that does not match
* is to use `and`. * is to use `and`.
* *
* expect(fn).to.throw(ReferenceError).and.not.throw(/good function/); * expect(fn).to.throw(ReferenceError)
* .and.not.throw(/good function/);
* *
* @name throw * @name throw
* @alias throws * @alias throws
@ -921,8 +970,8 @@ Assertion.prototype.Throw = function (constructor, msg) {
* *
* Assert that object/class will respond to a method. * Assert that object/class will respond to a method.
* *
* expect(Klass).to.respondTo('bar'); * expect(Klass).to.respondTo('bar');
* expect(obj).to.respondTo('bar'); * expect(obj).to.respondTo('bar');
* *
* @name respondTo * @name respondTo
* @param {String} method * @param {String} method
@ -951,7 +1000,7 @@ Assertion.prototype.respondTo = function (method) {
* *
* Assert that passes a truth test. * Assert that passes a truth test.
* *
* expect(1).to.satisfy(function(num) { return num > 0; }); * expect(1).to.satisfy(function(num) { return num > 0; });
* *
* @name satisfy * @name satisfy
* @param {Function} matcher * @param {Function} matcher
@ -976,7 +1025,7 @@ Assertion.prototype.satisfy = function (matcher) {
* *
* Assert that actual is equal to +/- delta. * Assert that actual is equal to +/- delta.
* *
* expect(1.5).to.be.closeTo(1, 0.5); * expect(1.5).to.be.closeTo(1, 0.5);
* *
* @name closeTo * @name closeTo
* @param {Number} expected * @param {Number} expected