RESTful API testing in C# with RestSharp

Since my last blog post that involved creating tests at the API level in C#, I’ve kept looking around for a library that would fit all my needs in that area. So far, I still haven’t found anything more suitable than RestSharp. Also, I’ve found out that RestSharp is more versatile than I initially thought it was, and that’s the reason I thought it would be a good idea to dedicate a blog post specifically to this tool.

The examples I show you in this blog post use the Zippopotam.us API, a publicly accessible API that resolves a combination of a country code and a zip code to related location data. For example, when you send an HTTP GET call to

http://api.zippopotam.us/us/90210

(where ‘us’ is a path parameter representing a country code, and ‘90210’ is a path parameter representing a zip code), you’ll receive this JSON document as a response:

{
	post code: "90210",
	country: "United States",
	country abbreviation: "US",
	places: [
		{
			place name: "Beverly Hills",
			longitude: "-118.4065",
			state: "California",
			state abbreviation: "CA",
			latitude: "34.0901"
		}
	]
}

Some really basic checks
RestSharp is available as a NuGet package, which makes it really easy to add to your C# project. So, what does an API test written using RestSharp look like? Let’s say that I want to check whether the previously mentioned HTTP GET call to http://api.zippopotam.us/us/90210 returns an HTTP status code 200 OK, this is what that looks like:

[Test]
public void StatusCodeTest()
{
    // arrange
    RestClient client = new RestClient("http://api.zippopotam.us");
    RestRequest request = new RestRequest("nl/3825", Method.GET);

    // act
    IRestResponse response = client.Execute(request);

    // assert
    Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
}

If I wanted to check that the content type specified in the API response header is equal to “application/json”, I could do that like this:

[Test]
public void ContentTypeTest()
{
    // arrange
    RestClient client = new RestClient("http://api.zippopotam.us");
    RestRequest request = new RestRequest("nl/3825", Method.GET);

    // act
    IRestResponse response = client.Execute(request);

    // assert
    Assert.That(response.ContentType, Is.EqualTo("application/json"));
}

Creating data driven tests
As you can see, creating these basic checks is quite straightforward with RestSharp. Since APIs are all about sending and receiving data, it would be good to be able to make these tests data driven. NUnit supports data driven testing through the TestCase attribute, and using that together with passing the parameters to the test method is really all that it takes to create a data driven test:

[TestCase("nl", "3825", HttpStatusCode.OK, TestName = "Check status code for NL zip code 7411")]
[TestCase("lv", "1050", HttpStatusCode.NotFound, TestName = "Check status code for LV zip code 1050")]
public void StatusCodeTest(string countryCode, string zipCode, HttpStatusCode expectedHttpStatusCode)
{
    // arrange
    RestClient client = new RestClient("http://api.zippopotam.us");
    RestRequest request = new RestRequest($"{countryCode}/{zipCode}", Method.GET);

    // act
    IRestResponse response = client.Execute(request);

    // assert
    Assert.That(response.StatusCode, Is.EqualTo(expectedHttpStatusCode));
}

When you run the test method above, you’ll see that it will run two tests: one that checks that the NL zip code 3825 returns HTTP 200 OK, and one that checks that the Latvian zip code 1050 returns HTTP 404 Not Found (Latvian zip codes are not yet available in the Zippopotam.us API). In case you ever wanted to add a third test case, all you need to do is add another TestCase attribute with the required parameters and you’re set.

Working with response bodies
So far, we’ve only written assertions on the HTTP status code and the content type header value for the response. But what if we wanted to perform assertions on the contents of the response body?

Technically, we could parse the JSON response and navigate through the response document tree directly, but that would result in hard to read and hard to maintain code (see for an example this post again, where I convert a specific part of the response to a JArray after navigating to it and then do a count on the number of elements in it. Since you’re working with dynamic objects, you also don’t have the added luxury of autocomplete, because there’s no way your IDE knows the structure of the JSON document you expect in a test.

Instead, I highly prefer deserializing JSON responses to actual objects, or POCOs (Plain Old C# Objects) in this case. The JSON response you’ve seen earlier in this blog post can be represented by the following LocationResponse class:

public class LocationResponse
{
    [JsonProperty("post code")]
    public string PostCode { get; set; }
    [JsonProperty("country")]
    public string Country { get; set; }
    [JsonProperty("country abbreviation")]
    public string CountryAbbreviation { get; set; }
    [JsonProperty("places")]
    public List<Place> Places { get; set; }
}

and the Place class inside looks like this:

public class Place
{
    [JsonProperty("place name")]
    public string PlaceName { get; set; }
    [JsonProperty("longitude")]
    public string Longitude { get; set; }
    [JsonProperty("state")]
    public string State { get; set; }
    [JsonProperty("state abbreviation")]
    public string StateAbbreviation { get; set; }
    [JsonProperty("latitude")]
    public string Latitude { get; set; }
}

Using the JsonProperty attribute allows me to map POCO fields to JSON document elements without names having to match exactly, which in this case is especially useful since some of the element names contain spaces, which are impossible to use in POCO field names.

Now that we have modeled our API response as a C# class, we can convert an actual response to an instance of that class using the deserializer that’s built into RestSharp. After doing so, we can refer to the contents of the response by accessing the fields of the object, which makes for far easier test creation and maintenance:

[Test]
public void CountryAbbreviationSerializationTest()
{
    // arrange
    RestClient client = new RestClient("http://api.zippopotam.us");
    RestRequest request = new RestRequest("us/90210", Method.GET);

    // act
    IRestResponse response = client.Execute(request);

    LocationResponse locationResponse =
        new JsonDeserializer().
        Deserialize<LocationResponse>(response);

    // assert
    Assert.That(locationResponse.CountryAbbreviation, Is.EqualTo("US"));
}

[Test]
public void StateSerializationTest()
{
    // arrange
    RestClient client = new RestClient("http://api.zippopotam.us");
    RestRequest request = new RestRequest("us/12345", Method.GET);

    // act
    IRestResponse response = client.Execute(request);
    LocationResponse locationResponse =
        new JsonDeserializer().
        Deserialize<LocationResponse>(response);

    // assert
    Assert.That(locationResponse.Places[0].State, Is.EqualTo("New York"));
}

So, it looks like I’ll be sticking with RestSharp for a while when it comes to my basic C# API testing needs. That is, until I’ve found a better alternative.

All the code that I’ve included in this blog post is available on my Github page. Feel free to clone this project and run it on your own machine to see if RestSharp fits your API testing needs, too.

On supporting Continuous Testing with FITR test automation (republished)

Note: this is an updated version of an earlier post I wrote in May of last year. Since then, my understanding of Continuous Testing and what it takes for automation to be a successful and valuable part of any Continuous Testing effort have changed slightly, so I thought it would be a good idea to review and republish that post.

Test automation is everywhere, nowadays. That’s probably nothing new to you.

A lot of organizations are adopting Continuous Integration and Continuous Delivery as a means of being able to develop and deliver software in ever shorter increments. Also nothing new.

To be able to effectively implement CI/CD, a lot of organizations are relying on their automated tests to help safeguard quality thresholds while increasing release speed. Again, no breaking news here.

However, automation in and by itself isn’t enough to safeguard quality in CI and CD. You’ll need to be able to do Continuous Testing (CT). Here’s how I define Continuous Testing, a definition greatly influenced by others that have been talking and writing about CT for a while:

Continuous Testing is the process that allows you to get valuable insights into the business risks associated with delivering application increments following a CI/CD approach. No matter if you’re building and deploying once a month or once a minute, CT allows you to formulate an answer to the question ‘are we happy with the level of value that this increment provides to our business / stakeholders / end users? ‘ for every increment that’s being pushed and deployed in a CI/CD approach.

It won’t come as a surprise to you that automated tests often form a significant part of an organization’s CT strategy. However, just having automated tests is not enough to be able to support CT. Apart from the fact that automation can only do so much (a topic I’ve discussed in several other blogs and articles), not every bit of automation is equally suitable to be used in a CT strategy. But how do you decide whether or not your automation can be used as part of your CT efforts? And when they can’t, what do you need to take care of to improve them?

In order to be able to leverage your automated tests successfully for supporting CT, I’ve come up with a model based on four pillars that need to be in place for all automated checks before they can become part of your CT process:

From AT to CT with FITR tests

Let’s take a quick look at each of these FITR pillars and how they are necessary when including your automation into CT.

Focused
Automated tests need to be focused to effectively support CT. ‘Focused’ has two dimensions here.

First of all, your tests should be targeted at the right application component and/or layer. It does not make sense to use a user interface-driven test to test application logic that’s exposed through an API (and subsequently presented through the user interface), for example. Similarly, it does not make sense to write API-level tests that validate the inner workings of a calculation algorithm if unit tests can provide the same level of coverage.

The second aspect of focused automated tests is that your tests should test what they can do effectively. This boils down to sticking to what your test solution and tools in it do best, and leaving the rest either to other tools or to testers, depending on what’s there to be tested. Don’t try and force your tool to do things it isn’t supposed to (here’s an example).

If your tests are unfocused, they are far more likely to be slow to run, to have high maintenance costs and to provide inaccurate or shallow feedback on application quality.

Informative
Touching upon shallow or inaccurate feedback, automated tests also need to be informative to effectively support CT. ‘Informative’ also has two separate dimensions.

Most importantly, the results produced and the feedback provided by your automated tests should allow you, or the system that’s doing the interpretation for you (such as an automated build tool), make important decisions based on that feedback. Make sure that the test results and reporting provided contain clear results, information and error messages, targeted towards the intended audience and addressing business-related risks. Keep in mind that every audience has its own requirements when it comes to this information. Developers likely want to see stack traces, whereas managers don’t. Find out what the target audience for your reporting and test results is, what their requirements are, and then cater to them as best as you can. This might mean creating more that one report (or source of information in general) for a single test run. That’s OK.

Another important aspect of informative automated tests is that it should be clear what they do (and what they don’t do), and what business risk they address. You can make your tests themselves be more informative through various means, including (but not limited to) using naming conventions, using a BDD tool such as Cucumber or SpecFlow to create living documentation for your tests, and following good programming practices to make your code better readable and maintainable.

When automated test solutions and the results they produce are not informative, valuable time is wasted analyzing shallow feedback, or gathering missing information, which evidently breaks the ‘continuous’ part of CT.

Trustworthy
When you’re relying on your automated tests to make important decisions in your CT activities, you’d better make sure they’re trustworthy. As I described in more detail in previous posts, automated tests that cannot be trusted are essentially worthless. Make sure to eliminate false positives (tests that report a failure when they shouldn’t), but also false negatives (tests that report no failure when they should).

Repeatable
The essential idea behind CT (referring to the definition I gave at the beginning of this blog post) is that you’re able to give insight into application quality and business risks on demand, which means you should be able to run your automation on demand. Especially when you’re including API-level and end-to-end tests, this is often not as easy as it sounds.

There are two main factors that can hinder the repeatability of your tests:

  • Test data. This is in my opinion one of the hardest ones to get right, especially when talking end-to-end tests. Lots of applications I see and work with have complex data models or share test data with other systems. And if you’re especially lucky, you’ll get both. A solid test data strategy should be put in place to do CT, meaning that you’ll either have to create fresh test data at the start of every test run or have the ability to restore test data before every test run. Unfortunately, both options can be quite time consuming (if at all attainable and manageable), drawing you further away from the ‘C’ in CT instead of bringing you closer to it.
  • Test environments. If your application communicates with other components, applications or systems (and pretty much all of them do nowadays), you’ll need suitable test environments for each of these dependencies. This is also easier said than done. One possible way to deal with this is by using a form of simulation, such as mocking or service virtualization. Mocks or virtual assets are under your full control, allowing you to speed up your testing efforts, or even enable them in the first place. Use simulation carefully, though, since it’s yet another moving part of your CT solution to be managed and maintained, and make sure to test against the real thing periodically for optimal results.

Having the above four pillars in place does not guarantee that you’ll be able to perform your testing as continuously as your CI/CD process requires, but it will likely give it a solid push in the right direction.

On delivering automation training online

Recently (as in, over the last year and a half or so) I regularly receive questions about providing online training in addition to my in-house, in-person training offerings. Until now, I put those requests on the back burner as I was of the opinion that teaching online (either live or through prerecorded video instructions) would never be a replacement for ‘live’ training.

And then something struck me: why would it have to be an exact replacement? Why not just try it, see how it goes, learn from it and see if it’s a suitable way to conduct training?

So, when I got in touch with a test consultancy firm in the UK that was looking for training for their employees, I decided to give it a try. After some discussion, we agreed that I would deliver the first day of training in house (meaning: in Manchester), while the following modules would be delivered online, saving me a couple of trips back and forth and cutting down on overhead costs for airfare and hotels. And so it was done.

Note: I am aware that having met the students in person before delivering training online to them is a big plus. However, I believe that the lessons and the pros and cons I talk about in this blog post equally apply when you’ve never met the students in real life just as well.

So, what did I learn in the process? Let’s see.

Preparation
I could write a whole separate article about how to properly prepare for a technical training course or workshop. In fact, I’ll be doing just that in the near future, in an article that will be published on another platform.

I won’t go into too many details here, but by far the most important thing to do when you’re about to conduct training online is to make sure that the participants are ready from the start. My preferred way of doing this is by sending detailed preparation instructions (a step-by-step guide, screenshots and all) to them at least a whole week in advance, so the participants have some time to set up their device. Additionally, I make myself available for questions and troubleshooting in case something goes wrong.

I was afraid to do this in the beginning, fearing I’d be overwhelmed with questions, but it turns out that’s not the case. For all the workshops I’ve given in the last few years, I’ve only had a couple (as in: three or four) people asking for help. That doesn’t mean that everybody else is ready to go when the workshop or training starts, but that’s a whole different kettle of fish…

The reason this is extra important when delivering training online is that you cannot just walk over to the participants and look over their shoulder to see what’s going wrong. You can do screen sharing, of course, but that’s not as efficient as taking over the controls for a bit.

So, long story short, overdo it on the preparation instructions. Be very clear in them and make sure they’re unambiguous. Have them tested by somebody else if you’re not sure everything’s clear (heck, do this even if you ARE sure).

Organization
With regards to how the training days should be organized, here are some key lessons I’ve learned from the two days of training I’ve hosted so far:

  • Group size: Where I can take around 12 people for a class that involves programming when they’re in the same room, I am glad I had only 4 participants for my online training. I think I can handle up to 6 people, but no more. Keeping track of how everybody is doing takes more effort when you see them through a webcam only, and there will probably be more questions (also because participants can’t help eachother out), so it’s only fair to limit the number of attendees to make sure everybody gets the attention and the answers they deserve.
  • Type of course: Live online training works well for hands-on automation training, but probably much less so (for obvious reasons) for training courses that involve a lot of group work, discussions and presentations. I wouldn’t even know how to facilitate that online…
  • Location and connection: Make sure the participants (and you yourself as well) are in a room with good lighting and that their webcam is on, because reading facial expressions will tell you a lot about their level of engagement. Also make sure they’re in a location with a good Internet connection. Videoconferencing takes bandwidth, yet you want both video and audio to be of the highest possible quality to make sure the participants can hear and see you well.

Engagement
The hardest part about delivering training online is keeping your audience engaged. Taking training is hard enough on your energy levels when you’re in the same room as the trainer, looking at a webcam and listening to somebody who’s potentially very far away is orders of magnitude harder. Here are some tips that might help you (they worked for me!):

  • Ask the participants how they’re doing often, to the point of being annoying. Don’t lose them, don’t give them a chance to start drifting off. Make sure they are awake and engaged. In the pre-course instructions, point out that they should be well rested, and that taking a training course online is even more demanding than ‘live’ training, for both parties.
  • Consider shortening the training days (for example, teach for 6 hours instead of 8 for a day of training). Chances are high that they won’t take in anything in those last two hours anyway, simply because their energy levels are too low. Additionally, take breaks often. Even just a five minute break for a leg stretch or a bathroom visit can help keep energy levels up. I took breaks every hour, which definitely wasn’t overdoing it.
  • Involve them. Instead of just broadcasting information all day, ask them lots of questions. When you’re doing programming exercises, ask them to share their screen and talk the rest of the audience through their solution and thinking process. Again, this helps keep them engaged. Don’t let them fall asleep!

Pros and cons
As I said earlier, online training isn’t a replacement for in-person training, at least not on a 1-on-1 basis. It’s a whole different ball game. Both have their pros and cons. Some of the benefits of delivering training online for me are:

  • It allows me to work from home. Big plus. I like driving my car, but I hate wasting time commuting. With online training, I can teach from the comfort of my own home.
  • My potential client base is many times larger. I am quite limited in the amount of travel I can do in a year, and the Netherlands is a small country, which means my client base isn’t all that large. With the possibilities of online training, though, I can deliver my courses to the entire world, potentially. Added bonus: meeting and talking to people from other countries and cultures, plus it does wonders for my English.

Sure, there are some downsides as well:

  • Not being able to walk up to people and see how they’re doing. I do this a lot when teaching in-person, but that’s not an option when online. Even with a webcam, people can hide behind their screen easier and pretend all is well. Their loss, of course, but I take pride in keeping everybody engaged.
  • It isn’t suited for every course I offer. I do more and more courses where people work in groups and have discussions, and as I said earlier, that’s not really an option when teaching online.

Having said all of this, I will definitely start offering live online training more often in the future, probably starting after the summer holidays. It’s definitely a valuable addition to the services I can offer. If you’re interested in taking one of my online courses, keep an eye out on this site for future announcements.

Oh, and in case you were wondering: so far I didn’t need any dedicated virtual classroom software to conduct the training. I used the pro version of appear.in, which requires no software to be installed at all on the client side, is a breeze to work with, allows everybody to share their screen effortlessly, has a chat to share links and stuff, basically everything I need.