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

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

examine.subject(handler)

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.

examine.assert and examine.expect

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

try-catch

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:

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

Does throw still work as expected if I use this package?

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.

Are you using process.on('uncaughtException', handle) to caught the thrown errors?

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

Is this black magic?

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

Where is should style?

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