CI for APIs with the Kong Insomnia CLI

Insomnia is a desktop app from Kong that is great for building, debugging, and testing back-end APIs. While custom manual testing is fine, wouldn’t it be better to include our API tests in continuous integration (CI) pipelines? With Inso, Kong Insomnia’s CLI tool, we can!

Inso allows you to run automated API tests directly from the command line, which means setting up a workflow with GitHub Actions is a snap.

In this article, we will create a simple server using Node.js and Express, write API tests using Kong Insomnia, and then run these tests in our CI pipeline using Inso and GitHub Actions.

Demo app: Nintendo Games Database

We’ve built a game database with information about every NES game ever published. The application is a server that implements a REST API with endpoints to get data about games, categories, developers, publishers, and years of release.

You can find the full code on github.

Use thinner Kong for manual testing

During API development, quick feedback cycles help ensure that the API works the way you want it to and returns the data you expect. Kong Insomnia is ideal for this type of custom exam.

To get started with our NES game API, we’ve created a new design document inside Kong Insomnia. We left the information on the Design tab blank and headed to the Correction tab to start placing orders. Below, we have requests for each API endpoint that our server provides. We can run each order inside Kong Insomnia, and the resulting data is displayed in the user interface.

Example of an API request in Insomnia

Writing tests with Kong Insomnia

Accessing our API endpoints manually is great for custom testing and debugging, but in the end what we want is an automated test suite that ensures our app is working properly. Kong Insomnia allows you to write tests in the Test tab within the desktop application.

Tests are written by selecting a request from the Debug tab and then making assertions about the data returned by the server. You can take individual tests or a full set of tests.

As you can see below, we have written tests for each of our API endpoints for a total of 11 tests in our test suite.

API tests in insomnia

These tests (and the information in our design document) can be synced to Git and included in our repo. This way, anyone with the Kong Insomnia desktop app can run these requests and tests.

To sync Kong Insomnia with Git, simply click the “Setup Git Sync” button at the top of the app.

Setting the Git Sync button in Insomnia

From there, you can provide the relevant details for linking Kong Insomnia with your project’s Git repo.

Connect insomnia to the GitHub repo

Syncing Kong Insomnia with Git repo requires an authentication token. You can easily create a personal access token within your GitHub account settings.

Create a personal access token in GitHub

Run tests from the command line with Inso

We now have a set of requests and a set of tests inside Kong Insomnia that help us with debugging and testing. But we haven’t run these tests automatically yet, so let’s do that for now. This is where you play CLI, Inso from Kong Insomnia.

Inso can be installed as an npm package, so we added that as a dev dependency for our project: yarn add --dev insomnia-inso.

To make running our test suite simple, we created an npm script in a file package.json a file. The following script does our tests with Inso: "test": "inso run test "NES Games API Test Suite"". This means we can simply run yarn test To run our tests from the command line anytime we want.

Inso integration with GitHub routines

Now is the culmination of everything we’ve built so far: running our automated tests as part of a continuous integration pipeline. It’s nice that we can run our tests from the command line, but at the moment, they don’t run automatically for us anywhere. We really want to run our test suite on every new pull request. Doing so will ensure that the tests pass before any new code is merged into the master branch. This is continuous integration at its best.

GitHub actions allow us to configure any persistent integration we wish using YAML files. We have created a file .github/workflows guide and unit-tests.yml file inside. This file is copied in full below:

name: NES Games API CI

      - master
      - master

    runs-on: ubuntu-latest
      - name: Checkout branch
        uses: actions/checkout@v2

      - name: Use Node.js 14.x
        uses: actions/setup-node@v2
          node-version: 14.x
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Start server and run unit tests
        run: yarn ci:start-and-test

As you can see, our workflow checks our current branch, uses Node v14, installs our dependencies with spinning, and then runs a custom script to start our application server and run API tests. This workflow is triggered when a token is pushed to the master branch or a new pull request is opened against the master branch.

this is ci:start-and-test script is another npm script we added to package.json a file. With npm packages on hold and at the same time we use this script to start our server, run API tests, and then terminate the server once the tests are over. The complete list of npm scripts in a file package.json The file is reproduced below:

"scripts": {
  "ci:start-and-test": "concurrently -k -s=first "yarn start" "yarn ci:test"",
  "ci:test": "wait-on http://localhost:3000 && yarn test",
  "format": "prettier --write .",
  "format-watch": "onchange . -- prettier --write {{changed}}",
  "start": "node index.js",
  "test": "inso run test "NES Games API Test Suite""

And now, we have a beautifully working CI pipeline!

We can test that everything is working correctly by creating a small pull request in our repo. After making the pull request, we can see that our CI pipeline is running:

The CI Pull Request Pipeline is running in GitHub

If we click on the details button to see more information, we can see the individual steps of the workflow in action:

CI أنابيب Pipeline Steps

Once the job passes, the results are reported back to the pull request as shown below:

The CI pipeline for our pull request has passed

We did it! All checks have been passed.

The last thing we can do for completeness is to require that all GitHub checks go through before pull requests can be combined. We can do this in the repo settings inside GitHub:

Request to pass state checks before merging pull requests into GitHub

If you want to explore another potential CI setup, the Kong team also has an example of their workflow, you can use the Inso install as part of a job in a CI pipeline with their GitHub Action setup.


So, what have we accomplished today? Too many, actually! We have built a server using Node.js and Express. We have created custom requests within Kong Insomnia to help develop and debug our API. We wrote tests inside Kong Insomnia and learned to run them from the command line using Inso. Finally, we built a CI pipeline with GitHub routines to run our API tests as part of every pull request for our repo.

Kong Insomnia, Inso and GitHub Actions have worked together to help us develop our app with confidence. We’ve prepared our Continuous Integration pipeline to deploy our app at any time. Success!

Going forward, we can integrate this workflow into a broader strategy to manage the entire API development lifecycle – design and development within Kong Insomnia, deployment with Inso integrated with the CI pipeline, and management and maintenance using a tool like Kong Gateway.

Thanks for reading, and happy coding!


Leave a Comment