So this is the situation, I have a project using gulp and the build tasks are increasingly getting complex and hard to maintain. These command line tools are written by me in JavaScript and I want a way of testing their command line API, similarly of how I write other source code unit test.
Before proceed, all the source code explained in this document is maintained here
https://github.com/cancerberoSgx/javascript-sample-projects/tree/master/gulp-test-setup-shelljs-jasmine
In particular, I want to write jasmine code with specs that call the command line tools and then assert if folders/files are created, etc. So I will use jasmine as the unit test framework and shelljs for easy filesystem operations & assertations.
So suppose you have a project with build system written with gulp or grunt, npm (or whatever) and you want to write a jasmine unit test that runs these tasks and make assertations. Then users can launch unit tests calling npm test on your app.
First we install jasmine and shelljs in your project:
npm install jasmine --save-dev
npm install shelljs --save-dev
Now let's generate the jasmine unit tests with the following command. This will generate the folder spec in which we will store our tests:
node node_modules/jasmine/bin/jasmine.js init
Now let's create the file specs/buildSpec.js with the following content.
require('shelljs/global');
describe("test the build", function()
{
it("npm install", function()
{
rm('-rf', 'node_modules');
expect(test('-d', 'node_modules')).toBe(false);
expect(exec('npm install', {silent:true}).code).toBe(0);
expect(test('-d', 'node_modules')).toBe(true);
});
it("gulp sass", function()
{
rm('-rf', 'dist');
expect(test('-d', 'dist')).toBe(false);
expect(exec('gulp sass', {silent:true}).code).toBe(0);
expect(test('-f', 'dist/main.css')).toBe(true);
});
it("gulp src", function()
{
rm('-rf', 'dist');
expect(test('-d', 'dist')).toBe(false);
expect(exec('gulp src', {silent:true}).code).toBe(0);
expect(test('-f', 'dist/all.js')).toBe(true);
});
});
This test only make sense in my application, you should write your own. I will use it only as an example.
As you can see it is a jasmine spec with three it(), the first checks if the command 'npm install' works, the second if the task 'gulp sass' works and the third if 'gulp src' works.
npm install: here the test first removes the folder node_module, then executes the command 'npm install' and then checks that the folder node_modules exists.
gulp sass: here the test removes the 'dist' folder, then executes the command 'gulp sass' and then makes sure the file dist/main.css was generated. gulp src is very similar.
Appendix: asserting if a server is turned on.
In my application, there is a command 'gulp connect' that will start a local server hosting the application. For testing this I use the following code.
It basically perform the following checks:
- check that the port 8080 is free
- run the command 'gulp connect' asynchronously.
- wait for two seconds (time to start),
- check that the http port 8080 is used,
- kill the server 6) and then checks that the port 8080 is free. Before killing a handler optionally given by the user is called so he can do some assertations over served resources (in my case using curl())
I tried to define a reusable and jasmine-agnostic function for testing all this automatically and assert something before killing the server. Unfortunately there are some hardcoded timeouts and have a asynchronous syntax so it might be hard to understand.
Notice how I have handcrafted an utility assertCommandOpenPort that performs all these work and a curl() function to assert on url resources.
require('shelljs/global');
describe('gulp connect', function()
{
it('gulp connect should serve index at 8080', function(done)
{
console.log('gulp connect should serve index at 8080');
assertCommandOpenPort({
cmd: 'gulp connect'
, port:8080
, timeout:2000
, predicate: function(val, msg)
{
if(!val)
{
expect('gulp connect fail: '+msg).toBe(false);
}
}
, testBeforeKill: function(done)
{
curl({
host: 'localhost'
, port: 8080
, path: '/'
, dataHandler: function(data, res)
{
expect(data.indexOf('</html>') !== -1).toBe(true);
done();
}
, errorHandler: function()
{
expect('html served').toBe(true);
done();
}
});
}
, done: done
});
});
});
// general utility for testing that a executing a command open a certain port. What it does:
// 0) assert port is free 1) assert port is unused 2) run the command 3) assert port is used 4) kill the command 5) assert the port is free.
// I promise I tried to write the async part the easier I could....
function assertCommandOpenPort(config)
{
var port = config.port
, predicate = config.predicate
, timeout = config.timeout || 2000;
isPortTaken(port, function(isUsed)
{
predicate(!isUsed, 'step 1 port taken initially');
});
var childProcess = exec(config.cmd, {silent: true, async: true});
setTimeout(function()
{
isPortTaken(port, function(isUsed)
{
predicate(isUsed, 'step 2 port not taken');
config.testBeforeKill(function()
{
childProcess.kill();
setTimeout(function() // hack: give some time to the killing
{
isPortTaken(port, function(isUsed)
{
predicate(!isUsed, 'step 3 port not free');
config.done();
});
}, 50);
});
});
}, timeout); // ugly hack: wait until server is up
}
// Utility used by assertCommandOpenPort to know if a port is currently used. Used by assertCommandOpenPort.
// Usage: isPortTaken(8080, function(isUsed){})
function isPortTaken(port, fn)
{
var net = require('net')
var tester = net.createServer()
.once('error', function (err)
{
if (err.code != 'EADDRINUSE')
{
return fn(false);
}
fn(true);
})
.once('listening', function()
{
tester.once('close', function() { fn(false); })
.close()
})
.listen(port)
}
function curl(config)
{
var http = require('http');
var options = {
host: config.host
, path: config.path || '/'
, port: config.port || 80
};
var request = http.request(options, function (res)
{
var data = '';
res.on('data', function (chunk)
{
data += chunk;
});
res.on('end', function ()
{
config.dataHandler && config.dataHandler(data, res);
});
});
request.on('error', function (e)
{
config.errorHandler && config.errorHandler(e);
});
request.end();
}
