ghoulies

ghoulies is a full-stack JavaScript integration test runner that allows you to run a NodeJS server, and a JavaScript client in the same unit test and write BDD-style integration tests in a simple and natural way.

ghoulies works by spawning a headless JSDom pointed to your development NodeJS server application. The client-side API ghoulie exposes an event emitter that can be listened to in your server-side tests.

So far, ghoulies has only been used alongside webpack (to build the app) and mocha/chai (for running the tests) but should work with other JavaScript test and build systems. Ghoulies may also be useful for those not even using Node, but are interested in using mocha/jasmine/jest for their client-side integration tests.

Installation

---

Prerequisites

Install your test and build systems (mocha, chai, webpack etc.):

npm install mocha --save
npm install chai --save
npm install webpack --save -g

Install nodemon to watch for file changes:

npm install nodemon --save -g

Install

Install both ghoulies (server-side interface) and ghoulie (client-side interface):

npm install ghoulies --save
npm install ghoulie --save

Set Up Your Unit Test (Using Mocha)

---

Make a directory specifically for ghoulie tests:

mkdir /test/ghoulie

Create a new unit test script (eg. /test/ghoulies/myghoulie.test.js):

var chai = require('chai');
var expect = chai.expect;

// include ghoulies
var ghoulies = require('ghoulies');

// url of your local development server
var url = "http://localhost:1337";

before(function (done) {	
	 ghoulies.client({
		url: url,
		globals: true,		// make window, document, and jquery global objects
		jquery: true		// (optional) include jquery if it isn't included in the app
	}, function (window, ghoulie) {
		done();
	});
});

describe('ghoulies', () => {
	it('loads a headless client and renders my application', (done) => {
	
		// ghoulies exposes a headless browser window object
		expect(typeof window).to.be.equal('object');
		
		// see if it loaded the app successfully
		console.log(document.body.innerHTML);
		
		// use jQuery to inspect the dom
		var myAppNode = $('#myapp');
		expect(myAppNode.length).to.be.equal(1);
		expect(myAppNode.get(0)].nodeName).to.be.equal('DIV');
		
		// initialize ghoulie at the end of the first test
		ghoulie.init();
		
		done();
	});
});

As configured above, the ghoulies.client() method will instantiate an instance of JSDom and load the entire contents of your web application running on http://localhost:1337

In a ghoulie test you can use JQuery or standard DOM operations to just as you would in a browser. It also exposes an API for emitting events and listening for events used by your unit tests.

Server-Side Setup

---

Ghoulies requires your webserver be fully booted and ready to go before the test proceeds. Ghoulies also exposes an EventEmitter to capture when the server is loaded.

If using ExpressJS, emit an event after the http server is running:

var express = require('express');
var app = express();

// include ghoulies
var ghoulies = require('ghoulies');

app.listen(8000, function () {
	
	// emit server event
	ghoulies.emit('SERVER_LOADED', app);

});

Create a unit test bootstrap script named /test/ghoulies/config.js, it listens for the 'SERVER_LOADED' event before continuing with the rest of the test suite:

before(function(done) {
	ghoulies.once('SERVER_LOADED', function(app) {
		// store a reference to the app for use in the tests
		ghoulies.app = app;		
		done();
	});
});

Client-To-Server Events

---

The client-side API is exposed by the ghoulie npm module. Your client-side application will need to include this module and emit events after important actions take place (eg. after data is loaded or a portion of your app is rendered). The unit tests use ghoulies to spawn the client browser and listen to the events emitted by ghoulie.

Somewhere in your JavaScript client-side code emit a client event:

// include ghoulie
var ghoulie = require('ghoulie');

// emit client event
var arg1 = 123;
var arg2 = "abc";
ghoulie.emit('CLIENT_LOADED', arg1, arg2);

Then add an event listener in your unit test /test/ghoulies/myghoulie.test.js to listen for the 'CLIENT_LOADED' event:

define("a ghoulie test", function() {
	it("listens for client events", function(done) {
		
		// wait for client event
		ghoulie.once('CLIENT_LOADED', function()arg1, arg2, ...) {
			
			// output useful data in the terminal
			ghoulie.log('CLIENT_LOADED!', arg1, arg2);
			
			expect(arg1).to.be.equal(123);
			expect(arg2).to.be.equal("abc");
			
			done();
		});
		
		// initialize ghoulie at the end of the first test
		ghoulie.init();
	
	});
});

Server-to-Client Events

---

You can also emit events from within a ghoulie test and have your client listen and respond to them. In this manner you can force the client to reload data from the server, render a new part of the application, or some other action:

Somewhere in your unit test, emit an event:

ghoulie.emit('RELOAD_SOME_DATA');

Somewhere in your client app, listen to the event:

ghoulie.once('RELOAD_SOME_DATA', function() {
	
	// fetch data from server
	$.ajax({url: "/api/data", success: function(result) {
        
        // emit new event
        ghoulie.emit('RELOADED_DATA', result);
        
    }});
	
});

Update your unit test to listen to the 'RELOADED_DATA' event:

ghoulie.on('RELOADED_DATA', function(result) {
	
	// perform test on the data
	expect(typeof result).to.be.equal('object');
	
	// can also perform DOM/JQuery commands to see if client rendered the new data
	$(...)
});

Ghoulies NPM Commands

---

The ghoulies npm commands are:

npm run ghoulies          # runs the build, then runs the tests

npm run ghoulies:build    # bundles your client app (eg. webpack/gulp)

npm run ghoulies:test     # runs your tests (eg. mocha/jasmine)

npm run ghoulies:watch    # runs your tests and watch for changes (nodemon)

These commands will need to be manually added to your project's package.json and modified accordingly depending on your build and test systems.

This example is for webpack and mocha:

...
	"scripts": {
		...
		"ghoulies": "npm run ghoulies:build; npm run ghoulies:test",
		"ghoulies:test": "NODE_ENV=test mocha --timeout 60000 --recursive ./test/ghoulies/config.js ./test/ghoulies",
		"ghoulies:watch": "npm run ghoulies:build; NODE_ENV=test nodemon -w ./test/ghoulies -e js -x npm run ghoulies:test",
		"ghoulies:build": "NODE_ENV=test node node_modules/webpack/bin/webpack.js -p --progress"
	}
...

It is recommended to experiment with running ghoulies:build and ghoulies:test independently and be sure they work properly before trying ghoulies and ghoulies:watch

Examples

---

The best example to date of a ghoulie test is the one supplied in the sails-react-redux-boilerplate example application which uses SailsJS server, ReactJS client, webpack build, and mocha tests.

See: https://github.com/jaxcore/sails-react-redux-boilerplate/blob/master/test/ghoulies/todos.test.js

To-do

---

• console/REPL client

• listen to react/redux events

• command line interface

• stand alone example app (simple expressjs example)

• experiment with multiple client instances