Insomnia REST Client Tutorial: API Testing with Collections and Tests

Insomnia is one of the most polished open-source API clients available. Originally built as a lightweight Postman alternative focused on great UX, it was acquired by Kong in 2019 and has since evolved into a full-featured platform with REST, GraphQL, and gRPC support, an OpenAPI design editor, a powerful plugin system, and inso — a CLI that runs Insomnia test suites in CI pipelines.

This tutorial covers the complete Insomnia workflow: creating a project, writing requests, organizing collections, managing environments, writing response tests, using plugins, generating code snippets, and integrating with GitHub Actions via the inso CLI.

Installation

Insomnia ships as a native desktop app for macOS, Windows, and Linux.

macOS via Homebrew:

brew install --cask insomnia

Direct download: Get the latest installer from insomnia.rest/download. Insomnia also has a web-based version through its cloud platform.

inso CLI (separate from the desktop app, for CI use):

npm install -g insomnia-inso
# or
yarn global add insomnia-inso

Insomnia went through a controversial change in 2023 when Kong required login to use the desktop app. This was partially walked back — you can now use the local storage mode without an account, but cloud sync and team features require an account.

Projects and Collections

Insomnia organizes work into Projects, which contain Collections (for API requests) and Design Documents (for OpenAPI specs). When you open Insomnia, you land on the dashboard where you create or select a project.

Create a new collection by clicking New Collection inside a project. Name it something meaningful — User Service API or E-Commerce Backend.

Collection Structure

Organize requests into folders. A well-structured collection mirrors your API's resource hierarchy:

E-Commerce API
├── Auth
│   ├── POST /auth/login
│   ├── POST /auth/refresh
│   └── POST /auth/logout
├── Products
│   ├── GET /products
│   ├── GET /products/:id
│   ├── POST /products
│   └── DELETE /products/:id
└── Orders
    ├── GET /orders
    ├── POST /orders
    └── GET /orders/:id/items

Folders can be nested arbitrarily deep. Drag requests between folders to reorganize.

Creating Requests

Click the + button next to a folder to create a new request. Insomnia prompts you to choose the method and gives you a new request tab.

GET Request

Enter a URL, add any headers, and click Send:

GET https://api.example.com/users/123
Authorization: Bearer {{authToken}}
Accept: application/json

The response panel shows the status code, size, response time, and the response body with syntax highlighting and tree view for JSON.

POST Request with JSON Body

Set the method to POST. Select JSON as the body type. Insomnia provides a code editor for the JSON body with auto-formatting:

{
  "name": "Alice Chen",
  "email": "alice@example.com",
  "role": "editor",
  "metadata": {
    "source": "api",
    "campaign": "{{utmCampaign}}"
  }
}

Form Data and File Uploads

Switch the body type to Multipart Form for multipart/form-data requests. Add form fields and use the file picker to attach files for file upload endpoints. Insomnia handles the MIME boundary generation automatically.

Authentication

The Auth tab in each request offers:

• Bearer Token — inserts the Authorization: Bearer <token> header
• Basic Auth — username/password combination
• OAuth 1.0 — full OAuth 1.0a with request signing
• OAuth 2.0 — authorization code, client credentials, password, implicit flows; Insomnia launches the browser for the authorization code flow automatically
• AWS IAM — signs requests with AWS Signature v4
• Digest Auth — challenge-response digest authentication
• NTLM — for Windows-integrated auth against corporate APIs

You can also set auth at the folder level and have it inherited by all requests inside.

Environment Variables

Insomnia's environment system is one of its strongest features. There are three layers:

Base environment: Variables available in all environments. Good for constants like API version prefixes.

Sub-environments: Environment-specific overrides. Create separate sub-environments for Local, Staging, and Production:

Local environment:

{
  "baseUrl": "http://localhost:3000",
  "adminEmail": "admin@local.test",
  "debugMode": true
}

Staging environment:

{
  "baseUrl": "https://api-staging.example.com",
  "adminEmail": "admin@staging.example.com",
  "debugMode": false
}

Variables are referenced with {{ variableName }} in URLs, headers, and body text. Switch environments from the dropdown in the top-left of the collection view.

Private environments: Insomnia has a "private" environment type where secret values are stored in the device keychain rather than in the collection JSON. These values never sync to the cloud. Useful for API keys, tokens, and passwords that should not leave the local machine.

Template Tags — Dynamic Values

Beyond simple variables, Insomnia has "template tags" — dynamic value generators that you insert with Ctrl+Space in any input field:

• {% now 'iso8601' %} — current timestamp in ISO format
• {% uuid %} — random UUID v4
• {% response 'body', 'req_login', '$.data.token' %} — extract a JSONPath value from another request's response
• {% faker 'internet.email' %} — generate a random email using the Faker library

The response tag ({% response %}) is how you chain requests without scripting. Point it at your login request, give it the JSONPath to the token field, and Insomnia automatically fires the login request and extracts the token when it's needed.

Writing Response Tests

Every request in Insomnia has a Tests tab alongside the regular request configuration. Tests are JavaScript and run after the response arrives.

const response = insomnia.response;

// Status code assertion
insomnia.test('Status code is 200', () => {
  insomnia.expect(response.status).to.equal(200);
});

// Response body assertions
const body = JSON.parse(response.body);

insomnia.test('Response contains user id', () => {
  insomnia.expect(body).to.have.property('id');
  insomnia.expect(body.id).to.be.a('string');
});

insomnia.test('Email is valid format', () => {
  insomnia.expect(body.email).to.match(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
});

insomnia.test('Response time under 800ms', () => {
  insomnia.expect(response.responseTime).to.be.below(800);
});

// Array response assertions
insomnia.test('Returns at least one item', () => {
  const items = JSON.parse(response.body);
  insomnia.expect(items).to.be.an('array');
  insomnia.expect(items.length).to.be.greaterThan(0);
});

Tests use the Chai assertion library via insomnia.expect(). The insomnia.test() wrapper labels each assertion.

Run tests by clicking the Tests tab in the response panel after sending a request. You see a pass/fail list for each test. You can also run the entire collection's tests in sequence using the Collection Runner.

Collection Runner

The Collection Runner (under Collection → Run Collection) executes all requests in order and reports test results. You can:

• Select which requests to include
• Set the delay between requests
• Choose how many iterations to run (for data-driven tests)
• Upload a data file (JSON or CSV) for parametrized runs

The runner produces a summary with request count, pass/fail counts per test, and total run time.

GraphQL Support

Insomnia has first-class GraphQL support. Create a new request and choose GraphQL as the method — not POST with a JSON body, but a proper GraphQL request type.

Insomnia auto-discovers the schema through introspection when you enter a GraphQL endpoint URL. The query editor provides:

• Schema explorer — browse all types, queries, and mutations in a sidebar
• Autocomplete — field names, argument names, types
• Inline documentation — hover over any field to see its description
• Query variables — separate panel for JSON variables

Example query:

query GetUserWithPosts($userId: ID!, $limit: Int = 10) {
  user(id: $userId) {
    id
    name
    email
    posts(limit: $limit) {
      id
      title
      publishedAt
      tags {
        name
      }
    }
  }
}

Variables:

{
  "userId": "usr_abc123",
  "limit": 5
}

Subscription support (WebSocket-based GraphQL subscriptions) is also available.

Plugins

Insomnia has a plugin system that extends the app's functionality. Install plugins from Preferences → Plugins. Notable plugins:

• insomnia-plugin-save-variables — writes response values to environment variables automatically
• insomnia-plugin-jsonpath — adds JSONPath template tag for extracting values
• insomnia-plugin-faker — integrates the Faker library for generating test data
• insomnia-plugin-aws-cloudformation — queries CloudFormation stack outputs as template tags
• insomnia-plugin-cookie-jar — advanced cookie management

Write your own plugin in Node.js. Plugins can add new template tags, response hooks, request hooks, and even custom themes.

Plugin example — a custom template tag that generates a HMAC signature for request authentication:

// insomnia-plugin-hmac-signature
const crypto = require('crypto');

module.exports.templateTags = [{
  name: 'hmacSignature',
  displayName: 'HMAC Signature',
  description: 'Generate an HMAC-SHA256 signature',
  args: [
    { displayName: 'Secret Key', type: 'string' },
    { displayName: 'Message', type: 'string' }
  ],
  async run(context, secretKey, message) {
    return crypto
      .createHmac('sha256', secretKey)
      .update(message)
      .digest('hex');
  }
}];

Place the plugin directory in ~/.insomnia/plugins/ and restart Insomnia.

Code Generation

Insomnia can generate code snippets for any request. Right-click a request and select Generate Code. Available targets include:

• cURL — a ready-to-paste curl command
• JavaScript — using fetch, axios, or XMLHttpRequest
• Python — using requests or http.client
• Go — using net/http
• PHP — using cURL or Guzzle
• Ruby — using Net::HTTP
• Java — using OkHttp or Unirest
• Swift — using URLSession
• C — using libcurl

Generated code substitutes current environment variable values, so what you get is a runnable snippet against your actual endpoint.

Design Mode and OpenAPI

Insomnia includes a full OpenAPI editor under Design documents. Create a Design document in your project, write or paste an OpenAPI 3.x spec, and Insomnia gives you:

• A visual preview of the API spec
• Lint warnings for spec errors
• Generate Collection — instantly creates a request collection from the spec

This is useful for API-first teams who write the spec before building the implementation. Design the API in Insomnia, share the spec with frontend and backend developers, then generate a test collection from the same spec.

inso CLI for CI/CD

inso is the Insomnia CLI. It can run test suites from a collection file exported from the desktop app, or from a collection in an Insomnia Cloud workspace.

Export your collection from Insomnia: Application → Preferences → Data → Export Data (choose "Current Collection").

Run tests with inso:

# Run all test suites in a collection file
inso run <span class="hljs-built_in">test --<span class="hljs-built_in">env Staging collection.json

<span class="hljs-comment"># Run a specific test suite by name
inso run <span class="hljs-built_in">test <span class="hljs-string">"User API Tests" --<span class="hljs-built_in">env Staging collection.json

<span class="hljs-comment"># Export JUnit XML results for CI
inso run <span class="hljs-built_in">test --<span class="hljs-built_in">env Staging --reporter junit --output results.xml collection.json

GitHub Actions workflow:

name: Insomnia API Tests
on:
  push:
    branches: [main]
  pull_request:

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install inso
        run: npm install -g insomnia-inso

      - name: Run API tests
        run: |
          inso run test \
            --env "Staging" \
            --reporter junit \
            --output results.xml \
            insomnia-collection.json
        env:
          INSOMNIA_API_KEY: ${{ secrets.INSOMNIA_API_KEY }}

      - name: Publish test results
        uses: dorny/test-reporter@v1
        if: always()
        with:
          name: Insomnia API Tests
          path: results.xml
          reporter: java-junit

If you store your collection in Insomnia Cloud (requires account), inso can pull the collection directly using the Cloud API key — no need to export a file.

Comparison with Postman

Insomnia's edge over Postman is the open-source nature, the quality of the GraphQL interface, and the plugin flexibility. Postman's edge is the broader ecosystem — more pre-built integrations, a larger marketplace of shared collections, and more mature monitoring features.

For teams that want an open-source client with a professional-grade UI, strong GraphQL support, a real plugin system, and CI integration via inso, Insomnia is an excellent choice in 2026.