• when the system under test relies on an expensive resource
• when the system under test relies on a live resource
• when the system under test relies on a resource that doesn’t yet exist
• when I want to ensure that the system under test uses the resource correctly

I had to build a couple of client applications recently (twitter and flickr, since you ask – talk about re-inventing the wheel …), which interacted with what I consider expensive resources – firstly, I was contacting the remote flickr servers and awaiting their response each time I tested; secondly, the twitter API puts limits on how often it’s called, which means that I could run out of calls pretty quickly if every test made at least one call, and all tests were run each time I compiled the movie.

A couple of years ago, we built a googlemaps-stylee flash app for a certain weekend-break company to allow users to choose chalets (/lodges/huts/accommodation units – bizarrely ‘accommodation units’ was the official term) online. The units’ availability was updated in real time, so the app had to query the server for the latest data. The only problem with this was that the server application was still under design – it didn’t yet exist.

I’ve also worked with database developers who haven’t yet finalised their DB structure, and who keep dropping and re-building the database, which means deleting all the data that my test scripts rely on.

You only need to experience difficulties such as these a couple of times to realise that it’s imperative to have control of the remote/live/non-existent/under-development resource in order for the tests to be of any use.

The good news is that – in most cases – it’s possible to define an API for communication with the resource even before it exists, and that’s what makes mock objects so useful – they can honour the API, thus enabling the code we build against the tests to work against the resource when it’s ready.

Strikes me an example might be useful. Twitter suit you?

I have a TwitterView object, which takes a TwitterProxy which in turn communicates with the Twitter servers. I know it’s terrible – aren’t these chaps supposed to be cleanly separated? The TwitterView receives an event when the proxy has done all its loading, and then can populate the relevant TextFields. Easy, innit.

In the onTwitterLoaded function, you can see the two most important calls that we need to make on the TwitterProxy: getTitle() and getTweets(). I put these in the ITwitterProxy interface.

So now we have a fairly basic view, which expects its data from the proxy.

Let’s see it in action, courtesy of TwitterApp. Yep, not much happening:

We want to practise test-driven development – write a failing test > code until it passes > write another test > refactor – so we want to write a unit test that will check the view’s title and tweets, but (a) we can’t rely on the live twitter data as it will change over time, and (b) we don’t want to run up against the limit of API calls that we can make. Time for a mock object, methinks.

Firstly, I’m using ASUnit rather than FlexUnit, so if you’re following along, you’ll need to grab that and the ASUnitMockitoTestCase bridging class that I published one or two articles ago. Let’s start with a skeleton testcase:

Notice that we have a basic test that will show up as a fail in ASUnit, so that we can be sure that we’ve hooked everything together successfully. As soon as you see the fail, you can delete it. Note also that the call to super() starts with an empty Array – in time we’ll populate with the classes that we wish to set up as mocks.

Now, let’s pause for a think about what we want to test here – the View relies on the proxy for its data, so we want to check that the view gets its data successfully from the proxy without hitting the live Twitter servers. Oh, and the proxy doesn’t exist yet, just an interface.

I’m going to start really slowly here, forgive me – adding the assert that checks the view’s title.

Immediate compile error, since we haven’t declared view, so let’s add another line:

Still no success, because the TwitterView cannot be instantiated without a ITwitterProxy, which we don’t have, so let’s mock that (note that I’ve also added ITwitterProxy to the super() in the TwitterTest() constructor).

Huzzah – the movie compiles and we get our failing test For the record, mock() takes the interface and builds an object based on it that will record all calls made on its methods – it’s very, very clever.

First thing, let’s set the mockProxy up to give us the title string that we expect – add this line above the creation of the view:

This beautiful line of code says: if someone calls getTitle() on the mockProxy, the mockProxy will return “Twitter updates”. Isn’t that cool? Of course, that doesn’t help pass the test just yet.

The view is expecting to receive a TwitterLoadEvent from the proxy, triggering onTwitterLoaded(), so our mock object needs to have IEventDispatcher functionality. However, because the mockObject does so much weird stuff behind the scenes that I don’t have (and don’t want to have) a clue about, I’m going to attack this another way.

When mockProxy.addEventListener() is called, it will fire an immediate load event – this is mocking the request/response communication with the Twitter server. So what’s fireImmediateLoadEvent?

It’s a GenericAnswer object, which just holds a function that will be called when addEventListener() is called; in this case I want it to be like this:

Of course, in the real world, the proxy will be doing this as part of its work, but because we’re using a mock proxy, we have to work around it a bit. I’ve come up with this:

So now the test looks like this:

For completeness, here’s TwitterLoadEvent:

HashMap
I’ve deliberately picked a fairly uninteresting class, as I want to focus on the process. It’s a utility data-holding object found in Java, more formalised than the ubiquitous Object that’s found in Flash applications the world over. That I’m stealing from Java is good, as we don’t need to design it – we just need to implement the same API:

- size():Number
- put(key:Object, value:Object):Object //returns previous value associated with key, or null
- get(key:Object):Object //returns value mapped to key
- clear():Void //empties the HashMap
- containsKey(key:Object):Boolean
- containsValue(value:Object):Boolean
- isEmpty():Boolean
- keySet():Array //returns an Array of keys
- putAll(hashmap:HashMap):Void //puts the contents of another HashMap into this one
- remove(key:Object):Object {//returns previous value associated with key, or null
- values():Array //returns an Array of values

Handily that API gives us our to-do list for the exercise (though we won’t get through it all).

Setting up the project
Firstly, if you don’t have asunit already, have a read-through this post which sets it up.

Set up a directory for this exercise. Create a new Actionscript 2.0 fla** in there called hashmap_tester.fla.

Add two lines to the first frame:

Now test the movie.

It complains that it can’t find AllTests, so let’s create that:

and now testing throws no errors, and we’re good to think about the HashMap.

Where to start?
Why are we even going down this route? Well, I don’t know about you, but I have a habit of thinking about a class for 5 minutes and then jumping straight into coding it. On a large/formal project, I plan enough to come up with a convincing overview of the likely class structure, but don’t drill down to a detailed level. Look, a class diagram, let’s get coding!

So, other folks’ motivations may be different, but I follow a test-driven process because

• I need something to prevent me coding before I’ve thought about design, and
• I’m sick of leaving all thought of testing to the end of a project when we’re already squeezed for time

Therefore, we’re going to start with a single method from the Java API: size(), and define how we want it to behave (actually, the Java boys have already done that):

size():int – Returns the number of key-value mappings in this map.

Whilst that’s already clear, it’s not specific enough to write a test (humour me). So, let’s agree that calling size() on an empty HashMap will return 0, calling size() on a HashMap with a single entry will return 1, one with 2 entries will return 2, and so on. I know I’m stating the bleeding obvious, but these are the statements that will prove our job is done.

Setting up the testing class
TDD uses unit tests, which verify single units of functionality, so we end up with a single class (HashMap) being tested by a single test class (HashMapTest).

Now uncomment the line addTest(new HashMapTest()); in AllTests.as, and test the movie. We get a red bar and the following message:

0 out of 1 asserts passed

----------------
Item Failed at :
assertion : assertTrue
message : failingtest
methodName : testIt
className : HashMapTest

That’s the information we need – which class the problem was in, which method, which assertion, etc. Well, alright, we could have worked all that out, but once there are lots of classes, these pointers will be invaluable.

The rules of TDD are really simple: Red, Green, Refactor.
We’ve got red, which when considering we started with nothing is already a major achievement, so we need to take the next step. Change false to true in the assertTrue statement, and run the movie again. Whatcha got?

Green is cool, calming, and the place to be. In TDD, we start with red, get to green as quickly as possible, and stay there.

Since there isn’t much refactoring to be done with this test, let’s move on to writing a test for size(), starting with an empty HashMap.

Testing size()

Run it, and you get a compile error, which handily points out our next move: let’s create the HashMap class and give it a size() method returning a Number.

Testing shows we’re at red, which is progress.
Now all we need to do is get to green, in the simplest and quickest (and dirtiest) way possible. So, I’m changing return null to return 0.

Obviously, I’m tricking the test, because we should be testing that there are no entries in there, but that comes with refactoring. For now we’re just aiming to pass the test, and we do the simplest thing to achieve that.

What’s next: calling size on a HashMap with a single entry returns 1.
But, before we write that test, we need to think about how to put an entry into the HashMap

Putting something into the HashMap

put(key:Object, value:Object):Object //returns previous value associated with key, or null

So, again starting with the tests: the behaviour we’re specifying is:

• putting an element (with key “element1″ and value “value1″) into an empty HashMap returns null
• putting an element (with key “element1″ and value “value2″) into the HashMap returns the first element (key:”element1″, value:”value1″)
• putting an element (with key “element2″ and value “value2″) into the HashMap returns null

Since we know the compiler’s going to baulk, let’s avoid that by adding the following to HashMap.as:

Note that I’m returning key to force the test to fail. And fail it does, so change it to return null; and we’re green. Time to add another assertion. Just duplicate the first, so the same key is being added to the HashMap again, but change the assert itself to assertNotNull.

Dang, fix one thing, break another. Well, this is where the refactoring part of the triad comes in: we need to refactor the code so that it passes both tests. (”Refactor” is much better than “write”, don’t you agree? It means that the code is already written, but just needs changing. And that’s the point – it is already written in my head).

So what to do? Well the HashMap is essentially a wrapper around a Plain Old Actionscript Object, isn’t it? If we’re going to return the first element when we add the second, we need to keep those elements somewhere, so let’s create a private object to hold them in the HashMap.

Right, if a key doesn’t already exist in the HashMap, return null, but if it does return its previous value. How should that look?

Well, give it a go, since I’m coding without thinking too much, and let the tests decide. And they say ‘PASS’ – all is green. Fantastic. Let’s add the final part of our tests for put to HashMapTest:

And it still works! That’s cool.

Size() re-visited
So now we are able to put elements into the HashMap and have them stay there, we can end the trickery that’s getting us past the size tests.

Add another assert to testSize in HashMapTest.as:

That’s the test. I’m happy. It compiles and the asunit test runner shows red. I’m happier.

What is size() supposed to give us? Information about how many elements are in the HashMap, i.e. how many elements are in the private variable map. So we can just iterate through that, and keep a count of how many properties it has:

And I reckon that should pass.

To-do list
I’ve missed a good test out here – now we know size() is working, then we can use it to verify put’s behaviour. Specifically, if we add elements using different keys, size will increase each time; but if we add elements using the same key, then they will replace each other and the size will remain the same.

It’s handy to have a list – paper- or computer-based – nearby to record such thoughts when they appear, since you’re likely to be in the middle of writing a test or refactoring code to pass a test. It also allows you to prioritise, and to go home knowing you can return in the morning and know where to pick up.

Which reminds me. Always finish the day with a failing test. The next morning you turn up, run the tests, and know exactly what you were going to do next. That’s easy, isn’t it? (N.B. If you’re working in a team with source code control – you are, aren’t you? – do not check in this failing test, that might upset the others).

Homework
Well, when did someone last give you homework to do?
You write out the tests to cover the rest of the Java HashMap API. And, if you really fancy it, code the implementation too.

The TDD rhythym
1. Quickly add a test.
2. Run all tests and see the new one fail.
3. Make a little change.
4. Run all tests and see them all succeed.
5. Refactor to remove duplication.

Red, green, refactor.
Red, green, refactor.
Red, green, refactor.

* Test-Driven Development
** I’m currently working on a project porting AS1.0 to AS2.0, nary a sign of AS3.0. I believe that there are other AS2-ers out there who need information about unit-testing and test-driven development, so I’m fairly unapologetic about using AS2.0. If you are only coding AS3.0 (lucky you!) and can’t find resources, shout and I’ll have a stab at re-writing this for AS3.0, using flexunit.

They reckon that “urgency is acidic” – it burns out morale, especially when working towards an emergency deadline lasts more than a day or two (like, say 7 weeks plus – you know who you are!).

If your deliveries are that critical to the hour or day, maybe you’re setting up false priorities and dangerous expectations.

I re-read it several times, and each time it sunk in deeper just how important this concept is: this alone proves the worth of an agile approach to project development. Requirements go stale.

Most obviously, they run the risk of becoming obselete as the team and client’s understanding of the project evolves; but, equally importantly, they suffer atrophy simply through lack of use.

Once captured and defined, a requirement has a half-life – the longer it gets left in the requirements document without being actively worked on, the poorer the knowledge of that requirement. Clearly, if the developer leaves, the team suffers massive impact in its understanding of the requirement. But, even if the developer stays, their understanding and knowledge of the requirement withers as they work on other things.

The reality is that a requirement can rarely be so fully captured that it doesn’t depend on an individual’s understanding and definition of it.

The solution to this problem?

Define a sub-set of requirements that can be worked on within a specific timeframe. Move from requirements capture and definition to solution implementation within the same timeframe. Work agilely.

* Eli Schragenheim & David J. Anderson, Prentice Hall, 2003 (ISBN: 0-13-142460-2)