Running a Collection in KeyRunner

KeyRunner allows users to execute API collections with configurable iterations and input data. This guide explains how to run a collection, use a data file, set iterations, and view results.

---

1. Running a Collection

Starting the Collection Runner

1. Locate your collection in the sidebar.
2. Click the three-dot menu next to the collection name.
3. Select "Run Collection" from the dropdown menu.
4. This will open the Run Collection screen.

Configuring the Run Order

1. Select API Requests

   • Under "Run Order," choose the API requests to execute.
   • Use "Select All" or "Reset" as needed.

2. Run Configuration

   • Choose a mode:
     • Run Manually (Immediate execution).
     • Schedule Collection (Periodic execution).
     • Run via CLI (Execution via KeyRunner CLI—coming soon).

3. Run Parameters

   • Iterations: Number of times to execute the collection.
   • Delay Between Iterations: Optional wait time (in seconds) between runs.

---

2. Using a Data JSON File

How Data Files Work

• You can provide a JSON file to pass dynamic values into API requests.
• These values can be referenced in URLs, headers, bodies, or any other request fields using {{variable_name}}
• The referenced variables will appear in red to indicate runtime injection.

Steps to Use a Data File

1. Click "Browse" and select a JSON file.
2. Ensure the file path is correctly loaded.
3. KeyRunner dynamically injects values from the JSON file at runtime.

Example Data File (data.json)

[
  {
    "patient_id": "12345",
    "auth_token": "abcdef",
    "endpoint": "/fhir/Patient"
  },
  {
    "patient_id": "67890",
    "auth_token": "ghijkl",
    "endpoint": "/fhir/Doctor"
  }
]

Example API Request Using Data

• URL: https://api.example.com
• Headers:

  {
    "Authorization": "Bearer {{auth_token}}"
  }

• Body:

  {
    "patient_id": "{{patient_id}}"
  }

🔴 Variables will appear in red in the UI, indicating runtime evaluation.

---

3. Executing the Collection

1. Configure requests, iterations, and data file.
2. Click "Run Collection".
3. KeyRunner will:
   • Inject values from the data file into requests.
   • Execute the collection for each row in the data file.
   • Repeat the execution based on the iteration count.

---

4. Viewing Execution Results

After execution:

1. Right panel displays results per iteration.

2. For each request, you’ll see:
   • API Name
   • Response Time (in ms)
   • Status Code
   • Click "View" for detailed logs.

Note: If multiple iterations are configured, KeyRunner will cycle through rows in the data file for each iteration.

---

5. Troubleshooting & Common Issues

Issue	Cause	Solution
404 Not Found	API endpoint missing or incorrect	Verify API URL and data file values
Unauthorized (401)	Missing or incorrect auth_token	Ensure correct token in JSON file
Empty Request Body	Data key missing in JSON file	Check for typos or missing fields
Variable Appearing in Red but Not Replaced	Normal behavior (runtime injection)	No action needed,resolved at execution

---