The Issue

Ensuring that your API calls are working is key to having a functional application. As we covered with our post on best practices for API testing,  automation is essential to ensure proper testing coverage. Lest take a look at one way we can automate a basic API request using Ruby – and then validate that we are seeing what we want to see.

For our example, we’ll use The Movie Database (TMDB). We’ll see how we can run a POST function by creating a list within our user settings, and then asserting that we receive the correct response code.

The Code

First, lets take a look at the front end. The TMDB user page has a list section:

TMDB Lists

TMDB Lists


Step 1: Setting Up your Ruby Environment.

We want to run a POST command that will create a list. This is a simple enough endeavor – we’ll just need to make sure we are passing through our correct JSON headers and body. First, we will call our rest-client gem by using the below code:

This will be followed by including our values like URL, body, etc. using RestClient.get/post/delete. See formatting below:


Step 2: Adding JSON Parameters & Building the Ruby Script

In our case, we want to include our URL, request body, and headers. We will grab our URL for creating lists and the body format, and insert it (taken from our API documentation for TMDB). We will then include the headers, which span both the content_type and our authorization. For your authorization, follow the steps here to generate a bearer token, which will be included in this header. Once we have all of these, we will place them per the below code:

Now that we have our JSON request ready, we can incorporate it into our entire Ruby file, and also include commands to display specific output. In this case, we will choose to display the output body, the headers and the response code:

We will put these all into a Ruby file, and save it as TMDBTest.rb.


Step 3: Executing Your Script, HTTP Request

Then, we can actually run the file, using ruby TMDBTest.rb. For our response, we will be returned the following:

Screen Shot 2018-03-09 at 2.40.59 PM

Response from running our TMDBTest.rb

So, we now have our foundation –  a functioning API POST request that we can run from Ruby. However, we will need to add a few things before we can actually utilize this in a test case. First, we want to make sure the test is reusable – if we dont change our list name, we will not be able to create another list due to the name duplication. So, we can solve this by ensuring we are generating a new random name each time. In order to do this, we will build out a function that will generate a random string of alpha characters. See the below code

This gives us a function to work with: result. When we call result now, it will generate a string of 10 random alpha characters. So, now we need to figure how to incorporate result into our JSON request. There are two ways we can do this. The first will directly incorporate it as a string into our JSON request. We will first define request as a variable. In it, we include the area where we are calling result between our single quotes and plus signs – this converts it into a string that will be utilized by our JSON request. See below

So, when we run this, we will actually be doing the equivalent of the below code, with RANDOMNAME being any random selection of 10 Alpha characters


As for inputting this into our JSON request, we can include the our defined request into the body, like so:


Now, if we combine all of these and put them back into our main file, we will see something like this:

We will put our result variable in a string (see above code) which will allow you insert in the JSON request. Thus, we can utilize our function that we have constructed to generate a random string of characters which will act as our list name in this case.

Altanetively, we can use the .gsub command to replace our given placeholder with whatever we choose. See below

We defined request a bit differently, and include “NAME” where we want our name to be generated. We then include an additional line with our .gsub command, which will replace any given instance of NAME with our desired random string.

Step 4: Assertion

Now, let’s delve into two areas: the assertion, and actual incorporation into a frontend UI test. To validate that we receive the correct response code, we will add some Ruby logic into our file. First we will initialize results to an empty hash – see below

This empty hash will allow us to assign a key/value pair of our choosing. The key is going be our validation, and the value will be the result. We will use the following logic:

In this example, [“Response Code should be 201”] = acts as our validation, and the response.code == 201 acts as our value.

In display our results (and raise an exception on failure), we will add a puts command to print the contents of our variable:

We can then add a step to fail the test if any of the validations in our results variable have failed:

So, when we run the test we will now see a command line output like so:

Screen Shot 2018-03-14 at 2.54.40 PM

If the test failed, we would see a message like so:

Screen Shot 2018-03-14 at 2.57.11 PM

Lets take a look at what the entire script will now look like:


We now have a functioning Ruby script that will send an API request, display our responses and assert  we are seeing the correct response code. You can continue to assert different parts of your responses – such as a specific value in the response body, or a a certain response in the headers. A benefit of testing your API calls through a Ruby script in this way is the versatility of incorporating front end testing (through Watir Webdriver commands) in the same script (which we will be breaking down in a future post).