| [516] | 35 | "readme": "# should.js\n\n_should_ is an expressive, readable, test framework agnostic, assertion library for [node](http://nodejs.org).\n\nIt extends the Object prototype with a single non-enumerable getter that allows you to express how that object should behave.\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// or without Object.prototype, for guys how did Object.create(null)\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## Installation\n\n $ npm install should --save-dev\n\n## In browser\n\nIf you want to use _should_ in browser, use version that is in root of repository. It is build with browserify (see [Makefile](https://github.com/visionmedia/should.js/blob/master/Makefile) about how it is build). To build fresh version:\n\n```bash\n# you should have browserify\nnpm install -g browserify\nmake browser\n```\n\n## chaining assertions\n\nEvery assertion will return a should.js-wraped Object, so assertions can be chained. For example:\n\n```js\nuser.should.be.an.instanceOf(Object).and.have.property('name', 'tj');\nuser.pets.should.be.instanceof(Array).and.have.lengthOf(4);\n```\n\nAll assertions return themselves but not `property` and `ownProperty`. They two would return the property value.\n\nfor example if a property is volatile we can first assert property existence:\n```javascript\n// `user.should.have.property('pets')` returned `should(user.pets)` but not `should(user)`\nuser.should.have.property('pets').with.lengthOf(4)\n```\nwhich is essentially equivalent to below, however the property may not exist:\n```javascript\nuser.pets.should.have.lengthOf(4)\n```\n\nour dummy getters such as _a_, _an_, _be_, _of_ and _have_ make tests more readable while the getters _and_ and _with_ helps express chaining:\n```javascript\nuser.should.be.an.instanceOf(Object).and.have.property('name', 'tj')\nuser.should.have.property('pets').with.a.lengthOf(4)\n```\nThose getters don't have any actual effect, just for readability.\n\n## static\n\nFor some rare cases should can be used statically, without `Object.prototype`.\nIt can be replacement for node assert module (and it uses the same `AssertionError`):\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\n## ok\n\nAssert truthfulness:\n```javascript\ntrue.should.be.ok\n'yay'.should.be.ok\n(1).should.be.ok\n```\nor negated:\n```javascript\nfalse.should.not.be.ok\n''.should.not.be.ok\n(0).should.not.be.ok\n```\n## true\n\nAssert === true:\n```javascript\ntrue.should.be.true\n'1'.should.not.be.true\n```\n## false\n\nAssert === false:\n```javascript\nfalse.should.be.false\n(0).should.not.be.false\n```\n## arguments\n\nAssert `Arguments`:\n```javascript\nvar args = (function(){ return arguments; })(1,2,3);\nargs.should.be.arguments;\n[].should.not.be.arguments;\n```\n## empty\n\nAsserts that given object is empty\n```javascript\n[].should.be.empty\n''.should.be.empty\n({}).should.be.empty\n(function() {\n arguments.should.be.empty;\n})()\n```\n## eql\n\nequality:\n```javascript\n({ foo: 'bar' }).should.eql({ foo: 'bar' })\n[1,2,3].should.eql([1,2,3])\n```\n## equal and exactly\n\nstrict equality:\n```javascript\nshould.strictEqual(undefined, value)\nshould.strictEqual(false, value)\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## within\n\nAssert inclusive numeric range:\n```javascript\nuser.age.should.be.within(5, 50)\n```\n## approximately\n\nAssert floating point number:\n```javascript\n(99.99).should.be.approximately(100, 0.1);\n```\n## type\n\nAssert __typeof__:\n```javascript\nuser.should.be.type('object')\n'test'.should.be.type('string')\n```\n## instanceof and instanceOf\n\nAssert __instanceof__ or __instanceOf__:\n```javascript\nuser.should.be.an.instanceof(User)\n[].should.be.an.instanceOf(Array)\n```\n## above\n\nAssert numeric value above the given value:\n```javascript\nuser.age.should.be.above(5)\nuser.age.should.not.be.above(100)\n```\n## below\n\nAssert numeric value below the given value:\n```javascript\nuser.age.should.be.below(100)\nuser.age.should.not.be.below(5)\n```\n## NaN\n\nAssert numeric valus is NaN:\n```javascript\n(undefined + 0).should.be.NaN;\n```\n## Infinity\n\nAssert numeric valus is Infinity:\n```javascript\n(1/0).should.be.Infinity;\n```\n## match\n\nAssert regexp match:\n```javascript\nusername.should.match(/^\\w+$/)\n```\n## length\n\nAssert _length_ property exists and has a value of the given number:\n```javascript\nuser.pets.should.have.length(5)\nuser.pets.should.have.a.lengthOf(5)\n({ length: 10}).should.have.length(10);\n```\nAliases: _lengthOf_\n\n## property\n\nAssert property exists and has optional value(compare using `===`):\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```\n\n## properties\n\nAssert given properties exists:\n```javascript\nuser.should.have.properties('name', 'age');\nuser.should.have.properties(['name', 'age']);\n```\n## ownProperty\n\nAssert own property (on the immediate object):\n```javascript\n({ foo: 'bar' }).should.have.ownProperty('foo')\n```\n## status(code)\n\n Asserts that `.statusCode` is `code`:\n```javascript\nres.should.have.status(200);\n```\n## header(field[, value])\n\n Asserts 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');\nres.should.have.header('content-length', '123');\n```\n## json\n\n Assert that Content-Type is \"application/json; charset=utf-8\"\n```javascript\nres.should.be.json\n```\n## html\n\n Assert that Content-Type is \"text/html; charset=utf-8\"\n```javascript\nres.should.be.html\n```\n\n## include(obj) or contain(obj)\n\nAssert that the given `obj` is present via `indexOf()`, so this works for strings, arrays, or custom objects implementing indexOf. Also it can assert if given object will have some sub-object.\n\nAssert array value:\n```javascript\n[1,2,3].should.include(3)\n[1,2,3].should.include(2)\n[1,2,3].should.not.include(4)\n```\nAssert substring:\n```javascript\n'foo bar baz'.should.include('foo')\n'foo bar baz'.should.include('bar')\n'foo bar baz'.should.include('baz')\n'foo bar baz'.should.not.include('FOO')\n```\nAssert object includes another object:\n```javascript\nvar tobi = { name: 'Tobi', age: 1 };\nvar jane = { name: 'Jane', age: 5 };\nvar user = { name: 'TJ', pet: tobi };\n\nuser.should.include({ pet: tobi });\nuser.should.include({ pet: tobi, name: 'TJ' });\nuser.should.not.include({ pet: jane });\nuser.should.not.include({ name: 'Someone' });\n```\n## includeEql(obj)\n\nAssert that an object equal to the given `obj` is present in an Array:\n```javascript\n[[1],[2],[3]].should.includeEql([3])\n[[1],[2],[3]].should.includeEql([2])\n[[1],[2],[3]].should.not.includeEql([4])\n```\n## throw()\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\n## throwError()\n\nAn alias of `throw`, its purpose is to be an option for those who run\n[jshint](https://github.com/jshint/node-jshint/) in strict mode.\n\n```js\n(function(){\n throw new Error('failed to baz');\n}).should.throwError(/^fail.*/);\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## keys\n\nAssert own object keys, which must match _exactly_,\nand will fail if you omit a key or two:\n\n var obj = { foo: 'bar', baz: 'raz' };\n obj.should.have.keys('foo', 'baz');\n obj.should.have.keys(['foo', 'baz']);\n\n## type assertions\n\n```javascript\n({}).should.be.an.Object;\n(1).should.be.an.Number;\n[].should.be.an.Array;\n(true).should.be.a.Boolean;\n''.should.be.a.String;\n```\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: expected 1 to equal 0 | 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`, `a`, `instanceof`, `above`, `below`, `match`, `length`, `property`, `ownProperty`, `include`, and `includeEql`.\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## Running tests\n\nTo run the tests for _should_ simply run:\n\n $ make test\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\n(The MIT License)\n\nCopyright (c) 2010-2011 TJ Holowaychuk <tj@vision-media.ca>\n\nCopyright (c) 2011 Aseem Kishore <aseem.kishore@gmail.com>\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n", |
|---|
