Unit testing the Complementary game
I hope you at least heard of the concept of Unit Testing as it is one of the principal pillars of software development. Its purpose is to automatically check the functionality of isolated components of your code, but it adds a lot of benefits:
- your code becomes more modular - you only worry about the code you change
- your code becomes more readable - clear dependency chain and tests demonstrate in code what was the purpose of particular features
- you gain confidence that your code works as you are making changes to it - refactoring without unit tests in place is usually dangerous
- changing any component with another implementation does not affect the overall application
This post is a companion to the Programming a simple game in pure HTML and Javascript in the sense that it is that game that we will be testing. Also, as per the requirements of that project, we will not be using any of the numerous unit testing frameworks available for Javascript code.
When we left off the development of the game we had three files:
- complementary.html - the structure of the page
- complementary.css - the visual design of the page components
- complementary.js - all the code of the game, including the initialization and the game starting bit
In order to test our individual components, we need to separate them. So let's split complementary.js in four files:
- complementary.js - just the game start (instantiating Game and initializing it)
- game.js - the Game class
- color.js - the Color class
- elements.js - the custom HTML elements and their registration
Obviously the HTML will change to load all of these Javascript files. When we get to modules, this will become a non issue.
There are things that we could test on the custom HTML elements, but let's leave that aside. Also the two lines in complementary.js will not need testing. The simplest component should be the first to be tested and that is Color.
We start by creating a new HTML file (color tests.html) and we fill it with code that checks the Color class works as expected. First the code and then the discussion:
<html>
<head>
<script src="color.js"></script>
<script>
// this can easily be changed to display a nice report in this page
const assert ={
true:(value, message)=> {
if (value) {
console.log('Test PASSED ('+message+')');
} else {
console.warn('Test FAILED');
alert(message);
throw new Error(message);
}
}
};
</script>
</head>
<body>
<script>
// Arrange
const color1 = new Color(123);
const color2 = new Color(123);
const color3 = new Color(234);
// Act
const equalsWorks = color1.equals(color2);
const notEqualsWorks = !color1.equals(color3);
// Assert
assert.true(equalsWorks,'Expected two colors initialized with the same value to be equal');
assert.true(notEqualsWorks,'Expected two colors initialized with different values not to be equal');
</script>
<script>
// Arrange
const color = new Color();
const doubleInvertedColor = color.complement().complement();
// Act
const complementAndEqualsWork = color.equals(doubleInvertedColor);
// Assert
assert.true(complementAndEqualsWork,'Expected the complementary or a complementary color to be the original color');
</script>
<script>
// Arrange
const acolor = new Color(0x6789AB);
const stringColor = acolor.toString();
// Act
const toStringWorks = stringColor==='#6789ab';
// Assert
assert.true(toStringWorks,'Expected the HTML representation of the color to be #6789ab and it was '+stringColor);
</script>
</body>
</html>A test should follow the AAA structure:
- Arrange - sets up the necessary items for the test to run
- instantiate classes to be tested
- mock functionality of dependencies - we will see this when we test Game
- Act - executes the code intended to be tested and acquires results
- Assert - verifies that the test results are the ones expected
Normally, a framework would take tests written in a certain way and then produce some sort of report, with nice green and red rows, with messages, with information on where errors occurred and so on. However, I intend to demonstrate the basics of unit testing, so no framework is actually needed.
A unit test:
- is a piece of code (who unit tests the unit test?!)
- it requires effort, it is just as prone to bugs as normal code and requires maintenance just like any other code (shit doesn't just happen, it takes time and effort)
- it requires infrastructure that uses it to periodically test your changes (either someone does it manually or there is some setup to run it automatically and display/email the report)
In the code above I created a script tag for each test in which I am following AAA to create Color instances and then check their functionality does what it should. A very basic assert object is handling the reporting part. It remains homework for the reader to update that part or to plug in an existing unit testing framework.
The Color class is very simple:
- it supports initializing with a color integer representing the RGB values of the color
- toString method that returns the HTML representation of the color
- complement method returns the complement of the color
- equals method checks if two colors are equal
There are no external dependencies, meaning that it needs nothing from the outside in order to work. Game, for example, requires Color, which is a dependency for Game.
Open the color tests.html file in the browser and open the development tools (F12 or Ctrl-Shift-I) and refresh the page. You should see in the console that all the tests passed. Change something in a test so it fails and it should both throw an error in the console and show you a dialog with the failing test.
Now, let's test Game. The code of the game tests.html file:
<html>
<head>
<script src="game.js"></script>
<script>
// this can easily be changed to display a nice report in this page
const assert ={
true:(value, message)=> {
if (value) {
console.log('Test PASSED ('+message+')');
} else {
console.warn('Test FAILED');
alert(message);
throw new Error(message);
}
}
};
</script>
</head>
<body>
<script>
// Arrange
const game = new Game();
// Act
// Assert
</script>
</body>
</html>I used the same structure, the same assert object, only I loaded game.js instead of color.js. Then I wrote a test in which I do nothing than instantiate a Game. If you execute this page it will work just fine. No errors because we have not, in fact, executed anything. We need to execute .init(document), remember?
And now it becomes apparent why I chose to initialize the document from init instead of using window.document in my code. window.document is now the document of the test page, it has no complementary-board element in it. We haven't even defined any custom HTML elements or a Color class. In fact, we can now test that calling init with no parameter will fail:
<script>
// Arrange
const game = new Game();
// Act
let anyError = null;
try {
game.init();
} catch(error) {
anyError = error;
}
// Assert
assert.true(anyError!=null,'Expected the init method of a Game class to fail if run with no parameters ('+anyError+')');
</script>And, indeed, if we open the page now we get a console log like this:
Test PASSED (Expected the init method of a Game class to fail if run with no parameters (TypeError: Cannot read property 'addEventListener' of undefined))You just learned another important characteristic of a unit test: it tests both what should work and what shouldn't. This is one of the reasons why unit testing is hard. For each piece of code you need to test when it works and when it fails as expected. Now we have to test how Game should work, and that means we get into mocking.
Mocking is when you replace a dependency with something that looks exactly the same, but does something else. For unit tests mock objects need to do the simplest things and those things must be predictable.
Let's see how one of these tests would look:
<script>
// Arrange
const mockDoc = {
addEventListener:function() {
}
};
const game2 = new Game();
// Act
let anyError2 = null;
try {
game2.init(mockDoc);
} catch(error) {
anyError2 = error;
}
// Assert
assert.true(anyError2==null,'Expected the init method of a Game class to not fail if run with correct parameters ('+anyError2+')');
</script>Just by providing an object with an addEventListener function, the initialization of the game now works. mockDoc is a mocked document and this is called mocking.
Let's look at how would a "happy path" test look, one that assumes everything goes correctly and moves through and entire flow:
<script>
// Arrange
const mockDoc3 = {
testData : {},
addEventListener:function(eventName,eventHandler) {
this.testData.eventName = eventName;
this.onLoad = eventHandler;
},
getElementsByTagName:function(tagName) {
this.testData.tagName = tagName;
return [this.mockBoard];
},
mockBoard: {
setChoiceHandler:function(handler) {
this.choiceHandler=handler;
}
}
};
const game3 = new Game();
// Act
let anyError3 = null;
try {
game3.init(mockDoc3);
} catch(error) {
anyError3 = error;
}
Math = {
random:function() {
return 0.4;
},
floor:function(x) { return x; },
round:function(x) { return x; },
pow:function(x,p) { if (p==1) return x; else throw new Error('Expected 1 as the exponent, not '+p); }
};
Color = {
index:0,
new:function(value) {
return {
val: value,
equals: function(x) { return x.val==this.val; },
complement: function() { return Color.new(1000-this.val); }
};
},
random:function() {
this.index++;
return Color.new(this.index*10);
}
}
mockDoc3.onLoad();
mockDoc3.mockBoard.choiceHandler(3);
// Assert
assert.true(anyError3==null,'Expected the init method of a Game class to not fail if run with correct parameters ('+anyError3+')');
assert.true(mockDoc3.testData.eventName==='DOMContentLoaded','DOMContentLoaded was not handled!');
assert.true(mockDoc3.testData.tagName==='complementary-board','Game is not looking for a complementary-board element');
assert.true(game3._roundData.guideColor.val === 10,'Guide color object expected to have val=10 ('+JSON.stringify(game3._roundData.guideColor)+')');
assert.true(game3._roundData.tries.size === 1,'Expected 1 unsuccessful try ('+JSON.stringify(game3._roundData.tries)+')');
assert.true(game3._roundData.tries.has(3),'Expected unsuccessful try with value of 3 ('+JSON.stringify(game3._roundData.tries)+')');
assert.true(game3._log.length === 0,'Expected no score after one unsuccessful try ('+JSON.stringify(game3._log)+')');
// Act 2 (heh!)
mockDoc3.mockBoard.choiceHandler(2);
// Assert 2
assert.true(game3._roundData.guideColor.val === 60,'Guide color object expected to have val=60 ('+JSON.stringify(game3._roundData.guideColor)+')');
assert.true(game3._roundData.tries.size === 0,'Expected no unsuccessful tries after correct response ('+JSON.stringify(game3._roundData.tries)+')');
assert.true(game3._log.length === 1,'Expected one item of score after correct answer ('+JSON.stringify(game3._log)+')');
assert.true(game3._log[0] === 50,'Expected 50 as the score after one fail and one correct answer ('+JSON.stringify(game3._log)+')');
</script>
There is a lot to unpack here, including the lazy parts of the test. Here are some of the issues with it:
- it doesn't follow the AAA pattern, it asserts, then acts again, then asserts again
- while this works, it doesn't encapsulate testing of a single feature
- it is the equivalent of the classes or methods with multiple responsibilities from normal code
- the correct way to do it is to write another test, have two choiceHandler calls in the Act part and assert only that particular path
- it tests internal functionality
- in order to write the test I had to look at how the Game class works internally and then tailor the test so it works
- it accesses private data like _log and _roundData
- the Game class did not abstract all of its dependencies
- this is painfully obvious when mocking the Math object - in Javascript this is easy, but in other languages the Math functionality comes as an interface (a declaration of available members with no implementation)
- this is not a test problem, but a Game problem which makes testing tedious
- test contains logic
- look at the Math and Color mocks, how they compute values and return objects
- some values there are particularly chosen to "work"
- have you noticed how random returns 0.4 so that multiplied with 5 (number of choices) it returns 2, which then is equal with the correct choice?
- test is not independent
- Math and Color are replaced with some static objects, thus changing the environment for following tests
But it works, even if it's not very well written. Here are some of its good features:
- it tests a full game round with one bad and one good choice
- it doesn't try to go around randomness by adding more code in the assertion part
- it could have easily gone that way in order to determine the correct color in a random list, thus replicating or reverse engineering the Game logic into the test
- all the expected results are completely predictable (the score values, the indexes, etc)
- it tests only Game functionality, not others
- I could have not mocked Color, loading color.js and thus relying in a single test on functionality from a dependency
The lessons learned from this tell us that both the Game code and the test code could have been written better in regard to maintainability, with dependencies clearly declared, easy to mock or replace. In fact, the greatest gain of a company with hiring a senior developer is not on how well code works, but how much time is saved and how much risk is avoided when the code is written with separation of concerns and unit testing in mind.
It is funny, but when a piece of code is not testable, writing a single unit test forces you to refactor it into a good shape. The rest of the tests only test functionality, as the class has been rewritten with testing in mind. So that is my advice: whenever you write something, even a silly game like Complementary, write one "happy path" unit test per class.
Homework for you: rewrite the Game class and its test class so that testing becomes easier and more correct.
