examine


examine is a utility module that provides a powerful yet simple API to assert code in production.
Using an assertion framework wrapped inside this package you will be able
to use the assertion framework APIs without the fear of uncaught exceptions.

Errors thrown by the assert and expect APIs are caught and handled by the callback you bind to examine.

Imagine a big invisible and smart try-catch block wrapped around your app that only catches specific errors. That's what this is.

Quick Example

``js
var examine = new Examine()
var assert = examine.assert

function errorHandler (err) {
console.log('Caught it!', err)
}

examine.subject(errorHandler)

var string = 'Hello :)'

assert.typeOf(string, 'boolean')

console.log('This wont be executed')
`

API

$3


Bind a handler to the examine instance.
The handler will be called when an error is thrown from the .expect or .assert APIs and it can
be switched during the execution order.

$3

The assert and the expect APIs belong to the assertion library chai.js. They have a very good documentation if you don't know how to use these APIs.

Known Pitfalls

$3

If you use a try-catch block be careful to not put a examine expect/assert statement inside it, because it
can have behaviour that is not wanted.
If you do the error that is thrown will be caught by the try-catch block and the subject handler won't be called.

Take the following example:

`js
var examine = new Examine()
var assert = examine.assert

function errorHandler (err) {
console.log('This wont be called')
}

examine.subject(errorHandler)

try {
assert.ok(null)
} catch (e) {
console.log('Caught it here!', e)
}

`

Questions

$3


Of course yes, the only throws that are caught and handled are the examine errors, everything else that you throw is your responsibility to
catch it.

$3

No, and you can still use it without affecting the functionality of this package.

$3

I don't consider this to be black magic, just a clever hack. You can see the source of the mystery here.

$3

should is not supported because of the following reasons:
- It is considered bad practice to modify the prototype of String, Object, Number, Boolean, etc.
- It is not possible to know which subject handler that should be called

TODO

- Finish assert and expect` APIs tests
- Add some practical examples

License

MIT