Now that we are able to authenticate a service with OAuth, we need to be able to actually use that service to do something useful.

Many popular web service APIs like Facebook and Twitter provide a REST based implementation.

In this post I’ll show you how to easily connect to one of these web services from Android and parse any responses you get back.

Should I use a REST library?

This is a valid question we should address before getting into the details.

My answer to this question is basically “no.”

I first tried the approach of using a REST library to make it easier to communicate to a REST based web service, but quickly found the overhead of the library was more than the benefit it provided.

If you come from a background of calling XML and SOAP based web services, you might be surprised by this answer.  With SOAP based web services it was a huge benefit to use a library to generate a proxy for you to call the web service and let you not have to worry about parsing XML and SOAP headers.

With REST it is completely different.  The whole point of moving to REST based web services is to simplify the process of calling web services.

Most REST based web service interfaces are extremely simple to use.  The idea is that the URL itself contains as much of the data as possible and additional data is included in the POST body.

By adding the complexity of learning a REST library and implementing the proper interfaces required to make it work seamlessly, we can easily add more complexity and overhead than just creating a HTTP request ourselves and parsing the responses.

For this approach I am going to show you how to do just that.

Calling the REST service

In order to call a REST service in Android we are going to first have to discover and understand the REST API provided to us, then make the appropriate calls with the OAuth token we got from authenticating.  Finally, we will parse the result of the call and get back our response.

Discovering the API

Because REST is not really a standard, but rather an ideal, there is not a standard way REST APIs are implemented.

You’ll have to take a look at the documentation for the REST API you want to call to figure out exactly what a call should look like.

In general though a REST API will involve making some kind of HTTP GET, POST, PUT or DELETE request and passing data through the URL or in the request body.

Here is an example of the Dailymile.com API which I have been recently integrating my app to use.

You can see the full API documentation here.

For this API, I am going to show you how I am creating a workout entry using a post.

Making the REST call

In order to make a REST call in Android, we are going to use a HttpClient object and the appropriate http request class.

In this example we are going to use the JSONObject class to create some data in JSON format that we can pass to the REST call by embedding it in the post.

I looked at the API for posting a workout entry to Dailymile, and the format of the request should look like this:

https://api.dailymile.com/entries.json?oauth_token=<token>

The API also indicates that it expects the post body to contain some JSON and gives us a list of required and optional entries that need to be in that JSON object.

Let’s take a look at how I am making this call and then we’ll break it down some.

HttpClient httpClient = new DefaultHttpClient();
HttpPost httpPost = new HttpPost(
	"https://api.dailymile.com/entries.json?oauth_token=" 
    + token);

httpPost.setHeader("content-type", "application/json");
JSONObject data = new JSONObject();

data.put("message", dailyMilePost.getMessage());
JSONObject workoutData = new JSONObject();
data.put("workout", workoutData);
workoutData.put("activity_type", dailyMilePost.getActivityType());
workoutData.put("completed_at", dailyMilePost.getCompletedAt());
JSONObject distanceData = new JSONObject();
workoutData.put("distance", distanceData);
distanceData.put("value", dailyMilePost.getDistanceValue());
distanceData.put("units", dailyMilePost.getDistanceUnits());
workoutData.put("duration", dailyMilePost.getDurationInSeconds());
workoutData.put("title", dailyMilePost.getTitle());
workoutData.put("felt", dailyMilePost.getFelt());

StringEntity entity = new StringEntity(data.toString());
httpPost.setEntity(entity);

HttpResponse response = httpClient.execute(httpPost);

You can see that I am first creating an HttpClient object and an HttpPost object.  The HttpPost has its URL set to the URL for the API call and I am adding a query string parameter to provide the OAuth token we got when when authenticated in my previous post.

I set the content type to be JSON so that we can get back a JSON object from the API call and so it knows that we are passing JSON data.

Then I construct a JSON object in the format specified by the API.  The way to construct the JSON object is to basically create a set of keys and values that are specified by the API you are calling.  In this instance I have a “message” key which I put the message data into. 

The only tricky part is that JSON objects can be nested.  So if you look at the key “workout” in the example above, I am creating a brand new JSON object to use as the value for that key which has its own subkeys which could contain more JSON objects.

Doing it this way is much more simple than trying to construct the string yourself.  The string we end up constructing will look something like this:

{"message":"fun!","workout":{"distance":{"value":5,"units":"miles"},

"activity_type":"running"}}

Finally, I put the JSON data into a StringEntity class and set it as the entity on the HTTP Post.  Then we can call execute on the HttpClient to execute the HTTP POST.

Handling the response

HttpResponse response = httpClient.execute(httpPost);
String responseString = EntityUtils.toString(response.getEntity());
JSONObject responseJSON = new JSONObject(responseString);
int workoutId = responseJSON.getInt("id");

All we are doing in this case is getting the response from the execute call on the HttpClient object, then using EntityUtils.toString to convert the response’s entity to a string representation.  Finally, we construct a new JSONObject from that string.

We can then easily extract any data out of the JSON object by using the methods on that JSON object that let us get typed values out of it.  For this example, I know that I am getting back some JSON that has a key “id” which is the id of the workout I created with my POST.

It is really that simple

The example I am showing you here is one of the more complex examples of calling a REST based API, because we are having to POST and parse JSON data.

In many API calls, you can just use an HTTP GET or a POST without any data to accomplish what you need to in the API.

Some REST based APIs will allow or require data to be passed in a different format, but most of them use JSON notation, which I find the easiest to work with.

Hopefully with these series of posts you can now authenticate against an OAuth 2 based service and make calls to the API to get and manipulate data in Android.

If you have any questions, feel free to drop me a line or post in the comments below.

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

Let’s talk about OAuth

The first thing you NEED to know about OAuth is that OAuth and OAuth 2.0 are not the same protocol.

From the OAuth guide on hueniverse:

OAuth 2.0 is a completely new protocol and is not backwards compatible with previous versions. However, it retains the overall architecture and approach established by the previous versions, and the same introduction (from the Official Guide to OAuth 1.0) still very much applies.

But, before we get into that, let’s talk a little bit about what OAuth is for.

OAuth basically does two things for a web site providing some kind of service or API that another application might want to use.

1. It prevents the consuming application from needing to store or have the user’s login and password.
2. It allows for a scoping of access to the producer’s services.  (For example, a user might be able to login to a site and access all of the features, but an app using OAuth might only be granted permissions to do certain things.)

So now that we know why, let’s talk about how both OAuth and OAuth 2 work from a high level perspective.

From the app developer perspective, the flow goes something like this:

1. You register your application with the service you want to access and get some unique identifiers for your application.
2. When you want to access something on the service, you make a request to the service using your unique identifier and telling it where to send the user after they authenticate.  (Usually you would launch a browser window here.)
3. User will login to the service using the browser window you launched for that service and choose to grant your application certain privileges.
4. The service will redirect the user to the callback url you provided and include a code you can use to get an access token.
5. You call the service one more time passing in your unique identifier and the code you got back and the service grants you an access token which you can use to access services you have been granted permissions for.
6. The next time you need to make a call you can just use that access token instead of going through this whole process again.  (At least till it expires.)

It really isn’t that complicated; the basic idea is that you tell the service who you are and ask the user the authenticate themselves and grant permissions to your application.  Then you prove that you got the response from the server and that it is still you and the service gives you a special pass to access the service.

The real difference between OAuth and OAuth 2 is the protocol itself, not the process.  So this is both good and bad.

Good, because we don’t have to change our process flow and understand something different.

Bad, because we can’t use the same libraries to access an OAuth 2 implementation as we do for an OAuth implementation and vice versa.  There is no backwards compatibility.

For the purpose of this post I am going to show how to use the Leeloo library to connect to an OAuth 2 service.

Connecting to OAuth 2.0

Download the library

The first thing you will want to do is to get the latest version of the Leeloo library.  It has moved to the Apache Amber project, so this link might change, but for now I found the ready to download binaries here.

Configure build path

Once you have the library downloaded you’ll want to add the following jars to your build path:

• jettison-1.2.jar
• oauth2-client.jar
• oauth2-common-0.1.jar
• slf4j-api.1.6.1.jar

Make initial request for authorization

Make sure you already have a unique client id created with the service you are going to access.  Most services out there like Twitter have a page where you can request one for your application.

Once you have this, you will use this to create a url that you will redirect the user of your application to.

In the code snippet below, I am creating the url and then creating a new Intent in Android that will open a web browser at that url.

OAuthClientRequest request = null;
request = OAuthClientRequest
       .authorizationLocation(authenticationUrl)
	   .setClientId("<your client id>").setRedirectURI("<your redirect url>")
		.buildQueryMessage();

Intent intent = new Intent(Intent.ACTION_VIEW,
        Uri.parse(request.getLocationUri() + "&response_type=code"));
startActivity(intent);

A couple of things to note about this code snippet:

• You’ll need to replace client id with your client id and redirect URI with your redirect URI.
• The redirect URI for an Android application is going to be some protocol that doesn’t really exist, but you can tell your application to respond to.  (We’ll cover that in the next step, but you might have some URI like myapp://oauthresponse)
• I had to add a “&response_type=code” to the end of my URL because the authentication service required it.  You might have to look and see how the service you are trying to access expects requests to be formed.

Configure your application to respond to your unique URI

In the previous step we had set the redirect to a unique URI like “myapp://oauthresponse”, now you will need to configure the activity you want to handle the response from the service to intercept that protocol.

You can do this by adding an intent filter to that activity like so:

<intent-filter>
	<action android:name="android.intent.action.VIEW"/>
	<category android:name="android.intent.category.DEFAULT" />
	<category android:name="android.intent.category.BROWSABLE"/>
	<data android:scheme="myapp" android:host="oauthresponse"/>
</intent-filter>

With this intent filter we are telling our activity to respond to a URI request in the form of “myapp://oauthresponse”.

Configure your activity to respond to handle the intent you registered to receive

Next we’ll want to set up an override in our activity to handle the new intent that will be called on our activity.  We can then pull the code the service gave us out and use that to request a real token.

@Override
protected void onNewIntent(Intent intent)
{
	Uri uri = intent.getData();

   if (uri != null && uri.toString()
           .startsWith("myapp://oauthresponse"))
	{
        String code = uri.getQueryParameter("code");
        // ...
   }
}

This code will allow us to respond to the intent that will be fired by the web browser when the service redirects the user to “myapp://oauthresponse.”

Exchange the code for a token

Next we need to get a real token instead of a code.  When the user typed in their username and password and granted access to our application, the server called our callback URI with a code that we extracted in the last step.

Now we can pass that code back up to the server along with our client secret and client id and get an access token.

OAuthClientRequest request = null;

request = OAuthClientRequest.tokenLocation("<service request URL>")
	.setGrantType(GrantType.AUTHORIZATION_CODE)
   .setClientId("<your client id>")
	.setClientSecret("<your client secret>")
	.setRedirectURI("myapp://oauthresponse")
	.setCode(code)
	.buildBodyMessage();

OAuthClient oAuthClient = new OAuthClient(new URLConnectionClient());

OAuthJSONAccessTokenResponse response = oAuthClient.accessToken(request);
String token = response.getAccessToken();

In this bit of code we are sending back to the server all the information we have that identifies our application as well as the code that proves the user allowed us to access that service.

Then we get back an access token from the server.  I would recommend you save this access token so that you don’t have to do this reauthentication in the future.

Wrapping it up

So what we have been able to do here is to redirect a user to the right page to authenticate our application, and then wire up our activity to respond to the redirect the service gives us in order to ultimately get an access token we can use to prove we are authorized to access that service on behalf of the user.

Be cautious though, because not everyone is implementing OAuth 2.0 exactly the same way, since the spec is not finalized.  So you might run into issues where things aren’t working exactly as laid out in this post.  If that is the case, you may have to modify a URL that is generated or something along those lines.

In my next post, I’ll show you what you can actually do with your authorization token.  We’ll go through calling a REST based API web service from Android.

Feel free to post any questions in comments.  I used this code to connect to the Dailymile.com API in my PaceMaker application.

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

Not to say that you’ll ever be done expanding your automation framework and building and improving your BATs, but you are at the point of having a mature usable BAT framework and you can be proud of that accomplishment.

If you truly want to see where the rabbit hole goes though… Read on

Taking it to 11

If you have designed a good automation framework for writing your BATs, you will most likely have created an internal domain specific language (DSL).

What is an internal DSL?

Basically it is a set of APIs and rules built in another language that function as their own language.

You might have some code that looks like this:

Pages.Login.Goto();
Pages.Login.LoginWithDefaultUser();
Pages.Customers.Goto();
Pages.Customers.AddNewCustomer();

You can see how this code is really looking like a language itself.  It is hard to tell if this code is even C# or Java.

This is a good example of an internal DSL.

If we were to take this same section of a BAT test and write it as an external DSL, it might look something like this:

LOGIN WITH DEFAULT-USER
ADD-CUSTOMER WITH DEFAULT-CUSTOMER

With a true DSL we can simplify even further to get right down to the bare minimum set of commands we need to execute what we want in our application.

How to implement a DSL?

There are a number of tools and techniques that can be used to create a DSL.  I’ll hit on some of those a bit later on, but first we need to design the DSL itself.

Designing a DSL can be challenging, but I have found the best approach is to use a similar approach to what we used to design our automation framework.

It is best to work backwards from the syntax that would make your BAT the easiest to write and the most clear.  Once you have done that you can worry later about implementing the DSL to support the syntax you have come up with.

You should focus on creating a limited vocabulary for your DSL so that it will be easy for someone to learn and know what their options are.

The more restrictions we put into a DSL the easier that DSL becomes for doing a specific purpose.

We want to give the user of a DSL no more options than required for what they want to do and no less.

This isn’t always easy to do.  It often requires some careful thought and refinement.

Your DSL should also use terminology and phrases that are familiar to the business domain of your application.  By doing this you will make it so someone understanding your application will understand BATs written in that DSL.

I also always try to make a BAT DSL read as much as plain English as possible.

Once you have designed the DSL, you will need a way to implement it. 

I’ve written about using ANTLR to create an external DSL.  Also I have written a review on a book that I recommend for learning ANTLR.

Microsoft also has a DSL SDK you can use in VS2010, although I haven’t used it myself.

The basic idea behind implementing a DSL is that you have to take some sort of grammar you design for your DSL, parse it into a syntax tree, then use that tree to generate code that will actually perform the actions.

It is by no means a trivial task, but using a tool like ANTLR, makes it much simpler than trying to completely generate a parser and execution engine yourself.

Why even bother?

Creating a DSL for your BATs is completely optional, but there are some significant benefits to doing so.

The biggest one I have found is that you are much more likely to get business people to write BATs if you have a simple DSL they can use to create them.  Once you get everyone using BATs to define behavior and requirements, communication becomes much more simple.

Another great thing about creating a DSL is that you can create a runner that can interpret the DSL BAT scripts which can be run on any machine.  Typically, to run BATs created in Java or C#, you would need a C# or Java compiler and a test runner, etc.  By creating a DSL and a stand alone executor, you can very easily allow anyone to run BATs with little to no setup.

Writing your BATs in a DSL will also make writing the BATs and understanding them much easier.  A good DSL can get rid of all the little language and API nuances that don’t really add information to the specific domain you are working in.  A good DSL strips information down to the minimum amount needed and is able to do so, because it assumes the context is your application’s business domain.

You will also find that you are better able to separate framework from tests when you have a DSL in place.  One issue that many teams face when creating a BAT framework is that some people come along and write lower level code in the higher level BATs.  This creates a problem because it is hard to force someone to use the higher level API when the framework and the BAT code are the same language.

Wrapping it up

So that completes my series on Getting up to BAT.

Hopefully you have learned enough to be able to implement your own BAT framework and get BATs running for your application.

I tried to cover most of the important steps here without getting too deep into the details.

If you have any questions or are interested in getting more in depth training or consulting on getting BATs setup for your environment, send me an email or leave a comment.

It can be a little difficult to get started and get a BAT framework up and running, but the rewards are well worth the effort!

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

Now you are probably faced with the difficult decision of…

Where to begin with your tests

I don’t suggest writing your automation framework first and then writing tests to use it.  If you go this route you’ll have two problems

1. It will be a long time and large investment before you see any fruits from your automation effort.
2. Your framework will likely be designed incorrectly or not test-writer friendly.  (Which is basically the same as wrong.)

What you really want to do is to write some basic tests that let the development of those tests drive the development of your framework.

The best tests to drive your framework are some basic “smoke tests.”  If you are not familiar with the term “smoke test,” it basically means some tests that make sure the application you are testing is at least somewhat working and not completely broken. 

There are a few different opinions of what exactly constitutes a smoke test, but in general, if you have any tests that you regularly run on a new build to make sure it is at least OK, those would be the tests we are interested in here.

You are going to want to start by taking the easiest and most simple tests you have and writing them in a concise syntax that you use to drive the development of your framework.

It is very important at this stage to not worry about what you think might be possible or how it would be implemented in the framework, but to instead focus and making the tests as terse and explanative as possible.

The basic idea is that you will write the test out in the syntax you would like to be able to use, then implement the framework features required to make that test pass.  This whole process is very similar to doing Test Driven Development.

An example case

The easiest way to demonstrate this is with an example.

Let’s say you have a smoke test like the following:

Create a new account, pick an on-sale item, add it to your cart and check out using PayPal.  Verify that we hit the order success page.

We might write a test for this that looks something like:

Workflow.Users.CreateNewUser();
Pages.Login.LoginWithLastCreatedUser();
Pages.SaleItems.AddAnyToCart();
Workflow.Cart.CheckoutUsingPayPal();
Assert.True(Pages.Checkout.SuccessPage.IsAt());

What I just wrote above is astonishingly simple.  You are likely saying to yourself something along the lines of “What if… blah.”

Forget it!  We’ll handle “what if” later.  Right now we are going to write the tests as terse as possible and not handle any other conditions.

What I wrote above is the style that I like to write the tests in, which is highly subject to opinion, but the content of what I wrote is not as subjective.

There are a few important points to note:

• I used methods like CreateNewUser, LoginWithLasteCreatedUser and CheckoutUsingPayPal that do a huge amount of work and have no parameters.  Why?  Because for the purpose of this test, (and you’ll find for most of your tests), we don’t care about what the first name or last name or address of the user is, we don’t care how we get them logged in, and we only care that they checkout using PayPal, not what account is used, etc.
• I didn’t declare any variables.  Tests should be simple.  Let the framework remember the state.
• I over-simplified.  This is fine, you are working inside of a very specific domain.  Let your test framework methods do one large thing.  Don’t worry about oversimplifying for now.
• I asserted something at the end.  All tests need to assert something.  If you can’t figure out what to assert, work on redesigning the test before automating it.
• I didn’t pass parameters.  Avoid this also.  This goes along with the first point, but is so important that I feel it is OK to state it twice.  If you don’t care about variation, eliminate it.  You will constantly need to find places where a manual tester would have to enter specific information, but an automated test won’t care what that information is.
• All my methods are static.  While this would be bad in normal production code, for a test API it is the easiest for test writers to use.  No variable declarations, no “newing” up objects, no constructors, etc.
• It’s written in “business language.” As close to the language an end user or business person would use to describe the test.

So, this test is definitely doing a huge amount of stuff in a few lines of code, and because of this your inclination would be to say that the API level is too high. Don’t!

Instead, make the API level as high as you possibly can, until further tests you try to implement prove to you that it must be broken down further.

By working this way, you ensure a reduction in the total lines code and complexity of your tests by as much as possible.

You would NEVER work like this with normal code, but for automated tests this is essential.  The main reason is because you will be calling the same methods perhaps 1000s of times, where in normal code you usually only reuse a method in a few places.

Next steps

For my example above, the next step would be going through and implementing all the framework methods required in order to make that test runnable.  You will end up utilizing the general design you came up with for your automation framework to do this.

Then you will simply move on to the next test and repeat.  Each time you should have less and less effort required, as more of the basic functionality of your automation framework is implemented.

Automating your smoke tests should ensure that you get a fairly even distribution of the framework code written as the smoke tests should cover many different areas of your software.

But, don’t start adding these smoke tests to your build yet.  We’ll cover that in the next step.  Adding them to the build prematurely can cause the confidence in these tests to be forever diminished!  We don’t want to do that!

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

Automation tools that claim to support multiple browsers are LYING

Currently I am in the process of getting 400 automated tests that run in Firefox to run in Internet Explorer and Chrome. While the tests are using Selenium RC, a tool that claims to work on all three browser platforms, in actuality, many tests are failing and not for good reasons (bugs).

Here’s the rundown on what these overly-ambitious tools aren’t telling you:

• Xpath in Browser A isn’t always supported in Browser B
• The Dom in Browser A may vary from the Dom in Browser B
• Browser B may have built-in security settings that interfere with testing
• Bugs in the automation tool itself may cause issues in specific browsers

When it comes to XPath, I fully expected that any given expression was either valid or invalid. But it didn’t take more than one test run in Internet Explorer to suddenly find myself with tests that claimed certain elements didn’t exist. While Firefox accepted and successfully returned my element using the provided expression, IE claimed the expression itself was invalid. In this particular instance I discovered an issue with Selenium stripping off the end of my xpath statement, thus making it invalid.

But ultimately, whether it’s the browser or the tool doesn’t matter because the same expression is not working unequivocably in both browsers.

The Dom Issue

The next problem I immediately came across was the problem of Dom differences between browsers. In this particular case I had an element that occurred one time in Firefox but twice in IE. My test, expecting one instance of the element, failed. While I can’t tell you why this discrepancy exists (currently under investigation by some client-side engineers), I have a fair degree of confidence in saying this won’t be the last time I come across this issue.

In the quest to support many different browsers, it only follows that one is going to come across conditional browser logic, especially if a company is striving to support multiple browser versions (IE 6, 7, 8, 9). If a developer has to occasionally write browser-specific condition statements, it makes sense that we’d have to do the same to test specific browsers.

The Security Issue

If it seems that I’m picking on IE, it’s only because I can’t get very far in running our tests in Chrome. Chrome has special security settings that cause a Selenium exception if your test changes domains mid-run. This can easily be solved by passing a parameter to Chrome which will disable this security feature when the test runs, the trick is figuring out when/where/how to pass that parameter.

The Bug in the Tool Issue

Finally, the last obstacle I’ve come across in multi-browser testing: the tool itself. Any tool, regardless of how fabulous it is, is going to have bugs. Selenium RC has an issue where its select method (responsible for selecting a value in a dropdown menu) doesn’t trigger affiliated event handlers- in Internet Explorer. To work around this, one can manually call the event handler using Selenium’s runscript() but you will lose some degree of testing confidence in doing so (how do you know the event is really firing in response to a particular user action if you’re manually forcing it in automation?)

Another issue exists around multiple browser windows; if you need more than one open for your test, Selenium is unable to select the second window you open- another outstanding IE issue that has not been resolved.

Summary

In all fairness, some of these issues have more to do with the browsers themselves than with the automation tool. However, that makes it even more important to realize that when an automation tool says it supports multiple browsers, it’s not without some creativity, troubleshooting, legwork, and maintenance.

Knowing these kinds of issues exist is important in order to decide if and how much browser compatibility testing you want to automate. It’s definitely something to realize before deciding on a tool just because the tool claims to support other browsers.

Just as there is no silver bullet for writing a web application that works in every browser imaginable, there is no silver bullet for automation either.

This is one of the most critical components of the overall success of your automation strategy, so you will want to make sure you invest properly in this area.

I have seen a large number of automation projects go forth, but each time the critical component determining their success or failure was having a good automation framework.

Solid design and excellent technical resources are absolutely critical to success in this area!

What is an automation framework?

An automation framework is essentially an API that all of your BATs (Blackbox Automated Tests) are written against.

This API can be as simple as the API that is exposed by your browser automation tool (WatiN, Selenium, etc.), but I would highly recommend building your own layer on top of the browser automation tool’s API that will act as a DSL (Domain Specific Language) for automating your application.

Let me break this down a bit further by using an example.

Think about the task of making coffee.

There are several “API” levels we can interact with.

1. We can go with a very low level API where we take whole coffee beans and grind them down.  Then we take some water, get it hot.  We take our filter put the ground beans in it, put it over a cup and pour the water into the filter.
2. We can go with a higher level API where we use a traditional coffee maker.  In this case we load the coffee maker with a filter, ground coffee beans and water and push a “brew” button.  We could also set it to start at a certain time.
3. We can go with a very high level API where we use a Keurig machine or similar device.  In this case we only make sure the machine has water in it, and we just insert a little pod and press brew.  We can make different kinds of coffee, cider or hot cocoa just by changing what pod we use.

Using the API provided by the browser driver is like making the coffee by hand.  It’s going to take a large amount of effort each time you do it.

We want our automation framework to be more like the Keurig machine.  We want to be able to compartmentalize our tests in little pods that are small and don’t require many hooks into the automation framework.

To rehash this one more time, basically our automation framework will be a framework we build on top of the browser driver framework, which is designed to make it easy to write tests which automate our application.

What makes a good automation framework design?

The true measure of an automation framework is the size of the tests that are written against them. The less lines of code in each test, the better the automation framework captures the domain of the application being automated.

In my earlier post about an example of an automation framework, I talked a bit about the strategy I used in a real implementation of an automation framework.

Here is a diagram showing the different layers.  You can see the framework layer is in green here.

You can also see in this diagram that on the right hand side, I have screens, workflows and navigation.

This is one of the common design patterns you can use to build your automation framework, since it closely models that of most web applications.

A good way to design your framework is to use a pattern like this and create classes for each page in your application, create classes which might represent workflows in your application, and create some classes for navigating around the application.

The basic idea you are shooting for with your automation framework is to make it so the tests do not have to know anything about the browser.  Only your automation framework itself should be dealing with the DOM and HTML and CSS.  Your tests should be dealing with concepts which any user would be familiar with.  That is why I commonly use pages and workflows.

Let me give you an example.

Let’s say we ignored the advice of creating an automation framework and decided to program our tests directly against the browser driver layer.  In this case, let’s say that we want to automate a login page.  Our test might look something like this pseudo-code.

browser.goto("http://mywebsite/login.aspx");
Element userName = browser.getElementById("login_userName");
userNameTextField.Type("Joe");

Element userPassword = browser.getElementById("login_userPassword");
userPassword.TextField.Type("mypassword");

Element loginButton = browser.
    getElementByXPath("//button[class="loginButton"]");
loginButton.Click();

This is not very readable.  It is not something an average tester will be able to pick up and start writing, and it is extremely fragile.  If you have 500 tests like this and the id changes for one of the elements on the page, many tests will break.

Now, contrast it to this pseudo-code:

Pages.Login.Goto();
Pages.Login.LoginWithDefaultUser();

Where did all the code go?  You don’t need it!  Actually it went into the framework, where it can be reused.  Now your test code is simple, can be understood by just about anyone, and won’t break with changes to the UI.  (You will just have to change the framework method instead of 500 tests.)

If you want some more detailed examples take a look at my Boise Code Camp slides on the subject here.

Let me offer up some general guidelines for creating a good design for an automation framework.

1. NEVER require the tests to declare variables.
2. NEVER require the tests to use the new keyword or create new objects.
3. NEVER require the tests to manage state on their own.
4. ALWAYS reduce the number of parameters for API calls when possible.
5. ALWAYS use default values instead of requiring a parameter when possible.
6. PREFER to make the API easier to use over making the internals of the API less complex.
7. PREFER using enumerations and constants to requiring the test to pass in primitive types.  (Make the input bounded when possible.)
8. NEVER expose the browser or DOM to the tests or let them manipulate it directly.

You can see that these guidelines will almost force your API to be entirely static methods!  Don’t freak out.  It is perfectly fine.  There is nothing wrong with using static methods in this case.

Stop… take a breath, think about why you think static methods are bad, because I probably agree with you.

But, in this case we are HIGHLY valuing making the tests simple and easy to write over anything else, and because of this emphasis, static methods are going to be the way to go.

Some advice on getting started

Start with the tests in plain human English.

Take those tests and make them into code preserving as much English as possible.  Then work down from there implementing the methods needed to make those tests work.  Only add things as you need them.  Do not overdesign!

In my example above, we might have started with something like this:

1. Goto the login page.

2. Login with the default user.

The actual code looks just like that.  It should always be a 1 to 1 mapping.

This is where having someone that has some experience doing this is going to come in handy.

Just keep in mind the whole time your 2 big goals:

1. Easy to write tests
2. Tests are concise

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

In my last post in the Back to Basics series, I mentioned that I would begin this series with the intent of showing you step by step how to go from no automation to a quality BAT infrastructure.

By the end of this series you should have the information you need to actually get automated testing going in your organization instead of just talking about it.

First stop on this train is hiring an automation lead.

Don’t doom yourself before you start

If you think you are going to create BATs, but you are not going to have at least 1 dedicated resource to doing the job of getting this all going, you are probably bound for failure.

Listen up, because this is the single biggest mistake that most organizations make when trying to get BATs up.

This mistake is thinking that you can get your QA team to get this going and you can part time some developers onto the project, but not having a dedicated resource.

Why is this absolutely absurd and you should expect it to fail?  Because, in order to get an infrastructure to support your BATs, you are going to need to basically design and create a testing framework that is tailored to the business domain of your application.

Blah, what?  Ok, in simple terms.  Someone is going to need to design and build an automation framework.

If you think you are just going to buy some tool and use it to record test scripts, you are wrong.  That approach simply is not going to work.  I won’t get into why here, but I have written on it before in the past, and if you are interested, let me know and I’ll go much more in depth.

Think about this, do you want your QA team, as good as they may be at QA work, designing and building an automation framework?  Give them a few C# or Java classes and have their first real coding work be to design a complex system?

How about a developer who has “real” work and can only devote part time to designing what may end up becoming one of the most important parts of your infrastructure?

It is fine to pull a developer off of the main product and put them in this role until it is up and running, but make no mistake, you need a dedicated resource.

You are going to want to a well designed maintainable automation framework, because the ease of use of that framework will determine how easy or not it is to write automated tests that use that framework.

I recommend getting someone who has done it before

Why?  Because creating an automation framework is much different than developing your software and it is much different than writing tests.  It really requires a special skill set that is not so easily acquired without the experience of having done this before.

I also think it is fine to use a developer resource, but if you do, you want to try to get a more senior developer to take this role.

Here is a list of some of the skills that I think are important which may also make it much more clear why I am recommending a specialist in this case:

Development of APIs (In the end the automation framework will be an API that is used to write automated tests.  The better the API is designed, the easier it will be to write tests against it.)

Design of reusable base components (Much of the framework consists of repeated concepts with different variations for different screens in your application.  As a result, the core of the framework will be a basic design that allows for variation without too much repetition… reuse)

Ability to quickly acquire domain knowledge of the software (Someone writing an automation framework needs to really understand how the system under test works, so that they can model the framework after it.)

Pragmatism (Many “accepted” good software designs are actually bad automation framework designs.  Static methods can make an automation framework’s API much more simple to use, especially for non-programmers, but would not be a good design choice in your main product.  A person who designs an automation framework should be pragmatic enough to “break the rules” in order to make the framework easiest to use and maintain.)

Experience or understanding of QA (It is important to understand the users of the framework, the QA team.  Understanding what kind of tests they will likely write or how they will think will go a long way in coming up with a good framework design.)

Communication skills (Good BATs read like English.  It is critical to make sure that the person designing the framework facilitates this to make the BATs as useful and understandable as possible.)

HTML / XPath (This specific skill set is very important for web based products.  Creating an automation framework built on top of one of the web browser drivers will require intimate knowledge of HTML and probably XPath to be able to access attributes and elements on pages in your application.)

I’ve written a few automation frameworks and contributed to the design of several others, and I can tell you that my version 6.0 of an automation framework was much much better than version 1.0.

There are a huge number of patterns that emerge that are unique to this problem domain.  So, I do believe having experience in this area specially is a huge benefit.

What does this automation person do?

We’ll get to more specific in my later posts in this series, but the basic responsibility should be:

• Figure out the technology and tools to be used
• Create the initial automation framework
• Create smoke tests for the application under test
• Get those smoke tests into some kind of automated build
• Train developers and QA in the use of the framework
• Drive the adoption of the framework and automation for all features
• Set up rules for consistency in writing automated tests
• Design of hierarchy and structure of automated tests

You want your automation person to be responsible for pushing and driving forward the goal of getting to the point of being able to automate each feature being created with minimal effort.

This is one of those jobs that can actually be “done.”  What I mean by that is you may have the automation lead end up creating the framework, developing it enough to push it out to your development teams and train them to write automated tests along with QA, and you really don’t need an automation lead anymore.

This is great though, because now you have a developer that really knows your product and is a good bridge to QA, or you can keep them improving the framework and overseeing it if you want to go that route.

Bottom line is:

1. Make sure you get a dedicated resource
2. Make sure that resource can write code and design a framework
3. Make sure they train everyone else, one person cannot automate your entire application

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

First month of sales are over, and it was much better than I had expected.  About 75 purchases in the first 30 days.  Not a huge amount, but that is almost with no advertising, most people who found the app found it in the market.

So what is the next step for PaceMaker?

Well, with the iPhone coming to Verizon this month, I think it is pretty obvious that it is time for the iPhone version.

Only problem is…

I know nothing about iPhone development!

Well I didn’t last week, but I am slowly learning.

I bought my first Mac ever last week, a MacBook Air.

I have to say, the operating system on Macs has come a long way since I last used one.  (Did I mention I also don’t even know how to properly run a Mac?  But I know Unix, so I should be ok.)

I feel like the Mac interface is so much more polished and uniform than Windows, but it is pretty scary inside when you consider all the low level C and Objective C code.

Then again you have to consider that the wonderful .NET CLR is written right on top of a really crusty win32 API layer which is a bunch of scary C code that is about 20 years old.

So I am setting out on a brave new quest to learn Mac, iPhone and Objective-C and somehow port my application over to the platform.

Objective-C is kind of like an alternate universe

I was trying to think how I would describe Objective-C and here is what I came up with:

Objective-C is like one of those movies where there is an alternate universe where the same people exist as in this universe, but in some areas their technology is really advanced, but in others it’s really ancient.  Like a bunch of people flying around in flying cars, but their weapons are still bows and arrows.

I used to be a C++ programmer, so not too many things scare me, but some of the magical constructs in Objective-C are very frightening indeed.

I was just reading about a strange construct today that allow you to basically create the equivalent of a C# interface, but in Objective-C it is called a “Protocol.”  This seems fine and normal until I read the paragraph that says you can define some of the methods as “Optional.”  What?

Let me put it in C# terms so you can understand it.  In C# it would look like this:

public interface ILovePuppies
{
   private void HugThem();
   private void SqueezeThem();

   perhaps Corpse KillThem(); // Implement this one
                              //only if you feel like it.

}

This is not a joke.  I still can’t quite figure out what this is for, but it is kind of interesting.

Another thing I found interesting is Objective-C has this thing called a “Selector.”  It is not a function pointer, it is a variable that references the name of a method.

How is this different than a function pointer?

It is actually the name of the method being referenced.  So if you have a class Dog that has a method “Wag” and you have a class WildGuesser who has a method “Wag”, passing them the “Wag” selector will cause very different results.  How bizarre.

It’s weird to get sucked into the Mac world

It’s actually kind of funny.  Here were all us Java and C# programmers off basically doing the same thing; creating our interfaces and arguing about dependency injection and mocking our unit tests and these Mac geeks with their bow ties and designer jeans were going a totally different direction.

It was only by random chance that our two parallel universes should violently collide.  The iPhone came out and suddenly all these strange “Mac boys” were teaching us this new old language and reminding us to free up own memory again.

FOR GOD’S SAKE I JUST IMPORTED A C HEADER FILE FOR THE FIRST TIME IN 10 YEARS!  THIS IS CRAZY!

But, I have to admit it is actually kind of fun.

Sometimes a change of pace is refreshing

I don’t mean my harsh language to be derogatory towards you Mac heads out there.  You know you are cool, your boy Steve is leading this century’s computing revolution.

I honestly mean that.  Good job guys, you may just take over the world.

I’m actually enjoying this experience and beginning to think that if I come out alive, I will have gained some very valuable insights into programming in C# and Java.  It is good sometimes to view something from a totally completely different perspective.

Who knows maybe I’ll get to write that Objective-C vs Java vs C# post I’ve been dreaming of.

But what about…

MonoTouch?

Meh.  If I am going to program for a platform, I am going to program for that platform.  I’m not going to half learn how to program for the iPhone and learn on the C# crutch.  I didn’t do that for Android and I’m not going to do it for iPhone either.

Why?

Because I am stubborn and cranky?  Partially, but I actually have a few sensible reasons also:

1. MonoDroid and MonoTouch both implement another layer over the phone’s framework.  Adding this additional layer makes it harder to do low level stuff, and with something as low level as a phone, doing low level stuff is often important.
2. You are still using the underlying framework for either Android or iPhone.  It is not like using C# code behind the scenes allows you to write a Silverlight UI that you can use on any of the mobile platforms.  You still have to learn the entire phone development framework, which dovetails into point three…
3. It is much easier to get help and find resources for raw Android or iPhone development than for MonoX development.  Not trying to bash the Mono projects here, but most of mobile programming is spent googling for how to do things.  By sticking with C# you are really limiting yourself in terms of finding answers.
4. Change and learning different things is good.  I’m not sure you can fully appreciate the design of a framework or platform unless you develop against it the way it was designed.  I could be wrong, but I think there is a potential “lost in translation” problem in using C# on the iPhone or Android platforms.

After I learn iPhone development, I might try MonoTouch and see if it makes my life easier, but I need a good baseline first.

Well, I’m off on my journey.  Going to head on to the back of the wardrobe in the “Spare-Oom.”  I have to meet Mr. Tumnus, we are having tea with Mr. Wozniak and Mr. Jobs.

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

We’ve talked about what an interface is, cohesion and coupling, and even went a little bit off track to talk about sorting for a bit.

One of the reoccurring themes that kept showing up in most of the posts was unit testing.  I talked about why unit testing is hard, and I defined three levels of unit testing.

• Level 1 – we have a single class with no external dependencies and no state.  We are just testing an algorithm.
• Level 2 – we have a single class with no external dependencies but it does have state.  We are setting up an object and testing it as a whole.
• Level 3 – we have a single class with at least one external dependency, but it does not depend on its own internal state.
• Level 4 – we have a single class with at least one external dependency and depends on its own internal state.

Throughout this series I ended up tearing down using interfaces with only single non-unit test implementation.  I criticized the overuse of dependency injection for the sole purpose of unit testing.  I attacked a large portion of best practices that I felt were only really being used in order to be able to unit test classes in isolation.

But, I never offered a solution.  I told you what was bad, but I never told you what was good.

I said don’t create all these extra interfaces, use IoC containers all over your app, and mocks everywhere just for the purpose of being able to isolate a class you want to unit test, but when you asked me what to do instead, I said “I don’t know, I just know what we are doing is wrong and we need to stop.”

Well, that is no answer, but I intend to give one now.  I’ve been thinking about this for months, researching the topic and experimenting on my own.

I finally have an answer

But, before I give you it, I want to give you a little background on my position on the subject matter.

I come from a pretty solid background of unit testing and test driven development.  I have been preaching both for at least the last 7 years.

I was on board from the beginning with dependency injection and IoC containers.  I had even rolled my own as a way to facilitate isolating dependencies for true unit tests.

I think unit testing and TDD are very good skills to have.  I think everyone should learn them.  TDD truly helps you write object oriented code with small concentrated areas of responsibility.

But, after all this time I have finally concluded, for the most part, that unit tests and practicing TDD in general do more good for the coder than the software.

What?  How can I speak such blasphemy?

The truth of the matter is that I have personally grown as a developer by learning and practicing TDD, which has lead me to build better software, but not because the unit tests themselves did much. 

What happened is that while I was feeling all that pain of creating mocks for dependencies and trying to unit test code after I had written it, I was learning to reduce dependencies and how to create proper abstractions. 

I feel like I learned the most when the IoC frameworks were the weakest, because I was forced to minimize dependencies for the pain of trying to create so many mocks or not being able to unit test a class in isolation at all.

I’ve gotten to the point now where two things have happened:

1. I don’t need the TDD training wheels anymore.  I don’t pretend to be a coding god or demi-god of some sort, but in general the code I write that is done in a TDD or BDD style is almost exactly the same as the code I write without it.
2. The IoC containers have made it so easy to pass 50 dependencies into my constructor that I am no longer feeling the pain that caused my unit tests to cause me to write better code.

What I find myself ending up with now when I write unit tests is 70% mocking code that verifies that my code calls certain methods in a certain order.

Many times I can’t even be sure if my unit test is actually testing what I think it is, because it is so complex.

Umm, did you say you had an answer, dude?

Yes, I do have an answer.  I just wanted to make sure you understand where I am coming from before I throw out all these years of practical knowledge and good practices.

I am not the enemy.

My answer to the problem of what to do if you shouldn’t be using IoC containers and interfaces all over your code base just for the purpose of unit testing, is to take a two pronged approach.

1. Mostly only write level 1 or level 2 unit tests.  Occasionally write level 3 unit tests if you only have 1 or possibly 2 dependencies.  (I’ll talk about more how to do this in my next post)
2. Spend a majority of your effort, all the time you would have spent writing unit tests, instead writing what I will call blackbox automated tests or BATs.  (I used to call this automated functional tests, but I think that name is too ambiguous.)

I intend to drill really deep into these approaches in some upcoming posts, but I want to briefly talk about why I am suggesting these two things in place of traditional BDD or TDD approaches.

What are the benefits?

The first obvious benefit is that you won’t be complicating your production code with complex frameworks for injecting dependencies and other clever things that really amount to making unit testing easier.

Again, I am not saying you shouldn’t ever use dependency injection, interfaces or IoC containers.  I am just saying you should use them when they provide a real tangible value (which most of the time is going to require alternate non-unit test implementations of an interface.)

Think about how much simpler your code would be if you just went ahead and new’d up a concrete class when you needed it.  If you didn’t create an extra interface for it, and then pass it in the constructor.  You just used it where you needed it and that was that.

The second benefit is that you won’t spend so much time writing hard unit tests.  I know that when I am writing code for a feature I usually spend at least half the amount of time writing unit tests.  This is mostly because I am writing level 3 and level 4 unit tests, which require a large number of mocks.

Mocks kill us.  Mocking has a negative ROI.  Not only is creating them expensive in terms of time, but it also strongly couples our test classes to the system and makes them very fragile.  Plus, mocking adds huge amounts of complexity to unit tests.  Mocking usually ends up causing our unit test code to become unreadable, which makes it almost worthless.

I’ve been writing mocks for years.  I know just about every trick in the book.  I can show you how to do it in Java, in C#, even in C++.  It is always painful, even with auto-mocking libraries.

By skipping the hard unit tests and finding smart ways to make more classes only require level 1 and level 2 unit tests, you are making your job a whole lot easier and maximizing on the activities that give you a high ROI.  Level 1 and level 2 unit tests, in my estimation, give very high ROIs.

The thirds benefit is that blackbox automated tests are the most valuable tests in your entire system and now you’ll be writing more of them.  There are many names for these tests, I am calling them BATs now, but basically this is what most companies call automation.  Unfortunately, most companies leave this job to a QA automation engineer instead of the development teams.  Don’t get me wrong, QA automation engineers are great, but there aren’t many of them, good ones are very expensive, and the responsibility shouldn’t lie squarely on their shoulders.

BATs test the whole system working together.  BATs are your automated regression tests for the entire system.  BATs are automated customer acceptance tests and the ROI for each line for code in a BAT can be much higher than the ROI of each line of production code.

Why?  How is this even possible?  It’s all about leverage baby.  Each line of code in a BAT may be exercising anywhere from 5 to 500 lines of production code, which is quite the opposite case of a unit test where each line of unit test code might only be testing a 1/8th or 1/16th a line of production code on average (depending on code coverage numbers being reached.)

I’ll save the detail for later posts, but it is my strong opinion that a majority of a development teams effort should be put in BATs, because BATs

• Have high value to the customer
• Regression test the entire system
• Have a huge ROI per line of code (if you create a proper BAT framework)

Imagine how much higher quality your software would be if you had a BAT for each backlog item in your system which you could run every single iteration of your development process.  Imagine how confident you would be in making changes to the system, knowing that you have an automated set of tests that will catch almost any break in functionality.

Don’t you think that is worth giving up writing level 3 and level 4 unit tests, which are already painful and not very fun to begin with to achieve?

In my future posts on the Back to Basics series, I will cover in-depth how to push more of your code into level 1 and level 2 unit tests by extracting logic out to separate classes that have no dependencies, and I will talk more about BATs, and how to get started and be successful using them.  (Hint: you need a good BAT framework.)

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.

One of the most common misunderstandings and frustrations I see from developers is around sorting.

Almost every developer has faced needing to sort a list of things in some manner in their development careers.  Many developers end up fumbling through it, looking for an example from the web and then copying that example, not really knowing what they did or why it works.

If you fall into that category, or just want to know a little better how sort works, stay tuned, we are going to make it simple.

Sorting algorithms?

Nope.

Great for computer science.  You should have a basic idea of how they work, but unless you are writing some low level bit twiddling code on an integrated circuit, you don’t need to know about them.

Let’s think of sorting algorithms as a black box.  You don’t need to know what the algorithm is or how it works, you just need to know that if you give the two things it requires it will sort your list for you.

What two things do all sorting algorithms, regardless of implementation need?

1. A list of things to sort
2. A method to call to tell if object A comes before or after object B, or whether they are the same.

That is all you need to know and give to a sorting algorithm implementation and it will do the rest.

Every modern programming language has at least one sorting algorithm and every single one of them has the exact two same inputs I mentioned above, a list to sort, and a comparison method.

It doesn’t matter if you are using C#, Java, Ruby or some other language, they all implement a sorting algorithm and need those two things.  And that is all they need from you.

The burden is off your shoulders.

Step 1: Find the sorting method

I’m going to do better than teach you how to sort in each language.  I’m going to show you how to figure out how to sort in a language.

The first step in doing that regardless of the language, is to find the method that sorts things.

A good place to look is the list or collection object itself, since that is the most obvious place to put a sort routine.

When we look up List in C#, sure enough we find Sort on there.

Oh noes!  So confusing!  It has 3 sort methods!  Which one do I call?  Agh!

Don’t panic.  Remember what I said above.  Even though you see three signatures for the sort method, sort methods still only need two things.

Sort(), Sort(Comparison<T>), and Sort(IComparer<T>) still need just a list and a method to compare two of your objects.

We’ll dive into that more in a bit, now let’s look at Java.

If we look up ArrayList in Java, we don’t find a sort method.  Boo.  What were they thinking.  It’s ok though, googling for “Java sort” turns up Arrays.sort and Collections.sort.

Let’s look at Collections.sort.

This time we see two sort methods, sort(List list), and sort(List list, Comparator c).

Again, nothing to be afraid of since we know the two things all sorting algorithms require from us.

Step 2: Find the two things

So if every sorting method needs the same two things from you, then all you need to do is figure out how to give it those two things.

In the C# and Java instances above, the first thing (the list of things to sort) is fairly obvious.  In C# we saw that the sort method was on the list class itself, so we don’t even need to pass it the list of things to sort, it still needs it, but it knows where to find it.

In the Java instance the first parameter to both sort methods is a list.

See how easy we just made things?  We are already 50% there.

So really the only question left is how to provide the method that compares two of our objects.

When we know what we are looking for, it is much easier to find and understand.

Let’s break down each instance and figure this out.

If we look at C#’s Sort() method, without reading the documentation, we can probably guess two things.

1. The list to sort is the list we are calling the sort method on.
2. The objects in the list provide the comparing method.

The first is obvious.  The second one is a little less obvious, but if you think about it, since the method takes no parameters the only possible thing that could be providing the method for comparison is the objects in the list.

If we look at the documentation for Sort(), we find that is true.  The objects in the list have to implement IComparable.  IComparable has one method, CompareTo, which takes one object and compares it to the other.  If you implement this interface on your object, you can sort a list of them.  Simple.

For Sort(Comparison<T>), we can easily deduce that what is passed in there must be the method to compare two objects, and sure enough it is.  If we want to use this method we just pass in a method of type Comparison<T> where T is the type of object we want to compare.

We can see that Comparison<T> is just a method that takes two of your objects and returns an int to indicate which is greater or if they are equal (1 = greater, 0 = equal, –1 less).

The final C# Sort(IComparer<T>) just takes an object that implements IComparer<T>.  Sure enough, IComparer<T> has one method that must be implemented, Compare.  That method has the same signature as Comparison<T> from above.

Now, let’s look at Java.  You’re going to find it is pretty much the same thing.

For sort(List list), we can easily see that the list to sort is passed in as a parameter, but once again we have to find where we supply the method to compare two of our objects.

Since it can’t be passed in, it must be… say it with me… on the object.  That is right!

Turns out we just have to have our objects implement Comparable and then they can be sorted.  When we look at the Comparable interface, we see that it just has one method, CompareTo(Object o) and that method just takes another object to compare our object to and returns 1 if ours is greater, 0 if it is the same, or –1 if ours is smaller.

Now let’s look at sort(List list, Comparator c).  In this case, we can see that the method to compare our two objects is passed in, but since we can’t pass methods in Java, Comparator is just an interface that we can implement that provides the comparison method.

If we look at the Comparator interface, we see it has one method we need to implement compare(Object o1, Object o2).  I’m sure you can guess what that method should return by now.

So regardless of the language, when you are looking at how to use a sorting algorithm, find the two things that it needs.  The list is usually obvious, but the method to compare is almost always implemented in one of three ways.

1. An interface the objects being compared implement.
2. A method that is passed in.
3. An object that is passed in that implements a comparison interface.

Step 3: Implement the method

After you have figured out how to pass your list and your comparison method to the sorting algorithm, you need to actually write the comparison method.

If you learn to write a comparison method you can use it for any sorting algorithm, since all comparison methods do the exact same thing.

Fortunately, this is easy as well, because comparison methods always do the exact same thing.  They take two objects and return whether the first one is larger, smaller, or equal to the second.  That is it.

Don’t worry about sorting.  Remember what I told you about the sorting algorithm black box?  Let that sorting algorithm worry about sorting, all you have to do is decide whether 1 given item comes before a 2nd given item or if they are they same, nothing more.

Can you do that?

Sort people on age? 

If person1.Age > person2.Age return 1

Else if person1.Age < person2.Age return –1

Else return 0

Psuedo-code, but pretty simple.

Wrapping it up

If you can figure out what method you can use to sort in your language, find how to pass in the list of things to sort and provide the comparison method, and implement the comparison method, then you can sort!

Just remember to not get overwhelmed and think logically about the two things that all sorting methods need from you, and you’ll see how simple the whole sorting thing really is. 

You can be the guy that everyone asks about sorting instead of the guy copying and pasting some sorting code from the internet that you aren’t really sure how it works.

By the way, in C#, I would recommend just using the LINQ extension method OrderBy.

Very nice to do something like:

people.OrderBy(p => p.Age).OrderBy(p => p.Name);

As always, you can subscribe to this RSS feed to follow my posts on Making the Complex Simple.  Feel free to check out ElegantCode.com where I post about the topic of writing elegant code about once a week.  Also, you can follow me on twitter here.