_should_ is an expressive, readable, test framework agnostic, assertion library for [node](http://nodejs.org).

It extends the Object prototype with a single non-enumerable getter that allows you to express how that object should behave.

_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** `assert.AssertionError`, meaning any test framework supporting this constructor will function properly with _should_.

## Example
```javascript
var user = {
    name: 'tj'
  , pets: ['tobi', 'loki', 'jane', 'bandit']
};

user.should.have.property('name', 'tj');
user.should.have.property('pets').with.lengthOf(4);

someAsyncTask(foo, function(err, result){
  should.not.exist(err);
  should.exist(result);
  result.bar.should.equal(foo);
});
```
## Installation

    $ npm install should

## assert extras

As mentioned above, _should_ extends node's _assert_. The returned object from `require('should')` is thus similar to the returned object from `require('assert')`, but it has one extra convenience method:
```javascript
should.exist('hello')
should.exist([])
should.exist(null)  // will throw
```
This is equivalent to `should.ok`, which is equivalent to `assert.ok`, but reads a bit better. It gets better, though:
```javascript
should.not.exist(false)
should.not.exist('')
should.not.exist({})    // will throw
```
We may add more _assert_ extras in the future... ;)

## chaining assertions

Some assertions can be chained, for example if a property is volatile we can first assert property existence:
```javascript
user.should.have.property('pets').with.lengthOf(4)
```
which is essentially equivalent to below, however the property may not exist:
```javascript
user.pets.should.have.lengthOf(4)
```
our dummy getters such as _and_ also help express chaining:
```javascript
user.should.be.a('object').and.have.property('name', 'tj')
```
## exist (static)

The returned object from `require('should')` is the same object as `require('assert')`. So you can use `should` just like `assert`:
```javascript
should.fail('expected an error!')
should.strictEqual(foo, bar)
```
In general, using the Object prototype's _should_ is nicer than using these `assert` equivalents, because _should_ gives you access to the expressive and readable language described above:
```javascript
foo.should.equal(bar)   // same as should.strictEqual(foo, bar) above
```
The only exception, though, is when you can't be sure that a particular object exists. In that case, attempting to access the _should_ property may throw a TypeError:
```javascript
foo.should.equal(bar)   // throws if foo is null or undefined!
```
For this case, `require('should')` extends `require('assert')` with an extra convenience method to check whether an object exists:
```javascript
should.exist({})
should.exist([])
should.exist('')
should.exist(0)
should.exist(null)      // will throw
should.exist(undefined) // will throw
```
You can also check the negation:
```javascript
should.not.exist(undefined)
should.not.exist(null)
should.not.exist('')    // will throw
should.not.exist({})    // will throw
```
Once you know an object exists, you can safely use the _should_ property on it.

## ok

Assert truthfulness:
```javascript
true.should.be.ok
'yay'.should.be.ok
(1).should.be.ok
```
or negated:
```javascript
false.should.not.be.ok
''.should.not.be.ok
(0).should.not.be.ok
```
## true

Assert === true:
```javascript
true.should.be.true
'1'.should.not.be.true
```
## false

Assert === false:
```javascript
false.should.be.false
(0).should.not.be.false
```
## arguments

Assert `Arguments`:
```javascript
var args = (function(){ return arguments; })(1,2,3);
args.should.be.arguments;
[].should.not.be.arguments;
```
## empty

Asserts that length is 0:
```javascript
[].should.be.empty
''.should.be.empty
({ length: 0 }).should.be.empty
```
## eql

equality:
```javascript
({ foo: 'bar' }).should.eql({ foo: 'bar' })
[1,2,3].should.eql([1,2,3])
```
## equal

strict equality:
```javascript
should.strictEqual(undefined, value)
should.strictEqual(false, value)
(4).should.equal(4)
'test'.should.equal('test')
[1,2,3].should.not.equal([1,2,3])
```
## within

Assert inclusive numeric range:
```javascript
user.age.should.be.within(5, 50)
```
## a

Assert __typeof__:
```javascript
user.should.be.a('object')
'test'.should.be.a('string')
```
## instanceof and instanceOf

Assert __instanceof__ or __instanceOf__:
```javascript
user.should.be.an.instanceof(User)
[].should.be.an.instanceOf(Array)
```
## above

Assert numeric value above the given value:
```javascript
user.age.should.be.above(5)
user.age.should.not.be.above(100)
```
## below

Assert numeric value below the given value:
```javascript
user.age.should.be.below(100)
user.age.should.not.be.below(5)
```
## match

Assert regexp match:
```javascript
username.should.match(/^\w+$/)
```
## length

Assert _length_ property exists and has a value of the given number:
```javascript
user.pets.should.have.length(5)
user.pets.should.have.a.lengthOf(5)
```
Aliases: _lengthOf_

## property

Assert property exists and has optional value:
```javascript
user.should.have.property('name')
user.should.have.property('age', 15)
user.should.not.have.property('rawr')
user.should.not.have.property('age', 0)
```
## ownProperty

Assert own property (on the immediate object):
```javascript
({ foo: 'bar' }).should.have.ownProperty('foo')
```
## status(code)

 Asserts that `.statusCode` is `code`:
```javascript
res.should.have.status(200);
```
## header(field[, value])

 Asserts that a `.headers` object with `field` and optional `value` are present:
```javascript
res.should.have.header('content-length');
res.should.have.header('Content-Length', '123');
res.should.have.header('content-length', '123');
```
## json

  Assert that Content-Type is "application/json; charset=utf-8"
```javascript
res.should.be.json
```
## html

  Assert that Content-Type is "text/html; charset=utf-8"
```javascript
res.should.be.html
```
## include(obj)

Assert that the given `obj` is present via `indexOf()`, so this works for strings, arrays, or custom objects implementing indexOf.

Assert array value:
```javascript
[1,2,3].should.include(3)
[1,2,3].should.include(2)
[1,2,3].should.not.include(4)
```
Assert substring:
```javascript
'foo bar baz'.should.include('foo')
'foo bar baz'.should.include('bar')
'foo bar baz'.should.include('baz')
'foo bar baz'.should.not.include('FOO')
```
Assert object includes another object:
```javascript
var tobi = { name: 'Tobi', age: 1 };
var jane = { name: '