The difference between “normal” and test-driven development (TDD) is that when doing TDD, you write unit tests for your new code before writing the code itself. This way you ensure good test coverage for your code, and your code will also be more flexible and reusable, as you have to design the class interfaces for easy testing.

Test-driven development basics

As mentioned, the main idea is that before you write any actual application code, you write a unit test(s) which checks the code you will be writing.

It may initially be a bit difficult to adjust to writing the tests before any code. How do I know what to test when I don’t have any code?

The idea is not so difficult. Think of how you want to use the code, and write a test based on that. If you need to write a class which sums numbers, it needs a sum method and when passed two numbers the output is their sum.

Preconditions and postconditions

Another good approach is to think of preconditions and postconditions. This is something you can think of when writing unit tests in general, too.

• A precondition is something that must be true before something is done
• A postcondition is something that must be true after something is done

In tests we care more about the postconditions, but some things can be thought of as preconditions as well: When you create a new object, its properties must meet certain criterias, such as a collection should be empty. While this is actually a postcondition of the constructor, it may be easier to think of it as a precondition for any other operations.

Writing code in a TDD manner

Now it’s time to look at a simple example of writing code using TDD. We will first need some goal for our code.

Let’s say we’re writing a sales system and we need a class for orders. Orders need to have items in them, a recipient, order IDs etc.

We don’t have any code yet, and let’s keep it that way, as first we need to write tests. Let’s decide that an order must be empty and it must have no recipient when it’s created:

class OrderTest extends PHPUnit_Framework_TestCase {
    public function testOrderStartsEmpty() {
        $order = new Order();
        $this->assertEquals(0, count($order->getItems()));
    }
 
    public function testOrderStartsWithoutRecipient() {
        $order = new Order();
        $this->assertNull($order->getRecipient());
    }
}

Now we have tests that confirm the correct behavior of the constructor - we could say the postconditions of the constructor are that item count is 0 and recipient is null.

Of course, when running the above test it will fail quite miserably. We have no class, no methods, nothing. This is a good thing, as now we know that the test actually works as expected.

We can now write the Order class with the methods required by the test:

class Order {
    private $_items = array();
    private $_recipient = null;
 
    public function __construct() {
    }
 
    public function getItems() {
        return $this->_items;
    }
 
    public function getRecipient() {
        return $this->_recipient;
    }
}

And now the tests we wrote pass. Congratulations, now you have written code using test-driven development!

Another example

Now, we need to be able to add items to our order. To keep things simple for the example, the items are just going to be strings such as 'Cat food' or 'Bananas'.

Again, let’s define the behavior of the code first, then write tests and then the actual code. We’ll add a method called addItem, which takes the item as its parameter. If the parameter is not valid, it’ll throw an exception.

public function testHasItemAfterAdding() {
    $order = new Order();
 
    $this->assertFalse($order->hasItem('Cat food'));
 
    $order->addItem('Cat food');
 
    $this->assertTrue($order->hasItem('Cat food'));
}
 
public function testAddingInvalidItemThrowsException() {
    $order = new Order();
 
    try {
        $order->addItem('');
        $this->fail('Empty items are invalid');
    }
    catch(InvalidArgumentException $ex) {
    }
}

If we run the tests again, they should fail. Now we could write the code to make the tests pass, but I will leave that as an exercise to you.

In closing

Test-driven development is not as difficult as it may initially seem. You only need to adjust your thinking a bit.

You may notice that in our tests and code above we didn’t have good tests for some of the methods like getItems and hasItem. I left them out as it would’ve made the post unnecessarily long, but when writing actual code you would want to write tests for them as well. Because of such small helper methods, it may sometimes be a good idea if you have a class diagram or if you write empty stub methods in your code before writing the tests. This will help remind you of what methods you have to test.

Next time we’ll look at testing a Zend Framework application.

Originally the game was made for an older version of Opera 9, and only worked in it. However, I have now modified the game so it should work in most browsers (tested Firefox, Opera 9, 10).

Click here to play cross-browser version of the game. The game should work for other parts than the online game mode, as the server is no longer functional.

Interested in hearing how the game works, such as terrain, physics and the computer AI? Keep reading!

A disclaimer regarding the code

If you want to go look into the code, feel free, but keep in mind I wrote this in late 2006 and the code is not really very good. It probably makes sense after you’re totally familiar with it, but even I who wrote the thing had problems finding the places I needed to modify to make it work once again.

Main features of the game

Let’s look at how some of the main features of the game work.

Terrain

The terrain in TankWar is generated randomly, based on a bunch of parameters. If you go into the map settings from the main menu, you can see and adjust these parameters.

The input fields in the map settings screen are actually Web Forms 2 (now a part of HTML5 forms) elements, which still don’t seem to be supported by any other browser than Opera, even after many years. If you don’t have Opera handy, the main difference between the fields in other browsers and Opera is that in Opera, the fields get little arrows for increasing and decreasing the value.

The terrain generation algorithm itself is pretty simple. It takes the base height value, and then adds a number of points based on the height points value. The points’ heights is randomized between the min height and max height values. Ta-dah, simple terrain generation.

Destruction of terrain

Another feature of the terrain is that it’s desctructible. If you fire a weapon at it, it’ll make a hole. You could even destroy the whole map if you destroyed all the ground.

To understand how the desctruction of the terrain works, we have to look at how the terrain itself is stored and rendered.

The terrain is stored as an array of points, which are converted into a canvas path. The path actually consists of the sky, and not the ground - the sky and ground are rendered by first filling the whole image with the ground color, and then using the terrain path to fill in the sky.

When some of the ground is destroyed, the game creates a circular path, which is then added to the terrain path. This way the destroyed areas of the ground get filled with the sky color as well, making it seem like the ground was destroyed, even though the terrain path itself remains unmodified.

Terrain hit testing

This is also used for testing hits on the ground: as long as a projectile (or a tank) is inside the terrain path, or inside one of the circular explosion paths, the projectile keeps moving. The hit check was performed by an Opera-specific method and a custom polygon hit checking function in the old code, as when I wrote it, there was no reliable way to detect whether a point was inside a path or not. In the new version, the hit is detected with the canvas method isPointInPath, which should work in all browsers with a modern canvas implementation.

The physics engine

The game features a simple physics engine, which simulates falling tanks and moving projectiles such as cannon shells. It also allows for wind.

It functions relatively simply: each “physics object” - tanks and shells - have some vectors which define their position and velocity. The engine has a constant gravity, and an optional wind (which is kind of like horizontal gravity), which affect objects when they move. The physics engine is not active until someone actually fires their cannon - it has no need to run when you take aim, so the engine was designed so it could be given a set of objects to simulate (tanks and the newly fired shell) and then it could run until all the objects are considered “dead”. Being dead simply means that each object has hit the ground, or for shells, hit a tank.

Weapons

Currently the game has eight weapons. Originally there were less, but I had wanted to add more interesting weapons, so the weapon system was designed to accomodate various kinds of weapons, as can be seen in the current selection.

The weapon system is based on the concept of a cannon and a shell (which is what cannons fire). The cannon acts as a kind of a factory for shells, defining how much damage they make, how large is their blast radius etc.

The system is also wired with some events such as an event for the time when a shell hits the ground. This enables the engine to have weapons like the teleport or the arty drop, which both have a special handler for the hit ground event, which moves the player’s tank and fires three more shells at the location from the sky, respectively.

The bomber weapon is a bit special. The weapon’s behavior is actually not intended - it’s a bug. It probably seems crazily overpowered sometimes, and I never meant it to drop an infinite stream of “bombs”, just five of them, but because of a bug it just turned out like that. I liked the unintended behavior and left it in, so it became a feature instead.

Some of the weapons were inspired by Worms 2, like the arty drop and teleport.

Computer opponent

This was one of the most interesting parts of writing the game. As I wanted to give players the possibility to play the game by themselves, I wanted it to have an AI player.

The game’s “player system” is quite flexible. It had to be, so that implementing a “local” player, a “network” player for online games and an “computer” player would be possible. Simply put, the players each implement a specific set of functions that are called in specific points during the game - the game itself doesn’t care much what the type of the player is, except in some special cases, and the player object itself handles things differently.

The computer AI is not very complex. To not give it a completely unfair advantage (and so that my head wouldn’t hurt too much because of the math involved), I didn’t give it a 100% precise aim - which would have been possible by computing where the shell will land, given the gravity, wind and required power and shooting angle.

Instead, the computer follows this graph (click to see a bigger image)

The diagram is not 100% accurate, but that is the general idea of how the AI works. It does some small additional things, such as figuring if wind has changed.

Currently defunct: Online play

The coolest thing in the game no longer works: The online multiplay mode.

The online multiplayer mode was similar to what you can see in many PC games nowadays. It had a lobby where players could talk with each other, and a list of games which were active and joinable. It was also possible to protect your game with a password and choose a maximum amount of players.

There were some additional hidden features in the online lobby, such as the ability to join a custom room, a bit similar to joining channels on IRC. It also implemented some swearword filtering (schoolkids seemed to enojy abusing the chatroom during school hours) and an admin interface for getting rid of unwanted elements (which was implemented on the server and only worked for me)

The gameplay itself was the same, but in addition to the interface elements seen in a local game, the game showed you a chat box and the list of others in the game so you could talk with them during the game. As with local games, you could have up to eight players in a single game, which was a limitation I had chosen based on the map size - the game could have had 10, 20 or more players, but the map would’ve gotten very crowded.

Online game server

The server for the online play was lost in a fatal hard disk failure in 2008 or so. It was implemented in Python, using a library called Twisted to provide HTTP functionality.

The server received communications from clients with XMLHttpRequests, and sent responses using a Server-Sent DOM Events channel, which each client was required to open. Most of the stuff was quite normal client-server type of things - the clients would get an ID, send messages, receive responses and parse them etc.

There was quite much game related things to do on the server as well. While testing the game, I noticed a worrying inconsistency of where the shells landed on one PC compared to a slower PC - sometimes on slow PCs, the shells would land on completely different locations than on the fast PC. I fixed this by making each network player get synced from the server. Basically it meant that whenever a player’s turn was finished, the player’s game told the server where the shots had landed. The server would then broadcast this to all players in the game, and this way each player’s game was kept in perfect sync.

Sadly I no longer have the code as said, and it would be a rather big undertaking to write a new one - certainly possible, but I don’t have the time for it.

Bottom line

TankWar was, and maybe still is, my greatest widget. WidgetCity was a large and complex project, but TankWar had a lot of special things in it and it was 100% written by me - WidgetCity shared a lot of algorithms with the original Sim City source code available online.

Here is the source code for TankWar, if you want to take a look at it.

When testing a class which needs an instance of another class to work, you do not want to depend on the other class too much. This is where mock objects come in - a mock object is a “clone” of an object, which we can use to simplify our tests, by having the mock object perform assertions or by replacing some functionality of the mock with our custom functionality.

In this post we’ll first look at how mock objects are created and used with PHPUnit, and then we’ll take a practical example of using mocks to test code which uses the database to fetch some data.

Mock basics

Before we look at how PHPUnit does mocks, let’s first check out the principle of how the mocks work.

You can create mocks even without the fancy methods PHPUnit provides to you - by simply creating a new class which extends the class you wish to mock:

class SomeClassMock extends SomeClass {
}

We could call that a mock object, although it’s not very useful yet.

Say the class which we are testing needs to call a method in SomeClass, and we want to be sure it actually gets called in our test. In this case, let’s add a variable and a method to our mock class:

class SomeClassMock extends SomeClass {
  public $methodWasCalled = false;
 
  public function aMethod() {
    //This method should get called by the object we are testing
    $this->methodWasCalled = true;
  }
}

Now, in our test, we can do something like this:

//Just a simple example
public function testAMethodIsCalled() {
  //First, create a mock of SomeClass
  $someClass = new SomeClassMock();
 
  //This is the object we are testing, let's assume
  //it takes a SomeClass instance as the parameter
  $object = new MyClass($someClass);
 
  //Say the method in SomeClass needs to be called now
  $object->doSomething();
 
  //Confirm the method was called by checking the mock's variable:
  $this->assertTrue($someClass->methodWasCalled);
}

Creating mock objects with PHPUnit

Writing mock objects like we saw above is quite time consuming and complex. Luckily, we don’t have to actually write the mock classes ourselves, as PHPUnit provides us with a set of methods we can use to do almost any kind of mock we need. We will use the PHPUnit mocking API from now on, but it’s always useful to know how the things work behind the scenes.

Let’s rewrite the test with PHPUnit’s mocking API:

public function testAMethodIsCalled() {
  //First, create a mock of SomeClass
  $someClass = $this->getMock('SomeClass');
 
  //Now we can tell the mock what we want to do:
  $someClass->expects($this->once())
            ->method('aMethod');
 
  //This is the object we are testing, let's assume
  //it takes a SomeClass instance as the parameter
  $object = new MyClass($someClass);
 
  //Say the method in SomeClass needs to be called now
  $object->doSomething();
 
  //We don't need to do anything else - the mock object will confirm
  //that the method was called for us.
}

Doesn’t look too complex does it? Instead of writing a whole class to do a simple method-call check, we just use the getMock method to receive a mock-version of an object, and then we tell it what it needs to do in this test.

What did we do to the mock?

First, we call the expects method and pass $this->once() as a parameter. Then, we call method with 'aMethod'. This means that the mock object “expects one method call to aMethod”. Replacing a method in the mock like this is also known as stubbing the method - the code in the method is replaced by a “test stub”.

What will happen if the method does not get called? You will get an error similar to this when you run your test:

1) testAMethodIsCalled(ExampleTest)
Expectation failed for method name is equal to <string:aMethod> when invoked 1 time(s).
Method was expected to be called 1 times, actually called 0 times.

Using mocks to test database code

Now that we know our mocks, or at least enough to start with, let’s jump into some useful examples.

A very typical case is that you need to test code which uses the database - for example, the code might be fetching some data from the DB, or maybe inserting something. We certainly could have a testing database, but it’s much easier and simpler to work with mock objects.

The example scenario

Let’s say we have a class called EventRepository which tracks some kind of events in our application. We also have a class called Event, which represents a single event. We now want to write unit tests for the EventRepository class, but as the class accesses the database we have a dilemma.

class EventRepository {
  private $_pdo;
 
  public function __construct(PDO $database) {
    $this->_pdo = $database;
  }
 
  public function findById() {
    $sql = 'SELECT * FROM events WHERE ...';
 
    //Here we have some code to execute the SQL, convert
    //the result to an Event object and then return it
  }
 
  /* some other methods here */
}

To test this class, we would need to use a test database. This is because the SQL queries etc. are executed inside the class and there’s nothing our test can do about it.

Making the EventRepository testable

To make this class better, and easier to test, let’s modify it to use a data access object.

The data access object (DAO) will look something like this for our example:

class EventDao {
  private $_pdo;
 
  public function __construct(PDO $pdo) {
    $this->_pdo = $pdo;
  }
 
  public function findById() {
    $sql = 'SELECT * FROM events WHERE ...';
 
    //Instead of event repository, the code to execute SQL is here.
    //We then return the row's data as an array
  }
 
  /* some other methods here */
}

Then, the EventRepository is modified to use EventDao:

class EventRepository {
  private $_dao;
 
  public function __construct(EventDao $dao) {
    $this->_dao = $dao;
  }
 
  public function findById($id) {
    $row = $this->_dao->findById($id);
 
    //Now we simply process $row into an Event object. No direct DB access
  }
 
  /* some other methods here */
}

Testing the thing

Now we can test the class! We mock out the EventDao object, so the testing code for EventRepository will not need access to a database.

Let’s write a test for the findById method to demonstrate mocking the DAO:

public function testFindsCorrectEvent() {
  //Set up a fake database row
  $eventRow = array(
    'id' => 1,
    'name' => 'Awesome event'
  );
 
  $dao = $this->getMock('EventDao');
 
  //Set up the mock to return the fake row when findById is called
  $dao->expects($this->once())
      ->method('findById')
      ->with(1)
      ->will($this->returnValue($eventRow));
 
  $repo = new EventRepository($dao);
 
  $event = $repo->findById(1);
 
  //Confirm ID of the returned Event is correct
  $this->assertEquals(1, $event->getId());
}

Here we have some more features of the mock API - checking parameters and deciding return values.

Firstly, the $eventRow is a “fake” return value for the mocked dao. For the repository to work correctly, the dao will need to return it a value, and this is it.
Expects and method in the mock set up is the same as before, but the with(1) and will($this->returnValue($eventRow)) are new.

with is used to tell the mocked method what parameters it expects, in this case it should be passed the event’s ID: 1. If it is not passed the value 1 when called, it will report the test as a failure.
will is used to tell the mocked method what it should do when it gets called, and we want it to return our fake row.

The rest of the test sets up the repository that we are actually testing, and calls a method and asserts that the return value was correct. We didn’t go over the rest of the code in findById, nor did we give Event a getId() method, but just assume that there was some code in findById which turns the row into an Event object, and that Event has the method.

Summing up and further reading

Using the PHPUnit mocking API we can easily replace dependencies in our tested classes with mocks that make testing much simpler, than having to depend on the actual object itself.

We didn’t cover all possible mock calls, such as how to have it throw an exception. For that and more, I recommend reading the PHPUnit manual stubs and mocks chapter.

In the next post, we’ll check out how to do test-driven or test-first style development

Today we’ll take an example class and write tests for it. We’ll also introduce some common testing methodologies.

Our example class

To do some testing, we need a class to test. Conveniently, there’s a class we can use in my svn repo: CU_Collection - a class which I wrote to demonstrate generic collections in PHP.

Here’s an example of how this class works:

//This collection only accepts strings
$coll = new CU_Collection('string');
 
//Add a string and echo it
$coll->add('This is a string');
echo $coll[0];
 
//This will throw an InvalidArgumentException because 1000 is not a string
$coll->add(1000);

This class isn’t very large, but it’s complex enough for us to demonstrate some testing principles on it. Now, let’s continue and start writing some tests!

Writing a test

Before we write the test, let’s remind ourselves of how the testcase should look:

<?php
require_once '../../library/CU/Collection.php';
 
class CU_CollectionTest extends PHPUnit_Framework_TestCase {
 
}

This is the basic structure of the testcase class. Note that this time we have a require_once on top of the code. Why is this?

Because this code depends on the CU_Collection class, we actually need to include it to be able to test it. We are assuming that the test is located in a directory called “tests/CU/CollectionTest.php” under the main project directory, and the code for the CU_Collection class is in “library/CU/Collection.php”. You can structure your project differently if you wish.

There is also a way to use autoloading and include paths, but that will be discussed in a later post.

Now, let’s write that test. If you look at the code of the class, you can see it should start with an empty collection with no items in it. Let’s write a test for it:

<?php
require_once '../../library/CU/Collection.php';
 
class CU_CollectionTest extends PHPUnit_Framework_TestCase {
  public function testCollectionStartsEmpty() {
    $coll = new CU_Collection('string');
    $this->assertEquals(0, count($coll));
  }
}

It may seem very simple at this point. Don’t worry, writing unit tests usually is this simple! Let’s look at some more examples next…

Testing code vs. testing behavior

As I mentioned in the introduction post, a good unit test checks the expected behavior of some code, not that the code does what it looks like it’s doing if you read it line by line.

Let’s write a test for the add method:

//this code again goes inside the CU_CollectionTest class
public function testAdding() {
  $coll = new CU_Collection('string');
 
  $coll->add('foobar');
  $this->assertEquals(1, count($coll));
 
  try {
    $coll->add(1);
    $this->fail('Should throw exception');
  }
  catch(InvalidArgumentException $ex) {
    $this->assertEquals('Trying to add a value of wrong type', $ex->getMessage());
  }
}

Is this a good test? It looks correct, and when you run it, it passes with flying colors. However, in a sense, this is not a good test!

The problem of this test is that it’s strictly written in the fashion “Okay, looks like the code does this, so let’s test that it does that”. While this test can be helpful, it would be better to rewrite it as we’ll see next. Also, consider the fact that the code you’re writing the test for could have a bug! If it was a more complex method than the one in this case, it could very well corrupt your test as a result if you don’t notice it.

Now, before writing the test, let’s consider what behaviors we expect from the add method:

1. If we add a correct type, the length of the collection should increase
2. If we add an incorrect type, we should get an InvalidArgumentException

So for this parts, the initial test was quite correct. It is good to keep in mind that you should always consider the behaviors, and only test one behavior per test, as we will do now. Sometimes you can see such behaviors from just the phpdoc comments without reading the code itself, but when writing tests for existing code you will often need to look at the code to find them.

First, let’s test the behavior #1:

public function testAddingCorrectType() {
  $coll = new CU_Collection('string');
 
  $coll->add('foobar');
  $this->assertEquals(1, count($coll));
}

And the second behavior:

public function testAddingWrongTypeCausesException() {
  $coll = new CU_Collection('string');
 
  try {
    $coll->add(1);
    $this->fail('Should throw exception');
  }
  catch(InvalidArgumentException $ex) {
  }
}

Note here that the assertion which checked the exception’s message was removed. In this case, I think it’s enough that we test that the exception thrown is of the expected type. The content of the exception’s message itself is not so important.

Fixing bugs

Often you will want to write a unit test when you encounter a bug, to be sure that the bug will not reappear in the future. This is called regression testing, and I think it’s very important in longer running projects, or frameworks such as the Zend Framework.

This brings us to another thing that can help improve your tests:

A test should initially result in a failure.

This doesn’t mean you need to write an incorrect test, or intentionally break your code. It means that when writing a test for a bug, or when doing test-driven development, you should write your test before writing the actual code.

Let’s introduce a bug into the CU_Collection class so that we can demonstrate this.

Modify the remove method’s array_splice call to not define the amount of items to remove. An easy mistake to make, but it can be difficult to spot!

public function remove($index)
{
  if($index >= $this->count())
    throw new OutOfRangeException('Index out of range');
 
  array_splice($this->_collection, $index); //Uh oh!
}

Remember that array_splice’s third parameter is the amount of items to remove, and if left undefined, it will remove everything in the array from that index onwards!

A naive unit test which checks only that remove works won’t do, such as this one:

public function testRemovingItem() {
  $coll = new CU_Collection('string');
  $coll->add('foobar');
 
  $coll->remove(0);
 
  $this->assertEquals(0, count($coll));
}

Even though we introduced a bug, this one will still pass. Imagine if you fixed the bug, and then wrote this to test against it? Oops. Don’t get me wrong, this is an okay test, but it won’t help us this time.

We need a better test:

public function testRemovingItemFromTheMiddle() {
  $coll = new CU_Collection('string');
  $coll->add('one');
  $coll->add('two');
  $coll->add('three');
 
  $coll->remove(1);
 
  $this->assertEquals(2, count($coll));
}

If we run the testcase against the broken code, this test will fail. Now we know that the test for our bug works, and we can then proceed to fix the bug. After fixing the bug, the test passes.

Conclusion

Now you should be able to write good tests yourself. Test behaviors, and fail first!

Do you have any burning questions? Feel free to any in the comments!

Next week in unit testing we’ll look into mock objects, which are necessary when testing more complex classes. Continue to Unit testing 4: Mock objects and testing code which uses the database

The tile map is done purely using just CSS, and CSS classes. The map is also scrollable.

How is this all done?

Multiple approaches

As always, there is more than one approach to doing this type of a tile map.

The most obvious approach is to chop down each graphic in the game to one tile sized small images. Then, each of the small images is applied using a background image to each of the tiles. For example, an industrial zone is 3×3 tiles, so this would need 9 small images which each get applied to specific tiles to build the whole industrial zone.

This small image approach can be done in two ways: Using a CSS style to put the image as the background, or by inserting an img tag into the cell and changing its src.

There’s a lot of different graphics for just a single type of zone: Indstrial zones for example have different graphics for different land valued zones and different populations on the zone. The above approach would work, but it would require a lot of work to chop each big graphic into small ones and also each image would have to follow a specific naming scheme so it could be applied correctly.

Another approach is similar to what is used in CSS sprites: Each larger graphic is contained in a single file, and the image is then mapped into the small cells using CSS’ background-position.

The chosen approach

I decided to use the approach similar to CSS sprites. This is because it was simpler to work with the files, as I didn’t need to rename all the little images and define tons of CSS classes just to apply the specific backgrounds. This also somewhat simplified the JavaScript code applying the styles.

The game defines a set of CSS naming rules which are used in the stylesheets, so the code in the game can easily apply styles without having to use special cases all over the place. Each cell’s className attribute consists of several classes:

• An “offset class”, which is used to place the big image into the small cell: for example, “o31×1″ is the bottom right corner of a 3×3 tile - o for offset, 3 for 3×3, 1×1 for the X and Y offset from the center of the tile. The game knows which position of the tile it’s laying out, so it simply adds the respective offset class into the cell’s className.
• The main “graphic class”, such as “indbuilding” for an industrial building.
• A “land value/population class”. This is used to choose which graphic of the building to actually display, such as a small rowhouse, or a big skyscraper. These look like v0p1, where v0 means land value 0 and p1 means population 1

There are also some other special classes:

• nopower class is applied to zone center cells if the zone doesn’t have power. This shows the little no power indicator
• For roads and powerlines, there are classes called up, right, down and left, which are applied in following cases: if you have a road, and there’s a section of road above it, the class “up” is given to the bottom road cell, and the class “down” is given to the upper. If there’s also a road to the left of the upper cell, it gets “left”. In the stylesheet, there are combinations of these four classes, which apply the correct road and powerline graphics to the cells.

The scripting side of things

Of course all this won’t work without JavaScript. Behind the scenes, the game stores the map as a two dimensional array of objects. The objects in the array contain various data, which is used to determine which classes to apply to each cell when “rendering” the map.

The classes are also applied only when something changes - the game keeps track of what classes are in the cells, as re-applying the class incurs a performance penalty.

What about canvas?

Lastly, some words on an alternative to using a table: the HTML5 canvas element.

While it may seem “wrong” to use table to do something like this, I think it’s in certain ways better than canvas. Firstly, you get better performance, and second, you need less code.

Using canvas, you would need to write the code to draw the correct parts of the graphics, and if you wanted animations like the game has now, you would need to write timing code to run the animations. So in addition to the performance penalty of using canvas rendering, you would need additional JavaScript code running the animations and everything else.

The benefits of using canvas would be that you could provide smooth scrolling. With a table it would be very tricky if not completely unfeasible. Canvas would also allow zooming or other effects.

Setting up PHPUnit

Before we can write tests, we need a testing tool. We are going to use PHPUnit for our examples, so you will need to install it.

The easiest way to install it is through PEAR. Read the PHPUnit installation guide for information on how to do that.

You will also need to be able to run PHP on the command line, including the phpunit command-line script. If you’re on Linux, chances are you already have PHP available on the command line - if not, the package for installing command-line PHP is usually something like php5-cli or such.

I have previously written a post on setting up command-line PHP on windows, which you can read to make it work on Windows.

To confirm everything works as expected, run a shell or command prompt and type in:

phpunit --version

which should output something like this:

PHPUnit 3.3.17 by Sebastian Bergmann.

Using PHPUnit

Next, let’s take a look at how to use PHPUnit so that we know how to use it when we actually start writing some real tests.

Writing a testcase

PHPUnit tests are written as testcase classes, which extend PHPUnit_Framework_TestCase. Let’s take a simple example to show you how they work.
For this example, we will just write a quick test for PHP’s array and count function.

class ArrayTest extends PHPUnit_Framework_TestCase {
  public function testAddingItemsIncreasesLength() {
    $array = array();
    $expectedLength = count($array) + 1;
 
    $array[] = 'foo';
    $this->assertEquals($expectedLength, count($array), 'Length was not correct');
  }  
}

As you can see from the code here, our test class is called ArrayTest and it extends from the PHPUnit testcase class. The naming convention for classes such as this is usually ClassNameTest - for example, a testcase for Zend_Controller_Action would be called Zend_Controller_ActionTest.

The ArrayTest class contains one method: testAddingItemsIncreasesLength. This is a test method. The convention for PHPUnit is that test methods are named testDescriptionOfWhatIsTested, so since our test checks that when we add an item into the array, the count is increased by one, our test is called testAddingItemsIncreasesLength. You can write as many test methods in a testcase as you think is necessary.

The code in the test method should be quite easy to understand - we create an array, calculate what the expected length of the array should be, push an item into the array and finally we have an assertion that confirms the result is as we expected. You can find a list of assertions you can do in the PHPUnit manual.

Running tests

Now that we have a test, how do we run it? These are the usual ways to do it:

1. The most straightforward way is to run a single testcase with phpunit, like this: phpunit NameOfTest, so to run our ArrayTest, we can do phpunit ArrayTest. Note that this assumes you are in the directory where the test is saved, and that the filename is ArrayTest.php.
2. Writing a test suite. This is complex and annoying to maintain, so I won’t go into it any more. If you really want to know, there’s a chapter on it in the PHPUnit manual.
3. Using an XML configuration file. This is the easiest way to run multiple tests, so we’ll take a look at writing this next.

Since most of the time you’ll want to run all of your tests, or you have more than one test that you want to run, doing it manually with phpunit SomeTest isn’t very feasible. Option #2 can be used to run multiple tests in one go, but as said, it’s not exactly a very good method.

So to run multiple tests, we’ll use method #3 - an XML configuration file. This file can be named whatever you want, but it’s probably a good idea to call it phpunit.xml because that means phpunit will detect it automatically.

Here’s an example phpunit.xml configuration file:

<phpunit>
	<testsuite name="Test suite name">
		<directory>path/to/tests</directory>
	</testsuite>
</phpunit>

This is the simplest possible xml configuration. All we define is a testsuite element with a name attribute, and a path to the tests.

The typical directory layout for tests is like this:

project/tests
project/tests/phpunit.xml
project/tests/App/SomeClassTest.php (this is a test for class App_SomeClass)

In this case, you would set the directory in the phpunit.xml file to . to tell it the tests are in the current dir, like this:

<phpunit>
	<testsuite name="My tests">
		<directory>.</directory>
	</testsuite>
</phpunit>

Using this kind of a configuration file, we can now easily run all our tests by just typing phpunit on the command-line, and phpunit will then read the config and execute all tests, providing us with feedback about the process.

The configuration file has other options you can add to it too. We won’t look at other properties in this post, but you can find a list of configuration options from the PHPUnit manual.

Next week’s post

Next week we will finally get to actually writing some tests for some example methods. We’ll take a look at a class or two, and look at how to write good tests for it: Unit testing 3: writing tests for existing code

I’d like to apologize to those of you who were waiting for that to show up in this week’s post - I kind of forgot that explaining how to run tests and all that would need it’s own post, and posting that before going any further made more sense.

Sameer Borate has written four posts about the topic in his blog, and I encourage you to check them out:

• Refactoring: An introduction to PHP programmers
• Refactoring 1: Conslidate conditional expressions
• Refactoring 2: Extract method
• Refactoring 3: Replace temp with query

In this post I’ll introduce unit testing: What it is, when it’s a good idea and when it might not be. I’ll also discuss a bit about what makes for a good unit test.

Next week I’ll post a followup to this, which will be more about actually writing unit tests with examples.

What is unit testing

If you are already familiar with the concept, you may wish to skip this chapter.

Simply put, unit testing means writing code to test other code. There are a variety of libraries for testing for various languages: for PHP there are PHPUnit and SimpleTest, for Java there’s JUnit, NUnit for .NET Framework languages, etc.

The idea is that when you write tests for your code using one of these tools, you can easily automate them and run them as often as needed. By writing unit tests, you can easily ensure that your code works as expected, even if the code is later changed, as your tests stay the same and you can (and should) always run them after doing changes.

There’s a good article on unit testing in wikipedia, which you should check out for a more in-depth explanation of it.

When is unit testing a good idea?

There’s a short answer to this: Always.

And there’s also a long answer to this: It depends on how complex your project is, and how long is its estimated lifetime.

If you have a very simple project, writing unit tests for it may take time that would be better spent in just writing the project itself. If it’s simple, it’s less likely to be difficult to test and it’ll be easier to find errors by manually using it.

If your project’s estimated lifetime is short, you may again want to not spend time writing tests. If the lifetime is short, you usually won’t have to maintain it or do any changes to the code, making unit tests less beneficial.

That being said, if you have the time and resources to write unit tests for even small/short projects, it may be a good idea. It largely depends on the situation, and you should make the call based on your specific circumstances, but the two cases I mentioned should serve as good examples.

Writing good unit tests

The idea of a unit test is to test the behavior of a piece of code. This is usually a class and some method of it.

When writing tests, you usually would want to write one test per behavior: Expected behavior of code when given correct values and expected behavior of code when given incorrect values are the essential ones you will want to write. Depending on the case, there may be more tests that you’ll want to write, but these two are good ones to start with.

A common metric for determining how good a set of unit tests are is code coverage. Code coverage is determined by checking how much of the total code your unit tests execute - does each if and else block get executed by some test, does every function get called, etc.

While code coverage is a quite good metric, it can be misleading. Even if your tests cover 100% of your code, they may not actually test each behavior correctly.

I’ll show you some examples of good tests and testing behaviors next week.

In closing

Unit testing is a great way to improve code quality - correctness, but also modularity, because it forces you to write code in a way that it’s reusable and flexible, as it would otherwise be difficult to test.

In the next part we will take a more hands-on coding approach and I’ll show you some practical examples of writing unit tests.

Is there a specific topic you would like me to write about? As long as it’s somewhat relevant to this blog’s past content, post your idea to the comments! - I just might pick your idea and write about it. I even might pick more than one.

It doesn’t matter if it’s a small thing or a large thing. If it’s interesting, it’s good! It can be a general topic, like Zend Framework or design patterns, or some more specific thing like “how to do X”

Then along comes Git, touting that it’s easy and that you’re stupid if you don’t use it. The technical stuff people said about it were impressing, but not enough to actually warrant trying it for me - Afterall, I was quite happy with svn, as it did what I needed.

After a while, I decided I wanted to try Git anyway - just out of curiosity, to see if it actually was so amazingly much better. And in this post I’ll tell you if it was

Basics

I’ve been using Git for a while now with some small projects - nothing very large, so bear that in mind: some Git features are probably more useful with bigger stuff.

The main functionality of Git is pretty similar to what Subversion has, git add, git commit, etc. - of course there are some minor semantic differences, and then there’s the whole local/remote repository concept.

Overall, I think Git is as easy to use as svn is, and there is also a GUI which makes certain tasks simpler.

Feature-wise in my testing I’ve found that while some features in Git are convenient, it doesn’t really have any major advantages over svn in my use. However, I still prefer it over svn.

Why Git over Svn?

There’s a lot of stuff on the net on what makes Git better than some other version control system, such as Why Git is better than X, which is good for an overview of Git’s features vs. some others.

Here are some reasons that I’d like to add, as many sites only list the technical aspects:

1. You can commit only specific lines. I often modify some files, adding more than one feature. I might have a bunch of files and only one of the features is complete, so I don’t want to include the modifications related to the incomplete one in the commit. With Git, I can choose only the lines that are relevant to the commit, and include those.
2. You can modify the commit, for example if you forgot to include a file in the commit, you won’t need to make a new commit for it. I often forget to include a file in a commit, so I keep making additional commits with the forgotten files - and I don’t like that.
3. It’s fast
4. You can “stash” your work - put your modifications away to a safe place and reset the files to the latest revision, and you can later get the modifications back easily

So should you try it?

Yes! Absolutely. I wasn’t convinced by just reading other people’s opinions about it as they never quite covered the things that I appreciate about Git now that I have tried it, so you too should definitely try it as it has a lot of useful features.

It may not be amazing enough to warrant moving all your existing repositories over to it right away, but I think it’s still worth giving a shot - who knows, maybe you have use-cases that I don’t, where Git can help you become more productive.