Insomnia logo
  • Documentation
  • Get Started for Free
    • Introduction to Insomnia
    • Install Insomnia
    • Send Your First Request
    • Import and Export Data
    • Environment Variables
    • Global Environments
    • Insomnia Accounts
    • Forgotten Passphrase
    • Managing E2EE (End-to-End Encryption)
    • Organizations
    • Enable Enterprise membership
    • Configuring EE SSO
    • Integrating Insomnia Enterprise with Okta SAML 2.0
    • Integrating Insomnia Enterprise with Okta OpenID Connect
    • Integrating Insomnia Enterprise with Microsoft Azure/Entra ID SAML 2.0
    • Insomnia Whitelisting Guide for Enterprise Users
    • Transfer enterprise organizations and license
    • Configuring SCIM
    • Multiple Owners
    • Manage Domains
    • Invite Controls
    • Storage Controls
    • Session Report
    • Insomnia Subscriptions
    • Insomnia Subscription Management
    • Scratch Pad Tutorial
    • Requests
    • Responses
    • Request Collections
    • Request Timeouts
    • Chaining Requests
    • Post CSV Data
    • SOAP Requests
    • gRPC
    • WebSocket Support
    • Get Started with Documents
    • Design Documents
    • Linting
    • GraphQL for OpenAPI
    • Migrate from Designer
    • Unit Testing
    • Stress Testing
    • Insomnia Storage Options Guide
    • Sync with Insomnia Cloud
    • Sync with Git
    • Key Security Features
    • Security Standards
    • Signup and Authentication
    • Analytics Collected
    • End to End Data Encryption
    • Software Bill of Materials
    • Verifying Build Provenance for Signed Insomnia Binaries
    • Authentication
    • Client Certificates
    • Collection Runner
    • Generate Code Snippet
    • Cookie Management
    • Encoding
    • GraphQL Queries
    • Run in Insomnia Button
    • Key Maps
    • Proxy
    • Folder-level settings
    • Introduction to Plugins
    • Context Object Reference
    • Template Tags
    • Hooks and Actions
    • Custom Themes
    • AI Runner
    • FAQ
    • Application Data
    • SSL Validation
    • Password Recovery
    • Introduction to Inso CLI
    • Install Inso CLI
    • CLI Command Reference
      • inso run test
      • inso run collection
      • inso lint spec
      • inso export spec
      • inso script
      • Using Custom Linting with Inso CLI
    • Configuration
    • Inso CLI on Docker
    • Software Bill of Materials
    • Verifying Signatures for Signed Inso CLI Images
    • Verifying Inso CLI Build Provenance
      • Verifying Build Provenance for Signed Inso CLI Images
      • Verifying Build Provenance for Signed Inso CLI Binaries
    • Continuous Integration
    • Insomnia Pre-request Script Overview
    • Insomnia After-Response Script Overview
    • Secret Environment Variables
    • External Vault Integration (Enterprise feature)
    • Insomnia API Mocking Overview
    • Enterprise Login Report

Collection Runner

The Collection Runner allows you to run your collections an unlimited number of times, whether you are storing your data locally, on Git, or in the cloud. You can easily test and verify that your collections are functioning properly and that the APIs you are consuming remain consistent.

To open the Collection Runner, go to one of your collections (or the Collection tab) and click the Run button.

collection run button

The Collection Runner allows you to arrange the execution order of your requests and run multiple iterations of your tests:

collection run request order

Using Sample Data

You can use your own sample data to feed into the iterations of the Collection Runner.

To do this, upload a custom CSV or JSON file. The variables detected from these files can be used in your pre-request and after-response scripts, and will take precedence over any environment variables with the same name.

collection run preview data

Example: CSV

You can setup variables by the name they have on the sample data file of your choice, for example:

Title,ReleaseYear,Developer
Command & Conquer: Tiberian Dawn,1995,Westwood Studios
Command & Conquer: Red Alert,1996,Westwood Studios
Command & Conquer: Tiberian Sun,1999,Westwood Studios
Command & Conquer: Red Alert 2,2000,Westwood Studios
...

Means that anywhere on your requests you can setup Title, ReleaseYear and Developer, like:

example template var

And when running the collection runner they will be replaced in place.

example collection run variables results

Note: It is also allowed to reference values from CSV or JSON in the same manner as referencing environment variables. And variables from data files will take precedence over environment variables.

Example: JSON

JSON also works with runner, this is an example:

[
    {"id": 1, "deviceName": "device1" },
    {"id": 2, "deviceName": "device2" }
]

Accessing CSV or JSON data from Scripts

It is allowed to access values from custom CSV or JSON file. For each row, you can access values through insomnia.iterationData.

For example, if the above JSON file has been uploaded, you can access id and deviceName in this way:

const id = insomnia.iterationData.get('id');
const deviceName = insomnia.iterationData.get('deviceName');

And most of methods of insomnia.environment also work for insomnia.iterationData.

Test Results in the Collection Tab

With the Collection Runner, we have also introduced a new Test Results section.

Any tests that you define in pre-request or after-response scripts will appear when you execute them via the Collection Runner.

collection run test results

You can filter tests by status (e.g., Passed, Failed, All, Skipped) and browse through test results from previous collection runs.

The Test Results section is also available when you run tests for an individual request without using the Collection Runner.

Note: The test results shown in the Requests and in the Collection Runner are not to be confused with Insomnia’s Unit Testing feature.

Work with Runner in Scripts

The collection runner exposes several interfaces which help you to work with it in scripts.

Get Information of the Active Request

The insomnia.execution.location and insomnia.execution.location.current exposes the path of the active request and the last element of path, for example:

// Let's assume that the active request is located in: TopRequestGroup/RequestGroup/Request1

console.log(insomnia.execution.location);
// It will output: ["TopRequestGroup", "RequestGroup`", "Request1"]

console.log(insomnia.execution.location.current);
// It will output: Request1

Skip the Current Request

The insomnia.execution.skipRequest allows to skip the current active request in the pre-request script, for example, in the pre-request scripts:

// The runner will skip the current request and move to the next one (if exists)
insomnia.execution.skipRequest();

Dynamically Set the Next Request

The insomnia.execution.setNextRequest accepts request id or request name as the next request. Currently you are able to call it in the pre-request script, for example:

// The runner will move to the specified request (if exists), by skipping some requests
insomnia.execution.setNextRequest("requestName");
// Request id is also supported
insomnia.execution.setNextRequest("req_23590845293c4005b2127e211369f069");

This allows to dynamically change the workflow.

Abort the Execution

The insomnia.execution.setNextRequest can be used to redirect to a request for teardown, so that the exeuction will be ended.

Run with CLI

The Run button dropdown includes an option to generate the CLI command which can be used to run the same collection using inso CLI. This command can be used in combination with setup-inso to run this collection in a GitHub action. More information about the CLI options can be found in the CLI docs section

Edit this page
Report an issue
    COMPANY
  • Insomnia
  • Blog
  • Changelog
  • Pricing
  • Careers
    PRODUCTS
  • Insomnia
  • Inso (CLI)
    RESOURCES
  • Sign In
  • Documentation
  • Support
    LEGAL
  • Privacy Policy
  • Terms & Conditions
© Kong Inc. 2021