{
  "name": "should",
  "description": "test framework agnostic BDD-style assertions",
  "version": "3.1.2",
  "author": {
    "name": "TJ Holowaychuk",
    "email": "tj@vision-media.ca"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/visionmedia/should.js.git"
  },
  "homepage": "https://github.com/visionmedia/should.js",
  "scripts": {
    "test": "make test"
  },
  "devDependencies": {
    "mocha": "*",
    "jsdom": "*",
    "jquery": "*"
  },
  "keywords": [
    "test",
    "bdd",
    "assert"
  ],
  "main": "./lib/node.js",
  "engines": {
    "node": ">= 0.2.0"
  },
  "readme": "# should.js\n\n_should_ is an expressive, readable, test framework agnostic, assertion library. Main goals of this library __to be expressive__ and __to be helpful__. It means test code should be clean, and error messages enough helpfull to understand error.\n\nIt extends the `Object.prototype` with a single non-enumerable getter that allows you to express how that object should behave, also it returns itself when required with `require`.\n\n## Example\n```javascript\nvar should = require('should');\n\nvar user = {\n    name: 'tj'\n  , pets: ['tobi', 'loki', 'jane', 'bandit']\n};\n\nuser.should.have.property('name', 'tj');\nuser.should.have.property('pets').with.lengthOf(4);\n\n// if the object was created with Object.create(null)\n// then it doesn't inherit `Object` and have the `should` getter\n// so you can do:\n\nshould(user).have.property('name', 'tj');\nshould(true).ok;\n\nsomeAsyncTask(foo, function(err, result){\n  should.not.exist(err);\n  should.exist(result);\n  result.bar.should.equal(foo);\n});\n```\n## To begin\n\n 1. Install it:\n    \n    $ npm install should --save-dev\n    \n 2. Require it and use:\n\n```javascript\nvar should = require('should');\n\n(5).should.be.exactly(5).and.be.a.Number;\n```\n\n## In browser\n\nIf you want to use _should_ in browser, use version that is in root of repository (or build it yourself). It is builded with browserify (see [Makefile](https://github.com/visionmedia/should.js/blob/master/Makefile)). To build fresh version:\n\n```bash\n# you should have browserify\nnpm install -g browserify\nmake browser\n```\n\nThis script exported to `window.Should`. It is the same as use `should` statically:\n\n```js\nShould(5).be.exactly(5)\n```\n\nAlso as for node.js case `Object.prototype` extended with `should` (that is why `window.Should` used):\n\n```js\nwindow.should.be.exactly(window);\n// the same\n// window is host object \nshould.be.exactly(window);\n// you should not really care about it\n\n(5).should.be.exactly(5);\n```\n\n*should.js* uses EcmaScript 5 very extensively so any browser that support ES5 is supported. (IE <=8 not supported).\nSee [kangax's compat table](http://kangax.github.io/es5-compat-table) to know which exactly.\n\nYou can easy install it with again npm or bower:\n```\nnpm install should --save-dev\n# or\nbower install visionmedia/should.js\n```\n\n## Static should and assert module\n\nFor some rare cases should can be used statically, without `Object.prototype`.\nIt can be replacement for node assert module:\n\n```javascript\nassert.fail(actual, expected, message, operator) // just write wrong should assertion\nassert(value, message), assert.ok(value, [message]) // should(value).ok\nassert.equal(actual, expected, [message]) // should(actual).eql(expected, [message])\nassert.notEqual(actual, expected, [message]) // should(actual).not.eql(expected, [message])\nassert.deepEqual(actual, expected, [message]) // should(actual).eql(expected, [message])\nassert.notDeepEqual(actual, expected, [message]) // should(actual).not.eql(expected, [message])\nassert.strictEqual(actual, expected, [message]) // should(actual).equal(expected, [message])\nassert.notStrictEqual(actual, expected, [message]) // should(actual).not.equal(expected, [message])\nassert.throws(block, [error], [message]) // should(block).throw([error])\nassert.doesNotThrow(block, [message]) // should(block).not.throw([error])\nassert.ifError(value) // should(value).Error (to check if it is error) or should(value).not.ok (to check that it is falsy)\n```\n\t\n## .not\n\n`.not` negate current assertion.\n\n# Assertions\n## chaining assertions\n\nEvery assertion will return a `should.js`-wrapped Object, so assertions can be chained.\nYou can use this helpers to just chain: `.an`, `.of`, `.a`, `.and`, `.be`, `.have`, `.with`, `.is`, `.which`. Use them for better readability, they do nothing at all.\nFor example:\n```js\nuser.should.be.an.instanceOf(Object).and.have.property('name', 'tj');\nuser.pets.should.be.instanceof(Array).and.have.lengthOf(4);\n```\nAlmost all assertions return the same object - so you can easy chain them. But some move assertion object to property value. See feather, it will be mention if object chainged.\n\n## .ok\n\nAssert if asseted object is truthy in javascript meaning of truthy ('', null, undefined, 0 , NaN, Infinity - is falsy, so all others are truthy).\n\nAssert truthfulness:\n\n```javascript\ntrue.should.be.ok;\n'yay'.should.be.ok;\n(1).should.be.ok;\n({}).should.be.ok;\n```\n\nor negated:\n\n```javascript\nfalse.should.not.be.ok;\n''.should.not.be.ok;\n(0).should.not.be.ok;\n```\n\n## .true\n\nAssert if asseted object === true:\n\n```javascript\ntrue.should.be.true;\n'1'.should.not.be.true;\n```\n\n## .false\n\nAssert if asseted object === false:\n\n```javascript\nfalse.should.be.false;\n(0).should.not.be.false;\n```\n\n## .eql(otherValue)\n\nAssert if asserted object is *equal* to otherValue. This means that object compared by its actual content, not just reference equality.\n \n```javascript\n({ foo: 'bar' }).should.eql({ foo: 'bar' });\n[1,2,3].should.eql([1,2,3]);\n// see next example it is correct, even if it is different types, but actual content the same\n[1, 2, 3].should.eql({ '0': 1, '1': 2, '2': 3 });\n```\n## .equal(otherValue) and .exactly(otherValue)\n\nAssert if asserted object strictly equal to `otherValue` (using `===` - no type conversion for primitive types and reference equivalence for reference types).\n\n```javascript\n(4).should.equal(4);\n'test'.should.equal('test');\n[1,2,3].should.not.equal([1,2,3]);\n(4).should.be.exactly(4);\n```\n\n## .startWith(str)\n\nAssert that string starts with `str`.\n\n```javascript\n'foobar'.should.startWith('foo');\n'foobar'.should.not.startWith('bar');\n```\n## .endWith(str)\n\nAssert that string ends with `str`.\n\n```javascript\n'foobar'.should.endWith('bar');\n'foobar'.should.not.endWith('foo');\n```\n\n## .within(from, to)\n\nAssert inclusive numeric range (`<= to` and `>= from`):\n```javascript\nuser.age.should.be.within(5, 50);\n(5).should.be.within(5, 10).and.within(5, 5);\n```\n\n## .approximately(num, delta)\n\nAssert floating point number near `num` within `delta` margin:\n\n```javascript\n(99.99).should.be.approximately(100, 0.1);\n```\n\n## .above(num) and .greaterThan(num)\n\nAssert numeric value above the given value (`> num`):\n\n```javascript\nuser.age.should.be.above(5);\nuser.age.should.not.be.above(100);\n(5).should.be.above(0);\n(5).should.not.be.above(5);\n```\n\n## .below(num) and .lessThan(num)\n\nAssert numeric value below the given value (`< num`):\n\n```javascript\nuser.age.should.be.below(100);\nuser.age.should.not.be.below(5);\n(5).should.be.below(6);\n(5).should.not.be.below(5);\n```\n\n## .NaN\n\nAssert numeric value is NaN:\n\n```javascript\n(undefined + 0).should.be.NaN;\n```\n\n## .Infinity\n\nAssert numeric value is Infinity:\n\n```javascript\n(1/0).should.be.Infinity;\n```\n\n## .type(str)\n\nAssert given value have such type (using __typeof__ operator):\n```javascript\nuser.should.be.type('object');\n'test'.should.be.type('string');\n```\n\n## .instanceof(constructor) and .instanceOf(constructor)\n\nAssert given value is instance of `constructor` (using __instanceof__ operator):\n\n```javascript\nuser.should.be.an.instanceof(User);\n[].should.be.an.instanceOf(Array);\n```\n\n## .arguments\n\nAssert given object is an `Arguments`:\n\n```javascript\nvar args = (function(){ return arguments; })(1,2,3);\nargs.should.be.arguments;\n[].should.not.be.arguments;\n```\n\n## .Object, .Number, .Array, .Boolean, .Function, .String, .Error\n\nAssert given object is instance of such constructor (shortcut for `.instanceof` assertion).\n\n```javascript\n({}).should.be.an.Object;\n(1).should.be.a.Number;\n[].should.be.an.Array.and.an.Object;\n(true).should.be.a.Boolean;\n''.should.be.a.String;\n```\n\n## .property(name[, value])\n\nAssert property exists and has optional value(compare using `.eql`):\n```javascript\nuser.should.have.property('name');\nuser.should.have.property('age', 15);\nuser.should.not.have.property('rawr');\nuser.should.not.have.property('age', 0);\n[1, 2].should.have.property('0', 1);\n```\n\n__NB__ `.property` change object to actual property value!\n\n## .properties(propName1, propName2, ...) or .properties([propName1, propName2, ...]) or .properties(obj)\n\n`obj` it is object that map properties to their actual values.\n\nAssert all given properties exists and have given values (compare using `.eql`):\n\n```javascript\nuser.should.have.properties('name', 'age');\nuser.should.have.properties(['name', 'age']);\nuser.should.have.properties({\n    name: 'denis',\n    age: 24\n});\n```\n\n## .length(number) and .lengthOf(number)\n\nAssert _length_ property exists and has a value of the given number (shortcut for `.property('length', number)`):\n```javascript\nuser.pets.should.have.length(5);\nuser.pets.should.have.a.lengthOf(5);\n({ length: 10}).should.have.length(10);\n```\n\n__NB__ `.length` change object to actual property value!\n\n## .ownProperty(str) and .hasOwnProperty(str)\n\nAssert given object has own property (using `.hasOwnProperty`):\n```javascript\n({ foo: 'bar' }).should.have.ownProperty('foo').equal('bar');\n```\n\n__NB__ `.length` change object to actual property value!\n\n## .empty\n\nAssert given value is empty. It means for strings, arrays, arguments length == 0 and for object do not have own properties.\n\n```javascript\n[].should.be.empty;\n''.should.be.empty;\n({}).should.be.empty;\n(function() {\n  arguments.should.be.empty;\n})();\n```\n\n## .keys([key1, key2, ...]) and .keys(key1, key2, ...) and .key(key)\n\nAssert own object keys, which must match _exactly_,\nand will fail if you omit a key or two:\n\n```javascript\nvar obj = { foo: 'bar', baz: 'raz' };\nobj.should.have.keys('foo', 'baz');\nobj.should.have.keys(['foo', 'baz']);\n({}).should.have.keys();\n({}).should.have.keys('key'); //fail AssertionError: expected {} to have key 'key'missing keys: 'key'\n```\n\n## .containEql(otherValue)\n\nAssert given value to contain something *.eql* to otherValue. See examples to understand better:\n\n```javascript\n'hello boy'.should.containEql('boy');\n[1,2,3].should.containEql(3);\n[[1],[2],[3]].should.containEql([3]);\n[[1],[2],[3, 4]].should.not.containEql([3]);\n\n({ b: 10 }).should.containEql({ b: 10 });\n([1, 2, { a: 10 }]).should.containEql({ a: 10 });\n[1, 2, 3].should.not.containEql({ a: 1 });\n\n[{a: 'a'}, {b: 'b', c: 'c'}].should.containEql({a: 'a'});\n[{a: 'a'}, {b: 'b', c: 'c'}].should.not.containEql({b: 'b'});\n```\n\n## .containDeep(otherValue)\n\nAssert given value to contain something *.eql* to otherValue within depth.\nAgain see examples:\n\n```javascript\n'hello boy'.should.containDeep('boy');\n[1,2,3].should.containDeep([3]);\n[1,2,3].should.containDeep([1, 3]);\n//but not\n[1,2,3].should.containDeep([3, 1]);\n\n({ a: { b: 10 }, b: { c: 10, d: 11, a: { b: 10, c: 11} }}).should\n  .containDeep({ a: { b: 10 }, b: { c: 10, a: { c: 11 }}});\n\n[1, 2, 3, { a: { b: { d: 12 }}}].should.containDeep([{ a: { b: {d: 12}}}]);\n\n[[1],[2],[3]].should.containDeep([[3]]);\n[[1],[2],[3, 4]].should.containDeep([[3]]);\n[{a: 'a'}, {b: 'b', c: 'c'}].should.containDeep([{a: 'a'}]);\n[{a: 'a'}, {b: 'b', c: 'c'}].should.containDeep([{b: 'b'}]);\n```\n\nIt does not search somewhere in depth it check all pattern in depth. Object checked\nby properties key and value, arrays checked like sub sequences. Everyting compared using .eql.\nMain difference with `.containEql` is that this assertion require full type chain -\nif asserted value is an object, otherValue should be also an object (which is sub object of given).\nThe same true for arrays, otherValue should be an array which compared to be subsequence of given object.\n\n## .match(otherValue)\n\nAssert given object to match `otherValue`.\n\nGiven: String, otherValue: regexp. Uses `RegExp#exec(str)`:\n```javascript\nusername.should.match(/^\\w+$/)\n```\n\nGiven: Array, otherValue: regexp - assert each value match to regexp.\n```javascript\n['a', 'b', 'c'].should.match(/[a-z]/);\n['a', 'b', 'c'].should.not.match(/[d-z]/);\n```\n\nGiven: Object, otherValue: regexp - assert own property's values to match regexp.\n```javascript\n({ a: 'foo', c: 'barfoo' }).should.match(/foo$/);\n({ a: 'a' }).should.not.match(/^http/);\n```\n\nGiven: Anything, otherValue: function - assert if given value matched to function.\n\nFunction can use .should inside or return 'true' or 'false', in all other cases it do nothing. If you return value that return assertion, you will receive better error messages.\n\n```javascript\n(5).should.match(function(n) { return n > 0; });\n(5).should.not.match(function(n) { return n < 0; });\n(5).should.not.match(function(it) { it.should.be.an.Array; });\n(5).should.match(function(it) { return it.should.be.a.Number; });\n```\n\nNow compare messages:\n```javascript\n(5).should.not.match(function(it) { it.should.be.a.Number; });\n//AssertionError: expected 5 not to match [Function]\n(5).should.not.match(function(it) { return it.should.be.a.Number; });\n//AssertionError: expected 5 not to match [Function]\n//\texpected 5 to be a number\n```\n\nGiven: object, otherValue: another object - assert that object properties match to properties of another object in meaning that describe above cases. See examples:\n\n```javascript\n({ a: 10, b: 'abc', c: { d: 10 }, d: 0 }).should\n    .match({ a: 10, b: /c$/, c: function(it) { return it.should.have.property('d', 10); }});\n\n[10, 'abc', { d: 10 }, 0].should\n\t.match({ '0': 10, '1': /c$/, '2': function(it) { return it.should.have.property('d', 10); } });\n\n[10, 'abc', { d: 10 }, 0].should\n    .match([10, /c$/, function(it) { return it.should.have.property('d', 10); }]); \n```\n\n## .matchEach(otherValue)\n\nAssert given property keys and values each match given check object.\n\nIf `otherValue` is RegExp, then each property value checked to match it:\n```javascript\n(['a', 'b', 'c']).should.matchEach(/[a-c]/);\n```\n\nIf `otherValue` is Function, then check each property value and key matched it:\n```javascript\n[10, 11, 12].should.matchEach(function(it) { return it >= 10; });\n[10, 11, 12].should.matchEach(function(it) { return it >= 10; });\n```\n\nIn other cases it check that each property value is `.eql` to `otherValue`:\n```javascript\n[10, 10].should.matchEach(10);\n```\n## .throw() and throwError()\n\nAssert an exception is thrown:\n\n```js\n(function(){\n  throw new Error('fail');\n}).should.throw();\n```\n\nAssert an exception is not thrown:\n\n```js\n(function(){\n\n}).should.not.throw();\n```\nAssert exception message matches string:\n\n```js\n(function(){\n  throw new Error('fail');\n}).should.throw('fail');\n```\n\nAssert exepection message matches regexp:\n\n```js\n(function(){\n  throw new Error('failed to foo');\n}).should.throw(/^fail/);\n```\n\nIf you need to pass arguments and/or context to execute function use `Function#bind(context, arg1, ...)`:\n```js\nfunction isPositive(n) {\n    if(n <= 0) throw new Error('Given number is not positive')\n}\n\nisPositive.bind(null, 10).should.not.throw();\nisPositive.bind(null, -10).should.throw();\n```\n\nIf you need to check something in asynchronous function it is required to do in 2 steps:\n\n```js\n// first we need to check that function is called\nvar called = false;\ncollection.findOne({ _id: 10 }, function(err, res) {\n    called = true;\n    \n    //second we test what you want\n    res.should.be....\n});\n\ncalled.should.be.true;\n```\n\nIn case you are using something like `Mocha`, you should use asynchronous test and call `done()` in proper place to make sure that you asynchronous function is called before test is finished.\n```js\ncollection.findOne({ _id: 10 }, function(err, res) {\n    if(err) return done(err);\n    //second we test what you want\n    res.should.be....\n    \n    done();\n});\n```\n\nIn general case if you need to check that something is executed you need such thing as `spies`, good example is an [sinon](http://sinonjs.org/).\n\n## .status(code)\n\nAsserts that `.statusCode` is `code`:\n```javascript\nres.should.have.status(200);\n```\n\nNot included in browser build.\n\n## .header(field[, value])\n\nAsserts that a `.headers` object with `field` and optional `value` are present:\n```javascript\nres.should.have.header('content-length');\nres.should.have.header('Content-Length', '123');\n```\n\nNot included in browser build.\n\n## .json\n\nAssert that Content-Type is \"application/json; charset=utf-8\"\n\n```javascript\nres.should.be.json\n```\n\nNot included in browser build.\n\n## .html\n\nAssert that Content-Type is \"text/html; charset=utf-8\"\n```javascript\nres.should.be.html\n```\n\nNot included in browser build.\n\n## Optional Error description\n\nAs it can often be difficult to ascertain exactly where failed assertions are coming from in your tests, an optional description parameter can be passed to several should matchers. The description will follow the failed assertion in the error:\n\n    (1).should.eql(0, 'some useful description')\n\n    AssertionError: some useful description\n      at Object.eql (/Users/swift/code/should.js/node_modules/should/lib/should.js:280:10)\n      ...\n\nThe methods that support this optional description are: `eql`, `equal`, `within`, `instanceof`, `above`, `below`, `match`, `length`, `property`, `ownProperty`.\n\n## Mocha example\n\nFor example you can use should with the [Mocha test framework](http://visionmedia.github.io/mocha/) by simply including it:\n\n```javascript\nvar should = require('should');\nvar mylib = require('mylib');\n\n\ndescribe('mylib', function () {\n  it('should have a version with the format #.#.#', function() {\n    lib.version.should.match(/^\\d+\\.\\d+\\.\\d+$/);\n  }\n});\n```\n\n## Contributions\n\n[Actual list of contributors](https://github.com/visionmedia/should.js/graphs/contributors) if you want to show it your friends.\n\nTo run the tests for _should_ simply run:\n\n    $ make test\n    \nBefore contribute something:\n\n1. Your code looks like all other code - all project should look like it was written by one man, always.\n2. If you want propose something - just create issue and describe your question with much description as you can.\n3. Please never send issues or pull requests about code style, jshint violations etc - i do not accept it (and you will spend your time for free).\n4. If you think you have some general receipt, consider create PR with it.\n5. If you not sure if you receipt enough general just create your own plugin for should.js. (see should.use and Assertion.add usage).\n6. If you add new code it should be covered by tests, no tests - no code. \n7. If you find bug (or at least you think it is a bug), create issue with library version and test case that I can run and see what are you talking about, or at least full steps that I can reproduce it.\n\n## OMG IT EXTENDS OBJECT???!?!@\n\nYes, yes it does, with a single getter _should_, and no it won't break your code, because it does this **properly** with a non-enumerable property.\n\n## License\n\nMIT\n",
  "readmeFilename": "Readme.md",
  "bugs": {
    "url": "https://github.com/visionmedia/should.js/issues"
  },
  "_id": "should@3.1.2",
  "_from": "should@*"
}