#!/usr/bin/env node
var exec = require('child_process').exec,
    util = require('util'),
    fs = require('fs'),
    contents = null,
    branch, desc;

console.log(process.argv);

// expect .git/COMMIT_EDITMSG
if(/COMMIT_EDITMSG/g.test(process.argv[2])){
    // look for current branch name
    branch = exec("git branch | grep '*'",
      function (err, stdout, stderr) {
        if(err){
			// git branch will fail if initial commit has not been done,
			// so we can safely skip this hook
			process.exit(0); 
		}

		// opens .git/COMMIT_EDITMSG
        contents = fs.readFileSync(process.argv[2]);
		
		// trims extra characters from start/end of line
        var name = stdout.replace('* ','').replace('\n','');
		
		// If the branch has a description, pull that
        desc = exec('git config branch.'+ name +'.description',
            function(err, stdout, stderr){
				// don't handle errors (because we write out branch anyway)
                
				// we found a description, add to 'name'
				if(stdout){ name = util.format('%s (%s)', name, stdout.replace(/\n/g,'')); }

				// '(no branch)' indicates we are in a rebase or other non-HEAD scenario
                if(name !== '(no branch)'){
				
					// Append branch name to original contents.
                    contents = util.format('%s\n\n:%s\n', contents, name);
					
					// write contents back out to .git/COMMIT_EDITMSG
                    fs.writeFileSync(process.argv[2], contents);
                    process.exit(0);
                } else {
                    process.exit(0);
                }
        });
    });
}

$ mkdir example
$ cd example
$ git init

$ touch first
$ git add .
$ git commit -m 'Initial commit'

$ touch second
$ git add .
$ git commit -m 'Second commit'

    Second commit
    
    :master

$ git checkout -b ABC-123
$ touch third
$ git add .
$ git commit -m 'Third commit'

    Third commit
    
    :ABC-123

$ git branch --edit-description ABC-123

    Fourth commit
    
    :ABC-123 (Supporting branch for ABC-234 and ABC-567)

var Step = require('step');

Step(
	function first(){
		console.log('first');
		
		this();
	},
	
	function second(){
		var x;
		console.log('second');
		if(!x){
			// do something that should set x
		}
		return x;
	},
	
	function third(){
		console.log('third');
	}
)

$ node step-example.js 
first
second

var async = require('async');

async.series([
	function first(done){
		console.log('first');
		done(null, 'first');
	},
	function second(done){
		var x;
		console.log('second');
		if(!x){
			// do something that should set x
		}
		done(null, x);
	},
	function third(done){
		console.log('third');
		
		done(null, 'third');
	}
], function(err, results){
	console.log(results);
})

first
second
first
third
[ 'first', undefined, 'third' ]

async.waterfall([
	function first(done){
		console.log('first');
		done(null, 'first');
	},
	function second(val, done){
		var x;
		console.log('second has val: %j', val);
		if(!x){
			// do something that should set x
		}
		done(null, x);
	},
	function(val, done){
		console.log('third has val: %j', val);
		
		done(null, 'third');
	}
], function(err, val){
	console.log('callback has val: %j', val)
});

var someFunction = function(){ /* implement */ };
module.exports.someFunction = exports.someFunction = someFunction;

var someFunction = function(){ /* implement */ };
var exports = {};
exports.someFunction = someFuntion;

var count = 0;

var doSomethingShared = function(){
	count += 1;
	console.log("Shared call count: %d", count);
};

var doSomethingNotShared = function(){
	console.log("Other modules don't know about me!");
};

module.exports.shared = exports.shared =  doSomethingShared;
module.exports.unshared = exports.unshared =  doSomethingNotShared;

$ node
> var example = require('./example.js');
undefined
> example.shared()
Shared call count: 1
undefined
> example.shared()
Shared call count: 2
undefined
> example.shared()
Shared call count: 3
undefined
> example.shared()
Shared call count: 4
undefined
> example.unshared()
Other modules don't know about me!
undefined

> var example2 = require('./example.js');
undefined
> example2.shared()
Shared call count: 5
undefined
> example2.shared()
Shared call count: 6
undefined

> var shared = require('./example.js').shared;
undefined
> shared()
Shared call count: 7
undefined
> shared()
Shared call count: 8
undefined

// begin processor.js
var head = require('./head'),
	tail = require('./tail');
	
// don't do this IRL
var callback = null;

var processor = function(file, cb){
	if('function' === typeof cb){
		callback = cb;
	}
	
	// these fail
	head(file, function(d){
		callback(d)
	});
	tail(file, function(d){
		callback(d)
	});
	
	// these succeed
	// head(file, callback);
	// tail(file, callback);
};

module.exports = exports = processor;

var p = require('util').puts;

try {
    var probe = require('canvas');
} catch(e) {
    p("Cannot find node-canvas module.");
    p("Did you install dependencies:\n");
    p("\tnpm install -d");
    process.exit();
}

var fs = require('fs');
var Canvas = require('canvas');
var Image = Canvas.Image;

var canvas, ctx, baseImage, outImage, img;

var init = function() {
	// our working image is 35x35, we want 10x10 sheet of sprites
	canvas = new Canvas(35*10,35*10);
	ctx = canvas.getContext('2d');
	baseImage = __dirname + '/base.png';
	outImage = __dirname + '/markers.png';

	// pre-load the image
	img = new Image;
	img.onload = function() {
		processImage(fileProcessingComplete);
	};
	
	img.src = baseImage;
};

var fileProcessingComplete = function() {
	var out = fs.createWriteStream(outImage),
            stream = canvas.createPNGStream();

	stream.on('data', function(chunk){
	  out.write(chunk);
	});

	// when PNG stream is done, drain WriteStream
	stream.on('end', function(){
	  p('saved ' + outImage);
	  out.destroySoon();
	});
};

var processImage = function(cb) {
        // other code removed
	if(typeof cb === "function") {
		cb.call(this);
	}
}

ctx.font = 'normal 12px Impact';
ctx.textAlign = 'center';
var color = [255, 255, 0, 235];

// use a temp Canvas and Context of 35x35 size.
var tempCanvas = new Canvas(35,35);
var tempCtx = tempCanvas.getContext('2d');

for(var magnitude = 0; magnitude <= 100; magnitude++) {
	var y = 35 * Math.floor(magnitude/10),
		x = ( 35*(magnitude % 10) );

	// This increments the color slightly
	if(magnitude % 5 == 0){
		color[1] = color[1] - 13;
	}

        // some code removed

	ctx.fillText("" + parseFloat(magnitude / 10, 1), x + (35/2), y + (35/2), 35);
}

tempCtx.drawImage(img, 0, 0, 35,35);
var imgData = tempCtx.getImageData(0, 0, 35, 35);
var data = imgData && imgData.data;
if(data) {
	try {
		for(var pixel=0;pixel<data.length;pixel=pixel+4) {
			var red = data[pixel]
			var green = data[pixel+1];
			var blue = data[pixel+2];
			var alpha = data[pixel+3];

			if(red == 255 && green == 255 && blue == 255) {
				data[pixel] = color[0];
				data[pixel+1] = color[1];
				data[pixel+2] = color[2];
				data[pixel+3] = color[3];
			}
		}
	} catch (err) { console.error(err.message); }

	// Write our temp image data to the final canvas context
	/* imageData, dx, dy, sx, sy, sw, sh */
	ctx.putImageData(imgData,x,y,0,0, 35, 35);
}

ctx.putImageData(imgData, 0, 0, 315, 315, 35, 35);

// An object with safe getters/setters for each stream.  
// Streams are:  
// debug, info, error, warn
Log.prototype.streams = {
    get none() { return { write: function() { }}; },
    get debug() { return this._debug; },
    set debug(val) {
        requiresStream(val);
        this._debug = val;
    },
    get info() { return this._info; },
    set info(val) {
        requiresStream(val);
        this._info = val;
    },
    get warn() { return this._warn; },
    set warn(val) { 
        requiresStream(val);
        this._warn = val;
    },
    get error() { return this._error; },
    set error(val) {
        requiresStream(val);
        this._error = val;
    }
}

var Log = module.exports = exports = function Log(level) {
    // default error to stderr and the rest to stdout
    this.streams.debug = process.stdout;
    this.streams.info = process.stdout;
    this.streams.warn = process.stdout;
    this.streams.error = process.stderr;

    // default the logLevel to disabled
    this.logLevel = level || -1;
}

// [DISABLED] else [DEBUG > INFO > WARN > ERROR]
Log.prototype.logLevels = {
    DISABLED:   { value: -1, stream: 'none' },
    DEBUG:      { value: 0, stream: 'debug' },
    INFO:       { value: 1, stream: 'info' },
    WARN:       { value: 2, stream: 'warn' },
    ERROR:      { value: 3, stream: 'error' }
}

// ## log(level msg);
// logs the output with a nice colorful indicator of the stream.  
// `msg` may be a string or a formattable string and options.
Log.prototype.log = function(level, msg) {
    var original = level;
    try {
        if(typeof level === 'string'){
            level = this.logLevels[level.toUpperCase()];
        }
        // get logLevel value
        if( (this.logLevel > -1) && (level.value >= this.logLevel) ) {
            var stream = this.streams[level.stream];
            stream.write( util.format.call(this, '[\033[%sm%s\033[39m]\t', colors[level.value], level.stream) );
            stream.write( util.format.apply(this, slice.call(arguments,1) ) + '\n');
        }
    } catch (err) { 
        console.error("logging is improperly configured!\nIs %j a supported logLevel?\nError:\n%j\n",original, err);
    }
}

var Log = require('./log.js'),
    fs = require('fs');

var level = process.argv[2] || 1;
var logger = new Log(level),
    level = logger.logLevels;

logger.log(level.DEBUG, "This is a debug message");
logger.log(level.INFO, "This is an info message");
logger.log(level.WARN, "This is a warning message");
logger.log(level.ERROR, "This is an error message");

var debugStream = fs.createWriteStream('./debug.txt');
var infoStream = fs.createWriteStream('./info.txt');
var warnStream = fs.createWriteStream('./warn.txt');
var errorStream = fs.createWriteStream('./error.txt');

logger.streams.debug = debugStream;
logger.streams.info = infoStream;
logger.streams.warn = warnStream;
logger.streams.error = errorStream;

logger.log(level.DEBUG, "This is a debug message");
logger.log(level.INFO, "This is an info message");
logger.log(level.WARN, "This is a warning message");
logger.log(level.ERROR, "This is an error message");

debugStream.end();
infoStream.end();
warnStream.end();
errorStream.end();

var Uuid = require('./uuid.node').Uuid;
var uuid = new Uuid();
var myId = uuid.generate();

var template = function() { }

// default package.js for an expressjs app using ejs and uglify-js
{
    "name": "application-name"
  , "version": "0.0.1"
  , "private": true
  , "dependencies": {
      "express": "2.4.6"
    , "ejs": ">=0.4.3"
    , "uglify-js": ">=1.1.0"
  }
}

npm install -d

JS = $(shell find public/javascripts/*.js)
MINIFY = $(JS:.js=.min.js)

all: clean $(MINIFY)

clean:
	rm -f ./public/javascripts/*.min.js

%.min.js: %.js
	node ./node_modules/uglify-js/bin/uglifyjs -o $@ $<

.PHONY: clean js minify

[node.js] Getting started with nodeunit

The following code is part of the testing chapter I previously worked on in my fork of Mastering Node.

Throughout this post, you'll see references to files from a relative directory. If you clone my fork of Mastering Node, these file locations are relative to the root directory of that cloned repository.

For a pretty simple example of real-world testing using nodeunit, check out the initial testing done on my project, brushes.js [?].

---

Testing

Testing is a very large topic. There are different types of testing, each with different methodologies. Then, there are also strong feelings of developers toward which type of testing is the best or most effective.

• Assertion Testing
  • Tests a true or false condition against known objects or values
• Behavioral Testing
  • Tests how one object acts when interacting with another
• Functional/Acceptance Testing
  • "Black box" testing of a system, usually code-agnostic
• Regression Testing
  • Tests for consistency after changes have been made to code
• Others...

There are many other types of testing, but these are some large topics in the testing arena. Development practices include Test-Driven Development (TDD), Behavior-Driven Development, and others. Some programmers don't believe in testing, others believe tests should be written before the code, while others still believe tests should only be written for the most important code. As you can see, this is a large and complex topic.

Whether you write tests before you code, test only the most important code, or casually write tests when there is time, it is important to choose a testing tool that fits your needs.

assert Module

To begin, require the assert module:

var assert = require('assert');

This module exposes a few functions common to assertion testing:

// equality
assert.equal(actual, expected, [message])
assert.notEqual(actual, expected, [message])
assert.deepEqual(actual, expected, [message])
assert.notDeepEqual(actual, expected, [message])
assert.strictEqual(actual, expected, [message])
assert.notStrictEqual(actual, expected, [message])

// exception
assert.throws(block, [error], [message])
assert.doesNotThrow(block, [error], [message])
assert.ifError(value)

// condition
assert.ok(value, [message])
assert.fail(actual, expected, message, operator)

These are pretty self-explanatory if you've written assertion tests before. Let's look at a pretty simple test, anyway. We'll code in an object for the test that will do what we want for each test.

Synchronous Testing with Assert

// testing/equality_no_errors.js
var assert = require('assert'),
    tester_a = {
      val : 'a'
    },  
    tester_b = {
      val : 'b'
    };

assert.equal(tester_a.val, 'a');
assert.equal(tester_b.val, 'b');

In this example, we're using the assert module to check that a value on each of these objects is the expected value. This works well because the values are equal. But, the assert module throws an AssertionError whenever an assertion fails. So, it doesn't really make sense to have a single file with end-to-end assertions as in the ./src/testing/equality_no_errors.js file. This is where testing frameworks like nodeunit or expresso come in very handy. They offer common functionality of test frameworks (like metrics, etc.).

To see how the AssertionError being thrown from assert.equal can be problematic, change the expected value in the first test to an incorrect value. Then, change the expected value in the very last test to an incorrect value and run node src/testing/equality_no_errors.js again. You'll see that, because of the procedural style of the code, the last test never runs!

In order to run multiple assertions and provide feedback, the simplest test (without a testing framework) would use a try/catch and provide output to stdout.

// testing/equality_with_errors.js
var assert = require('assert'),
    tester_a = {
      val : 'aa'
    }, total = 0, good = 0;

// assert.equal(actual, expected, [message])
try {
    console.log("assert.equal(tester_a.val, 'a')");
    assert.equal(tester_a.val, 'a');
    passed();
} catch (err) { writeException(err); }

console.log("%d of %d tests passed", good, total);

function writeException(err) {
    console.log("Test failed!");
    util.inspect(err);
    if(err["name"] === "AssertionError") {
        console.log("Message: " + (err["message"] || "None"));
        console.log("Expected: " + err["expected"]);
        console.log("Actual: " + err["actual"]);
        console.log("Operation: " + err["operator"]);
    }
    console.log("");
    total = total + 1;
}

function passed() {
    good = good + 1;
    total = total + 1;
    console.log("Test passed!\n");
}

The above code is part of the code from within ./src/testing/equality_with_errors.js. It shows how to run synchronous tests with a minimal amount of redundant code, without writing a lightweight testing module for your tests. This may be what you want, but most likely it isn't.

The problems

You could write a simple helper module to run these tests for you. But, how do you verify the order of your tests? This can become complex very quickly.

You can partially resolve this with the try/catch block example above, but this requires a lot of redundant code. Compare ./src/testing/equality_with_errors.js and ./src/testing/equality_no_errors.js to see how the testing quickly expands! Run node testing/equality_with_errors.js to see the output. That's more like it! Isn't that nice?

Yes and no. There are a few problems with this code:

1. It isn't evented
2. It hard-codes test objects
3. It is very redundant
4. It isn't scalable

Well, then, what are other options?

Nodeunit

Nodeunit is a framework similar to nunit in that it allows for multiple test cases (running in parallel), and supports mocks and stubs. It is easy to use, and even allows you to run tests in the browser.

Nodeunit testing starts with exporting a test or two from a module.

// testing/nodeunit_basics.js
module.exports = {
    'Test 1' : function(test) {
        test.expect(1);
        test.ok(true, "This shouldn't fail");
        test.done();
    },
    'Test 2' : function(test) {
        test.expect(2);
        test.ok(1 === 1, "This shouldn't fail");
        test.ok(false, "This should fail");
        test.done();
    }
};

Here, we have a module exporting two tests, Test 1 and Test 2. You may have noticed that the test object in the functions have an ok() method just like the assert module mentioned above. Good eye. In fact, test supports all of the assert functions and adds two others: expect(number) and done(). The expect function tells nodeunit how many tests are being run within the context of the current test case. When all tests are finished, call test.done() to let nodeunit know the test case has completed (and a callback may have failed).

The output of nodeunit is visually helpful.

$ nodeunit src/testing/nodeunit_basics.js 

nodeunit_basics.js
✔ Test 1
✖ Test 2

Assertion Message: This should fail
AssertionError: false == true
    at Object.ok (/usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/types.js:81:39)
    at /home/jim/projects/masteringnode/src/testing/nodeunit_basics.js:10:14
    at Object.runTest (/usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/core.js:54:9)
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/core.js:90:21
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:508:13
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:118:25
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:129:25
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:510:17
    at Array.<anonymous> (/usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/types.js:144:17)
    at EventEmitter._tickCallback (node.js:108:26)


FAILURES: 1/3 assertions failed (8ms)

Nodeunit will list all test cases run within the test, followed by any AssertionError output and the number of passing or failing assertions. This is the default (minimal) output.

Nodeunit reporters

Nodeunit ships with a number of reporters and it is possible to add custom reporters.

$ nodeunit --list-reporters
Build-in reporters: 
  * default: Default tests reporter
  * minimal: Pretty minimal output
  * junit: jUnit XML test reports
  * html: Report tests result as HTML
  * skip_passed: Skip passed tests output
  * browser: Browser-based test reporter

To output to junit, run the command as:

$ cd src/testing && nodeunit --reporter junit nodeunit_basics.js --output junit.out

This creates an xml file (whitespace has been condensed):

   // testing/junit.out/nodeunit_basics.js.xml
   <?xml version="1.0" encoding="UTF-8" ?>
    <testsuite name="nodeunit_basics.js"
             errors="0"
             failures="0"
             tests="2">
      <testcase name="Test 1">
      </testcase>
      <testcase name="Test 2">
      </testcase>
    </testsuite>

This is great, but in a real-world development environment, you may be asked to write reports with a specific format, wording, or links (in html) to files with failing test cases. Luckily, nodeunit allows us to customize this output.

Nodeunit Custom reporters

To write a custom reporter for nodeunit, first decide how you'd like nodeunit to report information about your tests. As a simple example, let's take a look at a different take on the minimal reporter.

Here are the modifications I'd like to see:

• Show the start time of the test
• Show the filename as bold/green
• Add [PASS] or [FAIL] after the ✔ or ✖
• Prefix a test case with a '|'

These may seem like contrived requirements. But, what if my manager wants me to parse textual output for [FAIL] and, for whatever reason, it has to say [FAIL]?

The modifications to the minimal reporter are too spread out to include inline here, so be sure to check out the file at ./src/testing/reporterse/example.js.

Here is the slightly modified minimal output, meeting all of the requirements.

$ cd src/testing && nodeunit --reporter reporters/example.js nodeunit_basics.js 
Tests started: Tue Mar 22 2011 21:24:42 GMT-0700 (PDT)
nodeunit_basics.js: 

✔ [PASS] | Test 1
✖ [FAIL] | Test 2


AssertionError: false == true
    at Object.ok (/usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/types.js:81:39)
    at /home/jim/projects/masteringnode/src/testing/nodeunit_basics.js:10:14
    at Object.runTest (/usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/core.js:54:9)
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/core.js:90:21
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:508:13
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:118:25
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:129:25
    at /usr/local/lib/node/.npm/nodeunit/0.5.1/package/deps/async.js:510:17
    at Array.<anonymous> (/usr/local/lib/node/.npm/nodeunit/0.5.1/package/lib/types.js:144:17)
    at EventEmitter._tickCallback (node.js:108:26)


FAILURES: 1/3 assertions failed (9ms)

These were small modifications, but following through the reporters included in nodeunit, it will be easy to output test reports to your desired format.