Collection Runner — User Guide

Run entire API collections automatically, validate every response with tests, and track results across runs — without clicking Send on each request one by one.

Table of Contents

1. What Is the Collection Runner?
2. Opening the Runner
3. Setting Up a Run
   • 3.1 Choose a Collection
   • 3.2 Pick an Environment
   • 3.3 Configure the Run Sequence
   • 3.4 Set Run Options
   • 3.5 Upload a Data File (for data-driven runs)
4. Running and Stopping
5. Reading the Results
   • 5.1 Run History Panel
   • 5.2 Run Details Panel
   • 5.3 Request Timing Breakdown
   • 5.4 Pre-Request Script Logs
6. Exporting Results
7. Writing Test Scripts
   • 7.1 How Test Scripts Work
   • 7.2 Basic Assertions
   • 7.3 JSON Schema Validation
   • 7.4 Reading and Writing Variables
   • 7.5 Reading Data File Values
   • 7.6 Controlling Execution Flow
8. Writing Pre-Request Scripts
9. Data-Driven Testing with CSV and JSON
10. Secret Variables and Masking
11. Error Categories
12. Tips and Best Practices
13. Frequently Asked Questions

1. What Is the Collection Runner?

The Collection Runner lets you execute every request in a collection — one after another — in a single click. It is useful for:

• Smoke testing — quickly verify that a newly deployed API responds correctly across all endpoints.
• Regression testing — run the same suite of requests before and after a code change to catch regressions.
• Data-driven testing — run the same set of requests many times, each time with a different row of data from a CSV or JSON file (for example, testing with different user accounts, IDs, or payloads).
• End-to-end workflows — string requests together so that the output of one (such as an auth token) automatically feeds into the next.
• Generating reports — export a record of a run as a PDF, HTML page, or JUnit XML file for sharing with your team or attaching to a CI pipeline.

2. Opening the Runner

Click the ▶ Play icon in the sidebar rail on the left side of the window.

The runner opens in a two-panel layout:

• Left — Run history (all previous runs for the active workspace)
• Right — Results of the selected run

3. Setting Up a Run

3.1 Choose a Collection

Use the Collection dropdown at the top to pick the collection you want to run. The list shows every collection in your active workspace.

If the dropdown is empty, you need to create a collection first. See the main user guide, section 5 — Collections & Folders.

3.2 Pick an Environment

Use the Environment dropdown to select an environment. The runner will substitute all {{variableName}} placeholders in your request URLs, headers, and bodies using that environment's values.

If you don't need variable substitution, leave it set to No Environment.

3.3 Configure the Run Sequence

Click Configure Run to expand the run sequence panel. Here you can:

• Enable or disable individual requests — tick or untick the checkbox next to each request. Disabled requests are skipped entirely.
• Reorder requests — drag a request up or down by its handle. The order shown here is the order requests will execute.

By default, all requests are enabled and appear in their original collection order (root-level requests first, then folders depth-first).

3.4 Set Run Options

The Configure Run panel also reveals four run options:

3.5 Upload a Data File (for data-driven runs)

Below the run options you will find the Data File section. This is for data-driven testing — running the same set of requests multiple times, once for each row in a file.

1. Click Upload CSV or JSON.
2. Choose a .csv or .json file from your computer.
3. The runner shows how many rows (iterations) were detected, along with any warnings if the file had formatting issues.
4. Click Preview to inspect the data in a table before running.
5. Click Clear to remove the file and go back to a single run.

Once a data file is loaded, the runner will loop through every row and execute the entire request sequence once per row. Each row's column values are available as variables inside your requests and scripts.

For full details, see Section 9 — Data-Driven Testing.

4. Running and Stopping

To start: Click the Run button (top right of the controls bar). It shows the number of selected requests in brackets, e.g. Run (12).

While the run is in progress:

• The button changes to a spinning clock labelled Running…
• Results appear in real time in the right panel as each request completes
• A toast notification appears when the run finishes

To stop early: Click the Stop button that appears while the run is active. The runner finishes the request currently in flight and then halts. The run is marked as stopped in the history.

5. Reading the Results

5.1 Run History Panel

The left panel lists every completed run, most recent at the top. Each entry shows:

• Collection name — which collection was run
• Environment name — which environment was used (or "No Environment")
• ✓ N — number of requests that returned a 2xx status (green)
• ✗ N — number of requests that returned a non-2xx status or had failing test assertions (red)
• ⏱ N ms — total wall-clock time for the run
• ⏹ — appears if the run was stopped manually before finishing
• Iterations badge — if a data file was used, shows the number of iterations and the file name

Click any run to load its full results in the right panel.

5.2 Run Details Panel

When you click a run, the right panel shows:

Summary bar (across the top):

• Total requests executed
• Passed count (green) and failed count (red)
• Total execution time
• Total data transferred (KB / MB)
• Iteration count and data file name, if applicable

Results table — one row per request (or per request per iteration if you used a data file):

Clicking a row opens the full response detail for that request, including:

• Response headers, body, cookies
• Test script results (pass/fail with error messages)
• Pre-request script logs (if the request had a pre-request script)
• Request timing breakdown (DNS / TCP / TLS / Waiting / Download)

Iteration groups — if the run used a data file, results are grouped under Iteration 1, Iteration 2, etc., so you can see results per data row.

Skipped requests — requests skipped via fc.execution.skipRequest() in a script are shown with a Skipped badge instead of a status code.

5.3 Request Timing Breakdown

When you click on a result row and look at the response detail, a timing panel appears at the bottom if timing data is available. It shows a proportional horizontal bar broken down into phases:

The bar shows each phase relative to the total, with the exact millisecond value alongside each segment. This is useful for pinpointing whether slowness is in DNS lookup, server processing, or download.

5.4 Pre-Request Script Logs

If a request has a pre-request script, a Pre-request Logs tab appears in the response detail panel. It shows:

• Any console.log() output from the script
• Script errors, if the script threw an exception

This makes it easy to debug pre-request scripts without opening the Console separately.

6. Exporting Results

You can export any completed run from the run history. Hover over a run in the left panel and click the Download icon to open the export menu:

All export formats include:

• Run metadata (collection name, environment, date and time, status)
• Summary statistics (total, passed, failed, duration)
• Per-request results with method, name, status, and response time
• Test assertion results (pass/fail with error messages)

JUnit XML is the most useful format for automation — most CI systems can parse it and display test results natively. Each HTTP request becomes a test suite and each fc.test() assertion becomes a test case.

Note: Request and response bodies are not included in exports to keep files concise and avoid accidentally leaking sensitive data.

7. Writing Test Scripts

Test scripts let you validate the response from each request automatically. They run inside a secure sandbox after the response is received. If any assertion fails, that request is counted as failed in the results.

7.1 How Test Scripts Work

Open a request, go to the Scripts tab, and write JavaScript in the Test Script section. The script runs every time that request is executed by the runner (and also when you click Send manually).

The script has access to a fc object (and pm as an alias, for Postman compatibility) that provides the response, assertion helpers, and variable access.

7.2 Basic Assertions

Check the status code:

fc.test("Returns 200 OK", function () {
    fc.response.to.have.status(200);
});

Check a JSON field value:

fc.test("User ID is present", function () {
    var body = fc.response.json();
    fc.expect(body.id).to.exist;
    fc.expect(body.name).to.equal("Alice");
});

Check response time:

fc.test("Responds within 1 second", function () {
    fc.expect(fc.response.responseTime).to.be.below(1000);
});

Check a header:

fc.test("JSON content type", function () {
    fc.response.to.have.header("Content-Type", "application/json");
});

Check one of several status codes:

fc.test("Create or already exists", function () {
    fc.expect(fc.response.code).to.be.oneOf([200, 201, 409]);
});

Negate an assertion:

fc.test("Body does not contain error", function () {
    fc.expect(fc.response.text()).to.not.include("error");
});

Full list of assertion methods:

fc.expect(value).to.equal(expected)          // strict equality
fc.expect(value).to.eql(expected)            // deep equality (objects/arrays)
fc.expect(value).to.include(substring)       // string or array contains
fc.expect(value).to.be.true
fc.expect(value).to.be.false
fc.expect(value).to.exist                    // not null or undefined
fc.expect(value).to.be.above(number)
fc.expect(value).to.be.below(number)
fc.expect(value).to.be.oneOf([a, b, c])
fc.expect(array).to.have.length(n)
fc.expect(object).to.have.property("key")
fc.expect(object).to.have.nested.property("a.b.c")
fc.expect(value).not.to.equal(other)

7.3 JSON Schema Validation

You can validate that the entire response body matches a JSON Schema:

fc.test("Response matches schema", function () {
    fc.response.to.have.jsonSchema({
        type: "object",
        required: ["id", "name", "email"],
        properties: {
            id:    { type: "number" },
            name:  { type: "string" },
            email: { type: "string", format: "email" }
        }
    });
});

If validation fails, the error message lists every property that did not match, making it easy to spot exactly what changed in the API response shape.

7.4 Reading and Writing Variables

Read an environment variable:

var baseUrl = fc.environment.get("baseUrl");

Write an environment variable (useful for passing values like tokens from one request to the next):

fc.test("Store auth token", function () {
    var token = fc.response.json().access_token;
    fc.environment.set("authToken", token);
});

Collection variables (scoped to the collection, not the environment):

var userId = fc.collectionVariables.get("userId");
fc.collectionVariables.set("userId", fc.response.json().id);

Variables set in a test script are immediately available to all subsequent requests in the same run. This is how you chain requests — for example, log in first, store the token, then use {{authToken}} in the URL or headers of every later request.

7.5 Reading Data File Values

When a data file is loaded, each row's column values are accessible in scripts via fc.iterationData:

// CSV headers become the keys
var username = fc.iterationData.get("username");
var password = fc.iterationData.get("password");

// Or get everything as a plain object
var allFields = fc.iterationData.toObject();

These values are also available as {{columnName}} placeholders directly in request URLs, headers, and bodies — you don't need a script just to substitute data file values.

7.6 Controlling Execution Flow

Inside a test script (or pre-request script), you can change which request runs next:

Skip the next request in the sequence:

fc.execution.skipRequest();

Jump to a specific request by name:

// Useful for conditional branching — e.g. skip cleanup if setup failed
fc.execution.setNextRequest("Cleanup - Delete User");

Abort the entire run immediately:

fc.execution.abort();

fc.execution.setNextRequest() accepts the exact request name as it appears in the collection. Looping is safe — the runner stops automatically if it detects more than twice the number of requests worth of jumps, preventing infinite loops.

8. Writing Pre-Request Scripts

Pre-request scripts run before the HTTP request is sent. Open a request, go to the Scripts tab, and write in the Pre-Request Script section.

Use pre-request scripts to:

Generate dynamic values (like timestamps or UUIDs):

fc.environment.set("timestamp", Date.now().toString());
fc.environment.set("requestId", crypto.randomUUID());

Build a signature or hash before the request:

// Example: set a nonce for an API that requires it
fc.environment.set("nonce", Math.random().toString(36).slice(2));

Conditionally set variables based on data file values:

var env = fc.iterationData.get("environment");
fc.environment.set("baseUrl", env === "prod"
    ? "https://api.example.com"
    : "https://staging.api.example.com"
);

Resolve a variable dynamically:

var resolvedUrl = fc.variables.replaceIn("https://{{baseUrl}}/users/{{userId}}");
fc.environment.set("computedUrl", resolvedUrl);

Pre-request scripts have access to the same fc.environment, fc.collectionVariables, fc.iterationData, and fc.execution APIs as test scripts, but do not have access to fc.response (since no response has been received yet) and cannot run fc.test() assertions.

Any console.log() output from pre-request scripts appears in the Pre-request Logs tab of the response detail panel.

9. Data-Driven Testing with CSV and JSON

Data-driven testing means running the same collection multiple times, each time with different input data. Instead of duplicating requests for every test case, you define one set of requests and supply a data file with many rows.

Preparing Your Data File

CSV format:

• First row must be the column headers (these become variable names)
• One data row per iteration
• Values containing commas must be wrapped in double quotes: "Smith, John"
• Double quotes inside values are escaped by doubling them: "She said ""hello"""

username,password,expected_status
alice@example.com,hunter2,200
bob@example.com,wrongpass,401
,missingusername,400

JSON format:

• Root must be an array of objects
• Each object is one iteration
• All values are treated as strings internally (numbers and booleans are converted)
• Nested objects are JSON-stringified into a single string value

[
  { "userId": "101", "role": "admin" },
  { "userId": "202", "role": "editor" },
  { "userId": "303", "role": "viewer" }
]

Using Data Values in Requests

Once a data file is loaded, each column is automatically available as a {{variable}} anywhere in your requests:

URL:    https://{{baseUrl}}/users/{{userId}}
Header: X-Role: {{role}}
Body:   { "username": "{{username}}", "password": "{{password}}" }

No script required — variable substitution happens automatically for each iteration.

Using Data Values in Scripts

fc.test("Login returns expected status", function () {
    var expected = parseInt(fc.iterationData.get("expected_status"));
    fc.expect(fc.response.code).to.equal(expected);
});

How Iterations Work

• The runner executes the full request sequence once per data row.
• Results are grouped by iteration in the results panel (Iteration 1, Iteration 2, …).
• Each iteration is independent — environment or collection variable changes made by one iteration's scripts carry forward into the next iteration (useful for chaining, but be aware of this if you expect a clean state each time).
• The Run History entry shows the total iteration count and the data file name.

Previewing Data Before Running

After uploading a file, click Preview to open a paginated table showing all the parsed rows. Rows that had formatting problems (wrong number of columns, etc.) are highlighted in yellow. You can inspect the data and clear it if it does not look right before running.

10. Secret Variables and Masking

Some environment variables hold sensitive values like API keys, passwords, and tokens. Mark these as secret in the Environment manager (set the variable type to Secret).

When the runner executes, any secret variable values are automatically replaced with **** in:

• Test script console.log() output shown in the results panel
• Pre-request script log output

This prevents sensitive values from appearing in run results that might be shared or exported.

Important: Secret masking applies only to log output. The actual secret values are still passed correctly to your requests and scripts — only the display in the results panel is masked.

Short values (4 characters or fewer) are never masked, as they are too likely to accidentally match unrelated text in a response body.

11. Error Categories

When a request fails, the results table shows an error category badge to help you understand why:

These categories are inferred automatically from the error message and response state, so you can quickly triage large runs without reading individual error messages.

12. Tips and Best Practices

Chain requests using variables Set fc.environment.set("token", ...) in a login request's test script, then use {{token}} in the Authorization header of all subsequent requests. The runner passes variable values forward automatically.

Use Stop on First Failure for CI smoke tests If you just want to know whether a deployment is healthy, enable Stop on First Failure so the run halts as soon as something goes wrong rather than running the full suite.

Add delays for rate-limited APIs If your API enforces rate limits (e.g. 10 requests per second), set a Delay Between Requests of at least 100 ms to stay under the limit without having to count manually.

Use retries for flaky endpoints For endpoints that occasionally return 500 or time out due to infrastructure issues, set Retry Failed Requests to 2 or 3. The runner retries automatically and records only the final result.

Keep your data files in version control Store CSV or JSON data files alongside your collection exports so that your team can run the same data-driven test suite consistently.

Export JUnit XML for CI pipelines Most CI systems (Jenkins, GitHub Actions, GitLab CI, CircleCI) have built-in support for JUnit XML reports. Export after each run and attach the XML file as a test artifact to get a proper pass/fail report in your pipeline without any extra tooling.

Preview data before long runs When running a large data file (hundreds of rows), always click Preview first to verify the data parsed correctly. Catching a formatting issue before a 500-iteration run saves time.

Use fc.execution.setNextRequest for conditional flows If a workflow branches based on a response (e.g. skip cleanup if the setup step failed), use fc.execution.setNextRequest("Step Name") in a test script to jump to the right next step.

Mark API keys and tokens as Secret Use the Secret variable type for any variable containing credentials. Their values will be masked in run results and logs, making it safer to export or share reports.

13. Frequently Asked Questions

Can I run just one folder instead of the whole collection? Yes. In the Run Sequence panel, uncheck the requests you don't want to run. You can also deselect entire folders by unchecking all requests inside them.

Do test scripts run when I click Send on a single request (not via the runner)? Yes. Test scripts run both in the runner and in normal single-request mode. Results appear in the Tests tab of the response panel.

Can I use Postman-style pm.* API calls? Yes. pm is fully supported as an alias for fc. Any script written with pm.test(...), pm.expect(...), pm.environment.get(...), etc. will work without changes.

Why are my {{variables}} not being substituted? Make sure you have an environment selected in the runner. Variable names are case-sensitive — {{baseUrl}} and {{BaseURL}} are treated as different variables.

The runner stops after one request with "stopped" status — why? Check whether a test script calls fc.execution.abort(). Also check if Stop on First Failure is enabled and that first request is failing.

My data file shows warnings in the Preview — is that a problem? Warnings appear when a row has a different number of columns than the header (for CSV), or when an array item in a JSON file is not an object. Those rows are still included in the run, with missing columns filled in as empty strings. Review the preview to decide if you need to fix the file.

Can I run the same collection against multiple environments in one click? Not in a single run. You would need to run once per environment. One approach is to put the environment name in your data file and use a pre-request script to set the base URL based on fc.iterationData.get("environment").

Are run results saved permanently? Yes. Run history and results are stored in the local database on your machine. They persist across app restarts. They are also included in GitHub Sync backups if you have that enabled.

How many iterations can I run from a data file? There is no hard limit. Very large files (thousands of rows × many requests) will take a long time, so consider testing with a sample first.