When you open the browser and hit ‘google.com’ in the address bar, it sends dozens of HTTP requests and gets responses from the servers. To send those requests you actually don’t have to open a browser.
You may use command-line cURL and send a request from the terminal. cURL’s disadvantage is the difficulty to switch between requests and sharing the responses with your teammates.
What about building UI on top of cURL? The most popular tool to deal with API requests is Postman. It’s quite powerful and has many great features. But very often you don’t want a bulky machine gun when a screwdriver is enough. I personally prefer Insomnia, cause it’s much easier and basically does the same thing. It’s handy when it comes to exploratory testing, or when you want to share the requests with developers.
To show my favorite Insomnia features I’ll use a real web application called Conduit. Conduit is a simplistic clone of Medium. Conduit is implemented in many popular languages and frameworks. I will use Spring Boot backend and React frontend to demonstrate how it works. Let’s spin the testing environment on the local machine.
Requirements
Please, install the following tools:
Setup testing environment
First, deploy the back-end service.
-
Open terminal and clone Github repo:
git clone https://github.com/drakulavich/spring-boot-realworld-example-app.git -
Run docker-compose to deploy the app on http://localhost:8080/
cd spring-boot-realworld-example-app docker-compose up -dTo check that deployment went smoothly open the page http://localhost:8080/tags
Second, deploy a container with the front-end.
-
git clone https://github.com/drakulavich/react-redux-realworld-example-app.git -
Run docker-compose to deploy the front-end on http://localhost:4100/
docker-compose up -d -
In Insomnia the organized collection of the requests is called Workspace. To import Conduit Workspace follow the steps:
- Open Insomnia
- Open Preferences → Data
- Click Import Data → From URL
- Paste the following URL https://raw.githubusercontent.com/drakulavich/spring-boot-realworld-example-app/workshop/Insomnia_conduit_workspace.json
Environment variables
At that time you should have up and running services for Conduit blog platform. The app is empty: no users, no posts, nothing. To be able to test it we have to prepare test data. The first step is to register the user in the system. We will use Environments to store all necessary information. The environment in Insomnia allows you to add a JSON document, that can be referenced to access fields as environment variables.
Base Environment can have default values and Sub Envs will override them. Usually, I add to sub envs user details and test stand URL. To make names consistent you may choose patterns like {env_name} with {user_name}.
Now we can use variables inside requests. For example, Auth → Register request:
To reference the field from Environment, start typing _ (underscore symbol) and choose a variable from the context menu.
The user is created. The next step would be sending a Login request to obtain the valid auth token. The token will be used for all the other requests under the user’s name.
Requests Chaining
It’s not sufficient to copy/paste the token for each request, that’s why Insomnia has Requests Chaining. Switch to Auth → Current User request and open Auth tab. Select Bearer Token authentication and start typing response word in the Token field. Insomnia will show you a popup menu. All we are interested in is the Response → Body Attribute. Click on the tag to specify details.
We need to specify the Request and filter out the value using JSONPath. If you see the correct value in Live Preview, it means everything is ready. All you have to do later is copy the tag and paste it into every request that requires the token. We touched only two Insomnia features: Environments and Requests Chaining. And look how powerful they are! You can improve your productivity even further by using hotkeys.
Insomnia Plugins
OK. We can log in to the app, but it’s still empty. Let’s create some posts. The blog post must have a title, short description, text, and tags. If you try to create testing data manually, it will take a lot of time. How to cut the corner and simplify the process? Insomnia supports plugins, so we may use a random generator called faker.
After installing, you will find new suggestions from Insomnia when you start typing faker word. After that Create Article request will produce a randomly generated body each time you click Send button. Cool! We can easily add several posts under different user names. It will be enough to test multiple use cases such as:
- Follow profile;
- Favorite a post;
- Comment a post;
- Use tags to navigate between posts.
Requests History
What if you found a bug with random data and you want to reproduce it again? In the upper right corner, click on Requests History. You will find the list of previous requests. If you switch to any request from the past, you can open the Timeline tab and check the exact body that was sent. Nice!
Copy as cURL to export and import requests
How to share the request with a developer? The easiest way is to open the context menu for the request and choose Copy as Curl. If you attach the request to the bug report, the developer will be grateful.
So, we have created users and added several blog posts. It’s time to explore the web app (http://localhost:4100/). Imagine the situation when you are working with the web app, and you want to debug the request that the browser just sent. Open Developer Tools, switch to the Network tab, and select the request. Chrome allows copying the request as cURL, the same way we did in Insomnia.
Open Insomnia, create a new dummy request without any data. Then, insert the cURL from Chrome to the address bar. Insomnia will parse the request and show it with the body, headers, etc. I usually prefer to debug API in Insomnia, and this is how you can import the request from the Browser.
Filter the response body
The last thing I’d like to demonstrate is response filtering with JSONPath. Let’s execute request Articles → All Articles. The response is quite heavy to read. Imagine we are interested only in one field from the collection of the articles. Use JSONPath to filter the output. For example, get only the favoritesCount field:
Summary
To recap, what we have learned so far:
- Environment variables
- Requests Chaining
- Insomnia Plugins
- Requests History
- Copy as cURL
- JSONPath for filtering the data in the response body
Thanks for reading! I suggest to try everything we covered by yourself, and I hope you will enjoy debugging and testing APIs in Insomnia as much as I do.
Also published here.