lazy-ass-helpful

lazy-ass plugin to automatically show helpful info for failed assertions

Test page, test page BDD (mocha)

Stop writing assertion messages, let the automatic on the fly code rewriting put the entire expression into the text message.

This package provides single function lazyAssHelpful that transforms any given function with lazy-ass assertions into another function. If any lazy assertion fails, it will help its expression in the error message.

Example:

Typical code with assertions requires lots of extra stuff to be helpful, if the condition is false.

function doSomething(a) {
  lazyAss(typeof a === 'number', 'a should be a number', a);
  ...
}
doSomething('foo'); // Error: a shoud be a number 'foo'

lazy-ass-helpful allows you to skip writing text explanations in assertions

function doSomething(a) {
  lazyAss(typeof a === 'number', a);
  ...
}
lazyAssHelpful(doSomething)('foo'); // Error: condition [typeof a === "number"] 'foo'

install and use

node:

npm install lazy-ass-helpful --save
require('lazy-ass-helpful');

browser:

bower install lazy-ass-helpful --save
<script src="bower_components/lazy-ass-helpful-browser.js"></script>

use:

function foo() {
  lazyAss(2 + 2 === 5);
}
var helpfulFoo = lazyAssHelpful(foo);
foo(); // Error: failed
helpfulFoo(); // Error: condition [2 + 2 === 5]

Auto variables

lazyAssHelpful not only places the expression into the message, it also parses the expression and puts all variables into the message (if they are defined and not functions)

function bar() {
  var foo = 'something';
  lazyAss(foo === 'nothing');
}
var barHelped = lazyAssHelpful(bar);
barHelped();
// throws
// Error: condition [foo === "nothing"] foo: something

Limitation

Because lazyAssHelpful rewrites and evals the given function, it no longer can access the closure variables directly. Only global variables or local variables are allowed

// local variables are ok
function foo() {
  var bar = 'bar';
  lazyAss(bar === 'something');
}
lazyAssHelpful(foo)();
// global variables are ok
window.bar = 'bar';
function foo() {
  lazyAss(window.bar === 'something');
}
lazyAssHelpful(foo)();
// closure variables are NOT ok
bar bar = 'bar';
function foo() {
  lazyAss(bar === 'something');
}
lazyAssHelpful(foo)(); // ReferenceError: bar is undefined

lazy-ass-helpful-bdd

I include lazy-ass-helpful-bdd.js that wraps the common BDD functions describe and it into helpDescribe and helpIt. These functions transform the unit test code using lazyAssHelpful method.

Typical setup:

<script src="node_modules/mocha/mocha.js"></script>
<script>mocha.setup('bdd')</script> 
<script src="node_modules/lazy-ass/index.js"></script>
<script src="lazy-ass-helpful-browser.js"></script>
<script src="lazy-ass-helpful-bdd.js"></script>
<script src="test/test-bdd.js"></script>
<script>
  mocha.run();
</script> 

The write unit test wrapped in helpDescribe function using lazyAss assertions. If an assertion fails, there will be helpful context.

I also have same project optimized for QUnit assertions rewriting, see qunit-helpful

How?

lazyAssHelpful rewrites the given function using falafel, and then returns a new function with every lazyAss(condition, ...) replaced with lazyAss(condition, 'condition source', ...).

Small print

Author: Gleb Bahmutov © 2014 @bahmutov

License: MIT - do anything with the code, but don't blame me if it does not work.

Support: if you find any problems with this module, email / tweet / open issue on Github