Data‑Driven API Testing with Postman Collection Runner and CSV Files

Problem: Repeating the same request with different parameters

When you need to verify an API endpoint against many input values—such as checking a user‑lookup service for a list of IDs—manually creating a separate request for each value is tedious and error‑prone. Postman’s Collection Runner solves this by feeding a collection with rows from an external data file, turning a single request into a data‑driven test suite.

Thesis

Using the Collection Runner with a CSV (or JSON) file lets you execute a Postman collection multiple times, automatically mapping file columns to variables, while keeping the test logic inside Postman’s test scripts. This approach is quick to set up, requires no external code, and provides immediate pass/fail feedback for each iteration.

Setting Up the Runner

1. Open the collection you want to run in Postman Desktop.
2. Click the Runner tab at the bottom of the workspace.
3. Drag the collection into the right‑hand panel or use Add Collection to select it.
4. Under the Data section, choose Select File and point to a UTF‑8 encoded CSV (or JSON) file.
5. Postman will display the column headers; ensure they match the variable names you plan to use (e.g., id).
6. Click Start Run to begin.

Worked Example: GET /users/{{id}}

Suppose you have a simple GET request that retrieves a user by ID:

GET https://api.example.com/users/{{id}}

Attach a test script to validate the response:

pm.test('Status 200', () => {
  pm.response.to.have.status(200);
});

pm.test('ID matches', () => {
  const json = pm.response.json();
  const expected = pm.variables.get('id');
  pm.expect(json.id).to.equal(expected);
});

Create a CSV file named users.csv with the following content:

id
1
2
3
4
5

When you run the Collection Runner:

1. Postman reads each row, assigns the id column to the variable {{id}}.
2. The request URL becomes, for example, https://api.example.com/users/1 for the first iteration.
3. The test script runs after each response, marking the iteration as pass or fail.

After the run, the Runner UI shows a table with one row per CSV line, indicating pass/fail status and response time.

Trade‑off and Limitations

• Execution time: Large data files increase total run time because each iteration performs a full HTTP request. If you have thousands of rows, consider sampling or splitting the file.
• Memory usage: The Runner loads the entire data file into memory; very large files may affect Postman Desktop performance.
• Debugging complexity: Pre‑request scripts that depend on iteration‑specific data can be harder to troubleshoot than in a dedicated test framework where you can set breakpoints per iteration.
• Variable precedence: Collection or global environment variables with the same name as a CSV column will override the data file value. Be aware of this scope order to avoid unexpected values.

Verifying the Results

1. After the run finishes, look at the Summary bar at the top of the Runner output; it shows total iterations, passed, and failed.
2. Click any iteration in the table to open the request/response details for that specific row.
3. Optionally, click Export Results to download a JSON or CSV report containing each iteration’s status, response time, and any test assertions.
4. To confirm that the correct ID was used, open the exported report and verify that the url field for each iteration contains the expected /users/<value> pattern.

Actionable Closing

Start small: create a collection with a single request, attach a CSV of three to five rows, and run the Collection Runner. Observe the pass/fail table and export the report to ensure the data mapping works as expected. Once comfortable, scale up to larger datasets while monitoring run time and memory usage. This approach gives you repeatable, data‑driven API validation without leaving the Postman environment.