Collection Runner

Collection Runner

Run all requests in a collection or folder sequentially with configurable delays, iterations, and data-driven testing.

---

Quick Start

1. Right-click a collection or folder in the sidebar
2. Select Run Collection
3. Configure run options
4. Click Start Run

---

Run Options

Option	Description	Default
Iterations	Number of times to run the entire collection	1
Delay	Milliseconds between requests	0
Data File	CSV/JSON/YAML file for data-driven testing	None
Environment	Environment to use	Active
Stop on Error	Stop the run on first failure	No

---

Execution Order

Requests run in the order they appear in the collection tree, top to bottom:

my-collection/
├── auth/
│   └── login.yaml              # 1st
├── users/
│   ├── get-all-users.yaml      # 2nd
│   ├── create-user.yaml        # 3rd
│   └── get-user-by-id.yaml     # 4th
└── cleanup/
    └── delete-user.yaml        # 5th

Custom Order

Use _folder.yaml to specify execution order:

# users/_folder.yaml
order:
  - create-user.yaml
  - get-user-by-id.yaml
  - get-all-users.yaml

---

Data-Driven Testing

Feed different data into each iteration using external files.

CSV Data File

username,email,role
john,john@example.com,admin
jane,jane@example.com,user
bob,bob@example.com,viewer

JSON Data File

[
  { "username": "john", "email": "john@example.com", "role": "admin" },
  { "username": "jane", "email": "jane@example.com", "role": "user" },
  { "username": "bob", "email": "bob@example.com", "role": "viewer" }
]

Using Data in Requests

Each row/object becomes available as variables:

name: Create User
method: POST
url: "{{baseUrl}}/api/users"
body:
  type: json
  content: |
    {
      "username": "{{username}}",
      "email": "{{email}}",
      "role": "{{role}}"
    }

With 3 data rows and 2 iterations = 6 total runs (2 full passes through all 3 rows).

---

Results

Summary View

After a run completes, you see:

• Total requests: Number of requests executed
• Passed: Requests where all assertions/tests passed
• Failed: Requests with at least one failure
• Errors: Requests that couldn't be sent (network error, etc.)
• Duration: Total run time
• Average response time: Across all requests

Per-Request Details

Click any request in the results to see:

• Status code and response time
• Individual assertion results (pass/fail)
• Test results with error messages
• Response body
• Console output from scripts

---

Export Results

Export run results in multiple formats:

Format	Use Case
JSON	Programmatic processing, custom dashboards
JUnit XML	CI/CD integration (Jenkins, GitLab, GitHub Actions)
HTML	Human-readable report for sharing

JUnit XML for CI/CD

<testsuites name="My API Collection" tests="10" failures="1" time="3.456">
  <testsuite name="Users" tests="4" failures="0">
    <testcase name="GET /users - status is 200" time="0.245" />
    <testcase name="GET /users - has users array" time="0.002" />
  </testsuite>
  <testsuite name="Auth" tests="2" failures="1">
    <testcase name="POST /login - returns token" time="0.189" />
    <testcase name="POST /login - token is JWT" time="0.001">
      <failure message="Expected token to match JWT pattern" />
    </testcase>
  </testsuite>
</testsuites>

---

Variable Chaining

Variables set in one request are available in subsequent requests:

1. POST /auth/login
   → postResponseScript sets {{accessToken}}

2. GET /users (uses {{accessToken}} in Bearer auth)
   → postResponseScript sets {{firstUserId}}

3. GET /users/{{firstUserId}}
   → Uses the ID from step 2

This makes the collection runner powerful for end-to-end API testing workflows.

---

CLI Integration

Run collections from the command line for CI/CD:

# Basic run
apiark run ./my-collection

# With environment and data
apiark run ./my-collection --env production --data users.csv

# With JUnit output for CI
apiark run ./my-collection --reporter junit --output results.xml

# Fail the CI build on test failures
apiark run ./my-collection --reporter junit --bail

See CLI Reference for full details.