Test REST API with unREST – part 1

Motivation for this post is the recent project I’ve been working on. Project was about developing REST backend, and important segment of the work was testing the API. Fortunately, a lot of nice testing tools (such as Postman) have appeared in recent times, but working with them, it always felt like something is missing. To be exact, I felt that level of  automation was not high when working with these test tools. I always had a feeling that I’m repeating construction of requests each time, and wasting a lot of valuable time doing it.

So, my solution was to hack together something that would enable me to automate my testing cycle and speed up development. Ultimately, this failed :-), because I ended up working more on the test client then on the original project. It wase exactly like that XKCD comic :-).

But it turned out to be a nice lesson on Node.js development and JavaScript in general.Finally, I decided to package what I had into a Node module and put it on Github. Hopefully, someone might find it useful. In this post, I will describe some cool stuff  unREST can do.

What is it?

unREST is a command line tool to test REST APIs. Main goal of this tool is to automate repetitive tasks as much as possible. The way this is achieved is that developer creates a configuration file with a set of test cases that can be run as simple CLI commands. It is also possible to automate tasks like extracting, reviewing and saving data, creating templates and so on.

In this post, I will showcase some use cases for unREST.


To install the package globally, run simple NPM installation command:

To verify that installation is successful, simply run unrest  command. You should get an output like this:

Do not be alarmed by error messages. Unrest simply expects some configuration files in current directory. These files contain basic configuration options and tests cases for REST endpoint.

Simple test setup

In this section, we will set up simple test cases. We will use JSON REST API from JSON Placeholder as our endpoints for testing.

We will first create a directory for our sample test project:

Now we will create two configuration files, unrest.config.json  and tests.json . These are default names of the files unREST expects to find in current directory. You can also use different names and specify them with -d  and -t  options respectively (run unrest --help  to see startup options).

We will first create  unrest.config.json  with the following content:

This file contains settings which will be applicable for each request. Entry host defines the root URL of each request. In individual tests, we specify endpoints relative to this URL.

The other setting is for the HTTP client, and specifies that we allow self-signed SSL certificates. For more options related to HTTP client configuration, please see node-rest-client, which is a dependency for unREST.

Next, we will create our fist simple test case. We will retrieve list of posts from our dummy server. Create file named tests.json  with the following content:

Here, we define a test case called postList , and set /posts  as the test endpoint. Now, you can run unREST and try the test. You execute the test by running the following command:

This command will execute HTTP GET request with the parameters specified in test case. These parameters include endpoint, HTTP headers and anything else that might be required for the request.

unREST contains similar commands for most HTTP methods. You can see the list of available command any time by typing help  in the console. You can also see help for specific commands by specifying --help  option:

Specifying request parameters

It is possible to create parametrized test cases. For example, to retrieve specific post, we can create the following test case:

Here, we specify path parameter with name postId. Now we can run the test case by specifying the ID of the post we want to retrieve:

This will retrieve post with ID 2. It is also possible to specify query parameters this way. For example, we might create test case with endpoint /something?q=${param} , and specify it’s value the same way.

Formatting the output

So far, output of these commands is in JSON format. We can pretty-print this output using -f  option:

You get nicely formatted output. Notice that response headers are printed first, and then response body.

Overriding defaults

Configuration of test cases overrides defaults specified in unrest.config.json . For example, let’s say we want each of our requests to accept same content type. We can do something like this:

This will cause each HTTP request to contain specified header. Now, if we want to accept another content type in one of our test cases, we can easily set it in test case definition:

This setting will cause this particular test case to request XML as response type.

End of part one

This is it for now. In the next part, I will show you some more interesting stuff you can do with unREST. In the meantime, you can find sample code on Github.

Part 2 of the series


Leave a Reply

Your email address will not be published. Required fields are marked *