git.cworth.org Git - obsolete/notmuch-web/blob - node_modules/express/node_modules/qs/support/should/Readme.md

   1   _should_ is an expressive, test framework agnostic, assertion library for [node](http://nodejs.org).
   2
   3 _should_ literally extends node's _assert_ module, in fact, it is node's assert module, for example `should.equal(str, 'foo')` will work, just as `assert.equal(str, 'foo')` would, and `should.AssertionError` **is** `asset.AssertionError`, meaning any test framework supporting this constructor will function properly with _should_.
   4
   5 ## Example
   6
   7     var user = {
   8         name: 'tj'
   9       , pets: ['tobi', 'loki', 'jane', 'bandit']
  10     };
  11
  12     user.should.have.property('name', 'tj');
  13     user.should.have.property('pets').with.lengthOf(4)
  14
  15 ## Installation
  16
  17     $ npm install should
  18
  19 ## modifiers
  20
  21  _should_'s assertion chaining provides an expressive way to build up an assertion, along with dummy getters such as _an_, _have_, and _be_, provided are what I am simply calling **modifiers**, which have a meaning effect on the assertion. An example of this is the _not_ getter, which negates the meaning, aka `user.should.not.have.property('name')`. In the previous example note the use of _have_, as we could omit it and still construct a valid assertion.
  22
  23 Some modifiers such as _include_ only have an effect with specific assertion methods, for example when asserting a substring like so: `str.should.include.string('test')`, we could omit _include_, but it helps express the meaning, however _keys_ has a strict effect, unless the _include_ modifier is used.
  24
  25 ## chaining assertions
  26
  27 Some assertions can be chained, for example if a property is volatile we can first assert property existence:
  28
  29     user.should.have.property('pets').with.lengthOf(4)
  30
  31 which is essentially equivalent to below, however the property may not exist:
  32
  33     user.pets.should.have.lengthOf(4)
  34
  35 our dummy getters such as _and_ also help express chaining:
  36
  37     user.should.be.a('object').and.have.property('name', 'tj')
  38
  39 ## ok
  40
  41 Assert truthfulness:
  42
  43     true.should.be.ok
  44     'yay'.should.be.ok
  45     (1).should.be.ok
  46
  47 or negated:
  48
  49     false.should.not.be.ok
  50     ''.should.not.be.ok
  51     (0).should.not.be.ok
  52
  53 ## true
  54
  55 Assert === true:
  56
  57     true.should.be.true
  58     '1'.should.not.be.true
  59
  60 ## false
  61
  62 Assert === false:
  63
  64      false.should.be.false
  65      (0).should.not.be.false
  66
  67 ## arguments
  68
  69 Assert `Arguments`:
  70
  71     var args = (function(){ return arguments; })(1,2,3);
  72     args.should.be.arguments;
  73     [].should.not.be.arguments;
  74
  75 ## empty
  76
  77 Asserts that length is 0:
  78
  79     [].should.be.empty
  80     ''.should.be.empty
  81     ({ length: 0 }).should.be.empty
  82
  83 ## eql
  84
  85 equality:
  86
  87     ({ foo: 'bar' }).should.eql({ foo: 'bar' })
  88     [1,2,3].should.eql([1,2,3])
  89
  90 ## equal
  91
  92 strict equality:
  93
  94     should.strictEqual(undefined, value)
  95     should.strictEqual(false, value)
  96     (4).should.equal(4)
  97     'test'.should.equal('test')
  98     [1,2,3].should.not.equal([1,2,3])
  99
 100 ## within
 101
 102 Assert inclusive numeric range:
 103
 104     user.age.should.be.within(5, 50)
 105
 106 ## a
 107
 108 Assert __typeof__:
 109
 110     user.should.be.a('object')
 111     'test'.should.be.a('string')
 112
 113 ## instanceof
 114
 115 Assert __instanceof__:
 116
 117     user.should.be.an.instanceof(User)
 118     [].should.be.an.instanceof(Array)
 119
 120 ## above
 121
 122 Assert numeric value above the given value:
 123
 124     user.age.should.be.above(5)
 125     user.age.should.not.be.above(100)
 126
 127 ## below
 128
 129 Assert numeric value below the given value:
 130
 131     user.age.should.be.below(100)
 132     user.age.should.not.be.below(5)
 133
 134 ## match
 135
 136 Assert regexp match:
 137
 138     username.should.match(/^\w+$/)
 139
 140 ## length
 141
 142 Assert _length_ property exists and has a value of the given number:
 143
 144     user.pets.should.have.length(5)
 145     user.pets.should.have.a.lengthOf(5)
 146
 147 Aliases: _lengthOf_
 148
 149 ## string
 150
 151 Substring assertion:
 152
 153     'foobar'.should.include.string('foo')
 154     'foobar'.should.include.string('bar')
 155     'foobar'.should.not.include.string('baz')
 156
 157 ## property
 158
 159 Assert property exists and has optional value:
 160
 161     user.should.have.property('name')
 162     user.should.have.property('age', 15)
 163     user.should.not.have.property('rawr')
 164     user.should.not.have.property('age', 0)
 165
 166 ## ownProperty
 167
 168 Assert own property (on the immediate object):
 169
 170     ({ foo: 'bar' }).should.have.ownProperty('foo')
 171
 172 ## contain
 173
 174 Assert array value:
 175
 176     [1,2,3].should.contain(3)
 177     [1,2,3].should.contain(2)
 178     [1,2,3].should.not.contain(4)
 179
 180 ## keys
 181
 182 Assert own object keys, which must match _exactly_,
 183 and will fail if you omit a key or two:
 184
 185     var obj = { foo: 'bar', baz: 'raz' };
 186     obj.should.have.keys('foo', 'bar');
 187     obj.should.have.keys(['foo', 'bar']);
 188
 189 using the _include_ modifier, we can check inclusion of a key,
 190 but not fail when we omit a few:
 191
 192     obj.should.include.keys('foo')
 193     obj.should.include.keys('bar')
 194     obj.should.not.include.keys('baz')
 195
 196 ## respondTo
 197
 198 Assert that the given property is a function:
 199
 200     user.should.respondTo('email')
 201
 202 ## Express example
 203
 204 For example you can use should with the [Expresso TDD Framework](http://github.com/visionmedia/expresso) by simply including it:
 205
 206     var lib = require('mylib')
 207       , should = require('should');
 208
 209     module.exports = {
 210       'test .version': function(){
 211         lib.version.should.match(/^\d+\.\d+\.\d+$/);
 212       }
 213     };
 214
 215 ## Running tests
 216
 217 To run the tests for _should_ simple update your git submodules and run:
 218
 219     $ make test
 220
 221 ## OMG IT EXTENDS OBJECT???!?!@
 222
 223 Yes, yes it does, with a single getter _should_, and no it wont break your code, because it does this **properly** with a non-enumerable property.
 224
 225 ## License
 226
 227 (The MIT License)
 228
 229 Copyright (c) 2010 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
 230
 231 Permission is hereby granted, free of charge, to any person obtaining
 232 a copy of this software and associated documentation files (the
 233 'Software'), to deal in the Software without restriction, including
 234 without limitation the rights to use, copy, modify, merge, publish,
 235 distribute, sublicense, and/or sell copies of the Software, and to
 236 permit persons to whom the Software is furnished to do so, subject to
 237 the following conditions:
 238
 239 The above copyright notice and this permission notice shall be
 240 included in all copies or substantial portions of the Software.
 241
 242 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 243 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 244 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 245 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 246 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 247 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 248 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.