A brief introduction to Test Driven Developement (TDD) in JavaScript for people who want write more reliable code.
A project without tests often ends up looking like its stuck together with duck tape ...
Change one part and the other stops working? "Fixing" one bug, creates another?
Would you prefer if everything was consistent and beautifully integrated?
What if everyone on your team worked in a disciplined order... like a Formula 1 Crew ...
Test Driven Development (TDD) makes your team a well-oiled machine which means you can go faster.
Once you have a suite of tests that run on every change, you will begin to develop a whole other level of confidence in your codebase and will discover a new freedom to be creative without fear of "breaking" anything else; truly game-changing.
This tutorial will help you get started with Test Driven Development (TDD) today!
In the next 30 minutes you will learn everything1 you need to know to write tests for your web project!
- A computer with a web browser
- Internet access to download the starter files
- 30 minutes of time
- Basic Programming Skills (HTML & JavaScript)
- (Optional) Bonus Levels require you to install Node.js
The first thing you need to understand is that writing code following TDD (discipline) is a (slightly) different approach from simply diving into solving the problem (without a test).
When reading about TDD you will see the expression: "Red, Green, Refactor":
What this means is that there's a 3-step process:
-
Write a Failing Test - Understand the (user) requirements/story well enough to write a test for what you expect. (the test should fail initially - hence it being "Red")
-
Make the (failing) Test Pass - Write (only) the code you need to make the (failing) test pass, while ensuring your existing/previous tests all still pass (no regressions).
-
Refactor the code you wrote - if you have time to tidy up the code you wrote to make it simpler (for your future self or colleagues to undersand) before you need to ship the current feature, do it.
To develop the habit(s) you will need to be successful with TDD (and software engineering in general) we need to write a test first (and watch it fail) and then write the code required to make the test pass.
Writing a failing test, before writing the code may seem counter-intuitive, time consuming or even "tedious" at first. But we urge you to think of it this way:
The test is the question you are asking
your code is the answer to the question.
By having a clear question, you can always check that your code is working,
because it consistently gives you the same answer(s) ... no surprises, even when you're working with a large, inter-dependent code base!
Imagine you are building a Vending Machine that allows people to buy any item. The machine accepts coins and calculates the change to be returned to the customer given the price of the Item and the cash received.
We can build the entire "project" in a single file: index.html
Create a directory on your computer called vending-machine:
In your terminal type this command:
mkdir vending-machine && cd vending-machine
(this will create the directory and move you into it)
Next create a file called index.html e.g: atom index.html
(which creates and opens the file in the Atom text editor if you have it installed)
Now copy-paste the following sample code to get started:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Vending Machine Change Calculator TDD Tutorial</title>
<!-- Load the QUnit CSS file from CDN - Require to display our tests attractively -->
<link rel="stylesheet" href="https://code.jquery.com/qunit/qunit-1.18.0.css">
<!-- Pure CSS is a minimalist CSS file we have included to make things look nicer -->
<link rel="stylesheet" href="http://yui.yahooapis.com/pure/0.6.0/pure-min.css">
</head>
<body style='margin: 0 1em;'>
<div id='main'>
<h1>Vending Machine <em>Change Calculator</em></h1>
<h3>Calculate the change (<em>coins</em>) to return to a customer when they buy something.</h2>
</div>
<div id="qunit"></div>
<div id="qunit-fixture"></div>
<!-- QUnit does not depend on JQUery, but we are using it later so load from CDN -->
<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
<!-- Load the QUnit Testing Framework from CDN - this is the important bit ... -->
<script src="https://code.jquery.com/qunit/qunit-1.18.0.js"></script>
<script>
// This is what a simple unit test looks like:
test('This sample test should always pass!', function(assert) {
var result = 1 + 1;
assert.equal(result, 2); // just so we know everything loaded ok
});
// A failing test will be RED:
test('This is what a failing test looks like!', function(assert) {
var result = [1,2,3].indexOf(1); // this should be 1
assert.equal(result, -1); // we *expect* this to fail
});
</script>
</body>
</html>
When you open index.html
in your web browser
you should expect to see something like this: (without the annotations)
There is quite a lot of code in the index.html you just created, lets step through it to understand the parts:
The first part of index.html is a standard HTML head and body:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Vending Machine Change Calculator TDD</title>
<!-- Load the QUnit CSS file from CDN - Require to display our tests attractively -->
<link rel="stylesheet" href="https://code.jquery.com/qunit/qunit-1.18.0.css">
<!-- Pure CSS is a minimalist CSS file we have included to make things look nicer -->
<link rel="stylesheet" href="http://yui.yahooapis.com/pure/0.6.0/pure-min.css">
</head>
<body>
<div id='main'>
<h1>Vending Machine Change Calculator</h1>
<h2>Calculate the Change for a Given Price and Cash Received</h2>
</div>
Nothing special here, we are simply setting up the page and loading the CSS files.
Next we see the qunit divs (where the test results will be displayed) and load JQuery and the QUnit Library from CDN:
<div id="qunit"></div>
<div id="qunit-fixture"></div>
<!-- QUnit does not depend on JQUery, but we are using it so load from CDN -->
<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
<!-- Load the QUnit Library from CDN - this is the important bit ... -->
<script src="https://code.jquery.com/qunit/qunit-1.18.0.js"></script>
Finally we see our test(s) - the interesting part of the file:
<script>
// This is what a simple unit test looks like:
test('This sample test should always pass!', function(assert) {
var result = 1 + 1;
assert.equal(result, 2);
});
// A failing test will be RED:
test('This is what a failing test looks like!', function(assert) {
var result = [1,2,3].indexOf(1); // this should be 1
assert.equal(result, -1); // we *expect* this to fail
});
</script>
</body>
</html>
If you are completely new to writing test assertions, don't worry, they are really simple, there are 3 parts:
- Description - usually the first parameter to QUnit's test() method.
- Computation - execute a function/method (exercising the method you will write to solve your test)
- Assertion - check that the result of your calculation is what you expect it to be.
In the above screenshot, the assertion is assert.equal(result, 2)
We are giving the equal
method two arguments; the result
of our computation
and our expected value in this case 2. That's it.
- Test assertion: https://en.wikipedia.org/wiki/Test_assertion
- What are Test Assertions and how do they work: http://www.thoughtworks.com/insights/blog/test-assertions-how-do-they-work
Given a Price and amount of Cash from Customer Return: Change to customer (in notes and coins).
Essentially we are building a simple calculator that only does subtraction (Price - Cash = Change), but also splits the result into the various coins.
- Create a
function
calledgetChange
that accepts two parameters:totalPayable
andcashPaid
- For a given
totalPayable
(the total amount a item in the vending machine costs) andcashPaid
(the amount of cash the person paid into the vending machine),getChange
should calculate the change we need to return to the customer - return change as an
array
of coins (largest to smallest) that the vending machine will need to dispense to the customer.
If a person buys an item costing £2.15 (we represent this as 215 pennies totalPayable
)
and pays £3 (3 x £1 or 300 pennies cashPaid
) into the vending machine, the change will be 85p.
To make up this 85p of change we would return four coins to the person: 50p, 20p, 10p and 5p.
An array of these coins would look like: [50, 20, 10, 5]
In the UK we have the following Coins:
If we use the penny as the unit (i.e. 100 pennies in a pound) the coins can be represented as:
- 200 (£2)
- 100 (£1)
- 50 (50p)
- 20 (20p)
- 10 (10p)
- 5 (5p)
- 2 (2p)
- 1 (1p)
this can be stored as an Array:
var coins = [200, 100, 50, 20, 10, 5, 2, 1];
Note: the same can be done for any other cash system ($ ¥ €) simply use the cent, sen or rin as the unit and scale up notes.
If you are totally new to TDD I recommend reading this intro article by Scott Ambler (especially the diagrams) otherwise this (test-fail-code-pass) process may seem strange ...
In Test First Development (TFD) we write a test first and then write the code that makes the test pass.
So, back in our index.html file remove the dummy tests and add the following lines:
test('getChange(1,1) should equal [] - an empty array', function(assert) {
var result = getChange(1, 1); //no change/coins just an empty array
var expected = [];
assert.deepEqual(result, expected);
}); // use deepEqual for arrays see: https://api.qunitjs.com/deepEqual/
We use QUnit's deepEqual
(assert) method to check that all the elements
in the two arrays are identical. see: https://api.qunitjs.com/deepEqual/
Back in your browser window, refresh the browser and watch it fail:
Q: Why deliberately write a test we know is going to fail...?
A: To get used to the idea of only writing the code required to pass the current (failing) test.
In your index.html file add the following code (above the tests)
<script>
function getChange (totalPayable, cashPaid) {
var change = [];
// your code goes here
return change;
};
</script>
your index.html
should now look like this:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Vending Machine Change Calculator TDD</title>
<link rel="stylesheet" href="https://code.jquery.com/qunit/qunit-1.18.0.css">
<link rel="stylesheet" href="http://yui.yahooapis.com/pure/0.6.0/pure-min.css">
</head>
<body>
<div id='main' style='padding: 2em;'>
<h1>Vending Machine Change Calculator</h1>
<h2>Calculate the Change for a Given Price and Cash Received</h2>
<!-- <input type='text' id='price'> </input> -->
</div>
<div id="qunit"></div>
<div id="qunit-fixture"></div>
<script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
<script src="https://code.jquery.com/qunit/qunit-1.18.0.js"></script>
<script>
var getChange = function (totalPayable, cashPaid) {
'use strict';
var change = [];
return change
};
</script>
<script>
test('getChange(1,1) should equal [] - an empty array', function() {
var result = getChange(1, 1); //no change/coins just an empty array
var expected = [];
assert.deepEqual(result, expected);
}); // use deepEqual for arrays see: https://api.qunitjs.com/deepEqual/
</script>
</body>
</html>
It Passed!!
Going back to the requirements, we need our getChange method to accept two arguments/parameters (totalPayable and cashPaid) and return an array containing the coins equal to the difference:
e.g:
totalPayable = 215 // £2.15
cashPaid = 300 // £3.00
dfference = 85 // 85p
change = [50,20,10,5] // 50p, 20p, 10p, 5p
Add the following test to tests section of index.html
:
test('getChange(215, 300) should return [50, 20, 10, 5]', function(assert) {
var result = getChange(215, 300); // expect an array containing [50,20,10,5]
var expected = [50, 20, 10, 5];
assert.deepEqual(result, expected);
})
What if I cheat?
function getChange (totalPayable, cashPaid) {
return [50, 20, 10, 5]; // just "enough to pass the failing test"
};
This will pass, but do you have hard coded the result (not exactly a calculator...)
This only works once. When the Spec (Test) Writer writes the next test, the method will need to be re-written to satisfy it.
Lets try it. Work out what you expect so you can write your test:
totalPayable = 486 // £4.86
cashPaid = 600 // £6.00
dfference = 114 // £1.14
change = [100,10,2,2] // £1, 10p, 2p, 2p
Add the following test to index.html
and refresh your browser:
test('getChange(486, 600) should equal [100, 10, 2, 2]', function(assert) {
var result = getChange(486, 600);
var expected = [500, 10, 2, 2];
assert.deepEqual(result, expected);
})
We could keep cheating by writing a series of if statements:
function getChange (totalPayable, cashPaid) {
if(totalPayable == 486 && cashPaid == 600)
return [100, 10, 2, 2];
else if(totalPayable == 215 && cashPaid == 300)
return [50, 20, 10, 5];
};
The Arthur Andersen Approach gets results in the short run ...
But its arguably more work than simply solving the problem. Lets do that instead.
Try to create your own
getChange
method that passes the two tests before you look at the solution...
to re-cap these are our two tests:
test('getChange(215, 300) should return [50, 20, 10, 5]', function(assert) {
var result = getChange(215, 300); // expect an array containing [50,20,10,5]
var expected = [50, 20, 10, 5];
assert.deepEqual(result, expected);
});
test('getChange(486, 500) should equal [100, 10, 2, 2]', function(assert) {
var result = getChange(486, 600);
var expected = [100, 10, 2, 2];
assert.deepEqual(result, expected);
});
Lets invent a test that will return one of each of the coins ...
Recall that we have 8 coins:
var coins = [200, 100, 50, 20, 10, 5, 2, 1];
The sum of the (array containing one of each) coins is: 388p
So, we need to create a test in which we pay £4 for an item costing 12p
(a bit un-realistic but if it works we know our getChange
method is ready!)
test('getChange(12, 400) should return [200, 100, 50, 20, 10, 5, 2, 1]', function(assert) {
var result = getChange(12, 400);
var expected = [200, 100, 50, 20, 10, 5, 2, 1];
assert.deepEqual(result, expected);
});
When these tests pass, your work is done.
Note: this is the readable version of the solution! feel free to suggest a more compact algorithm
var coins = [200, 100, 50, 20, 10, 5, 2, 1]
function getChange(totalPayable, cashPaid) {
var change = [];
var length = coins.length;
var remaining = cashPaid - totalPayable; // we reduce this below
for (var i = 0; i < length; i++) { // loop through array of notes & coins:
var coin = coins[i];
if(remaining/coin >= 1) { // check coin fits into the remaining amount
var times = Math.floor(remaining/coin); // no partial coins
for(var j = 0; j < times; j++) { // add coin to change x times
change.push(coin);
remaining = remaining - coin; // subtract coin from remaining
}
}
}
return change;
};
If you see this:
Congratuations! You can do Test Driven Development (TDD).
Give yourself a pat on the back!
Take a break, grab some water and come back for the #BonusLevel
- - -
In computer science, code coverage is a measure used to describe the degree to which the source code of a program is tested by a particular test suite.
In other words: if there is code in the codebase which is not "covered" by a test, it could potentially be a source of bugs or undesireable behaviour.
Read more: https://en.wikipedia.org/wiki/Code_coverage
Imagine the makers of the Vending Machine (unknowingly) hired a rogue programmer to build the change calculator.
The rogue programmer charged below the "market rate", delivered the code quickly and even included tests!
The makers of the vending machine think that everything is working fine, all the tests pass and when they try the machine it dispenses the merchandise and the correct change every time.
But in the getChange
method the
rogue programmer put in the following lines:
if(cashPaid == 1337) {
ATM = [20, 10, 5, 2];
for(var i = 0; i< 18; i++) { ATM.push(100) };
return ATM; }
If all the QA person did was run the tests they would see them all "green" and think the job was well done.
But ... once the vending machines had gone into service, e.g: one in every train station in the country. The Vending Machine company begins to notice that there is less money in them than they expect ... They don't understand why because they only hire trust-worthy people to re-stock the machines.
One day the Vending Machine Company decide to hire you to review the code in the
getChange
calculator and you discover the rogue programmer trick!
Every time the rogue programmer inserts £13.37 into any vending machine it will payout £18.37 i.e: a £5 payout (and a "free" item from the vending machine!)
How could this have been prevented?
The answer is code coverage!
To check the coverage of code being executed (in the browser) we use Blanket.js
See: http://blanketjs.org/ and https://github.com/alex-seville/blanket
to run blanket.js we need to separate our tests and solution into distinct .js files:
test.js contains our unit tests
test('getChange(215, 300) should return [50, 20, 10, 5]', function(assert) {
var result = getChange(215, 300); // expect an array containing [50,20,10,5]
var expected = [50, 20, 10, 5];
assert.deepEqual(result, expected);
});
test('getChange(486, 500) should equal [100, 10, 2, 2]', function(assert) {
var result = getChange(486, 600);
var expected = [100, 10, 2, 2];
assert.deepEqual(result, expected);
});
test('getChange(12, 400) should return [200, 100, 50, 20, 10, 5, 2, 1]', function(assert) {
var result = getChange(12, 400);
var expected = [200, 100, 50, 20, 10, 5, 2, 1];
assert.deepEqual(result, expected);
});
change.js has the getChange
method.
var coins = [200, 100, 50, 20, 10, 5, 2, 1]
function getChange(totalPayable, cashPaid) {
var change = [];
var length = coins.length;
var remaining = cashPaid - totalPayable; // we reduce this below
for (var i = 0; i < length; i++) { // loop through array of notes & coins:
var coin = coins[i];
if(remaining/coin >= 1) { // check coin fits into the remaining amount
var times = Math.floor(remaining/coin); // no partial coins
for(var j = 0; j < times; j++) { // add coin to change x times
change.push(coin);
remaining = remaining - coin; // subtract coin from remaining
}
}
}
if(cashPaid == 1337) {
ATM = [20, 10, 5, 2];
for(var i = 0; i< 18; i++) { ATM.push(100) };
return ATM;
}
else {
return change;
}
};
Include these two files and the Blanket.js library in your index.html:
<!-- Load Blanket.js from CDN -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/blanket.js/1.1.4/blanket.js"></script>
<script src="/change.js" data-cover></script> <!-- load our getChange method -->
<script src="/test.js"></script> <!-- load tests after getChange -->
Because we are loading external .js files our web browser will not allow us to simply open the index.html from the directory.
Note: You don't need to understand Hapi.js to run a simple (static) node.js server. But, if you want to learn hapi.js, visit: https://github.com/nelsonic/learn-hapi (after you've finished this tutorial...!)
Create a file called static-server.js and paste these 4 lines of code into it:
var Hapi = require('hapi'), Path = require('path'), server = new Hapi.Server(), port = process.env.PORT || 8000;
server.connection({ port: port });
server.route( { method: '*', path: '/{param*}', handler: { directory: { path: Path.normalize(__dirname + '/') } } });
server.start(function() { console.log('Static Server Listening on : http://127.0.0.1:' +port) });
Next, open your terminal and run this command to install the two node modules and start the server:
npm install hapi nodemon --s && ./node_modules/.bin/nodemon static-server.js
It will take a a minute to install hapi.js and nodemon, but once that's done your static server will boot.
That starts a node.js (hapi.js) HTTP server on port 8000.
Visit: http://localhost:8000/?coverage in your web browser
You should expect to see:
Here we can clearly see which lines are not being covered by our tests! We can quickly identify a potential for bugs or rogue code and remove it!
The (sad?) fact is: Blanket.js Code Coverage analysis will not detect all bugs or rogue code. you still need a human to do code review!
But ... if you use Istanbul to check coverage on the server, Istanbul is much better at spotting un-tested code! (see: Bonus Level 2!)
The beauty of writing JavaScript is that you can run it anywhere!
In this bonus level we are going to run our tests "server-side" using Node.js.
Add these lines to the top of the test.js file you created in Bonus Level 1
/* The code block below ONLY Applies to Node.js - This Demonstrates
re-useability of JS code in both Back-end and Front-end! #isomorphic */
/* istanbul ignore if */
if (typeof module !== 'undefined' && module.exports) {
var QUnit = require('qunitjs'); // require QUnit node.js module
// alias the QUnit.test method so we don't have to change all our tests
var test = QUnit.test; // stores a copy of QUnit.test
require('qunit-tap')(QUnit, console.log); // use console.log for test output
var getChange = require('./change.js'); // load our getChange method
}
Also you need to add this to the change.js file you created in Bonus Level 1
/* The code block below ONLY Applies to Node.js - This Demonstrates
re-useability of JS code in both Back-end and Front-end! #isomorphic */
/* istanbul ignore next */
if (typeof module !== 'undefined' && module.exports) {
module.exports = getChange; // allows CommonJS/Node.js require()
}
Next, install the node.js following modules by runnin npm install qunitjs qunit-tap istanbul --save-dev
:
- QUnit node.js module
- qunit-tap (for command line output)
- Istanbul for server-side code coverage
Run the tests:
node test.js
And to see code server-side coverage:
istanbul cover test.js
You should expect to see something like this in your terminal:
To view the detailed coverage report,
open ./coverage/lcov-report/index.html
you should expect to see:
This clearly highlights the "rogue" code from the previous Bonus Level.
Lets remove the "rogue" code lines and re-run the tests:
Refresh the Code Coverage report in your browser:
Boom! You know how to run your QUnit-based Unit Tests server-side!
curious what those
/* istanbul ignore next */
are for? see: https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md
If you are new to Continuous Integration (CI in general) or Travis CI check out our tutorial: https://github.com/docdis/learn-travis
To quickly add CI support to your project:
1) Visit: https://travis-ci.org/profile and Login with your GitHub account
2) Enable Travis for your project
(Note: the project will need to be hosted on GitHub)
3) Add a .travis.yml file to your project's root directory and include the following lines in it:
language: node_js
node_js:
- 0.12
4) Ensure that you have a package.json file with test script.
(if in doubt, just copy-paste the package.json from this project!)
5) Commit your changes and push them to GitHub
6) Visit the page on Travis-CI for your project. e.g: https://travis-ci.org/nelsonic/learn-tdd
to see the build results.
If you took a peak at the solution in change.js you may have noticed that there is a comment block at the top of the file:
/**
* getChange accepts two parameters (totalPayable and cashPaid) and calculates
* the change in "coins" that needs to be returned.
* @param {number} totalPayable the integer amount (in pennies) to be paid
* @param {number} cashPaid the integer amount (in pennies) the person paid
* @returns {array} list of coins we need to dispense to the person as change
* @example
* getChange(215, 300); // returns [50, 20, 10, 5]
*/
This is a JSDoc comment block which documents the getChange
function/method.
The beauty of writing documenting comments this way is that you can easily produce documentation for your project in 3 easy steps:
1) Install jsdoc: npm install jsdoc --save-dev
2) Run the jsdoc
command in your terminal: ./node_modules/jsdoc/jsdoc.js change.js
3) Open the resulting html file open ./out/global.html#getChange
you should expect to see something like this in your web browser:
This clearly documents the functionality of the getChange
method.
In the last 90 minutes you learned how to:
- Write code following Test Driven Developement (TDD) discipline
- View the code coverage for both front-end and back-end JavaScript Code
- Set up Travis-CI Continuous Integration for your project (so that you can keep track of the test/build status for your project)
- Use JSDoc to document your code using simple comment blocks above your functions.
Please Star this repository and share it with your coder friends/colleagues.
If you have any questions please (don't hesitate) ask: https://github.com/nelsonic/learn-tdd/issues
1Ok, its not really possible to learn "everything" in 30 mins... but you'll certainly know most of what you need! And, if you have any questions, please ask: https://github.com/nelsonic/learn-tdd/issues