Data‑Driven API Testing with Postman Collection Runner

Desired outcome

Run a single Postman collection request against many data rows, each row providing its own values for variables, and verify that each iteration passes its assertions.

Prerequisites

• A collection saved in Postman with requests that use double‑brace variables (e.g., {{userId}}).
• A UTF‑8 CSV or JSON file whose headers or keys exactly match those variable names.
• At least one pm.test assertion that evaluates the response (e.g., pm.test('Status is 200', () => pm.response.to.have.status(200))).
• Postman desktop app version that includes the Collection Runner (most recent releases).

Procedure

1. Open the Collection Runner. In the current UI (v2026.x) click the collection name in the sidebar and choose “Run” or use the “Runner” button in the footer.
2. Select the collection you want to test.
3. Attach the data file: click “Attach Files”, choose your CSV or JSON file, and confirm. The file must be UTF‑8 encoded; CSV needs a header row, JSON must be an array of objects.
4. The Runner automatically counts iterations from the file (one row per iteration). You can optionally set a delay in milliseconds under “Iteration Delay”.
5. Click “Start Run”. Postman will execute the collection once per data row.

Command‑line alternative (Newman)

newman run my-collection.json --iteration-data data.csv

Run this in a terminal where you have write permission to the files. Newman reads the same variable resolution rules as the UI.

Expected checks

• Iteration count in the run summary matches the number of rows in the data file.
• Open the Postman Console (View → Show Postman Console) and add console.log(pm.iterationData.get('userId')) in a script; each iteration prints the resolved value.
• Each iteration shows PASS/FAIL for every pm.test assertion in the summary.
• Export the run results via the “Export Results” button for further analysis.

Diagnostic details

To see the exact value each iteration receives, insert console.log(pm.iterationData.get('userId')) at the top of a script. The console will list the resolved value for every iteration, letting you spot mismatches quickly.

You can also use pm.test('User ID matches', () => pm.expect(pm.variables.get('userId')).to.eql(expectedId)) to create per‑iteration expectations.

Variable precedence follows the order local > data > environment > collection > global. If a data column shares a name with an environment variable, the data value wins for that iteration, which can be useful for per‑run overrides but may cause confusion if unintended. Verify by temporarily renaming the environment variable and observing the console output.

CSV vs JSON – practical comparison

CSV is ideal for flat tables; values arrive as strings, so you must convert when performing numeric checks, e.g., Number(pm.variables.get('price')). JSON supports nested objects and preserves types, allowing direct assertions like pm.test('age is number', () => pm.expect(pm.variables.get('age')).to.be.a('number')). For simple tabular test cases, CSV is quicker to set up; for complex payloads or multi‑level data, JSON reduces conversion overhead and avoids type‑casting bugs.

Common issues and recovery

• Undefined variable errors usually indicate a header/key mismatch (case‑sensitive) or missing column in CSV/JSON. Verify that the file’s first row (CSV) or top‑level keys (JSON) exactly match the variable names.
• Encoding problems (e.g., UTF‑8 with BOM) can cause silent failures; re‑save the file as plain UTF‑8 without BOM.
• If a variable defined in the environment is overridden by a data column, the data value wins for that run. To audit, temporarily set a distinct environment variable name and confirm the console output.
• Very large files (>10 000 rows) may hit version‑specific limits; check the current Postman documentation for the maximum iteration count. If you exceed the limit, split the file into smaller chunks or use a script to loop over multiple runs.

Recovery and CI considerations

Because each iteration runs in isolation, fixing a data row and re‑executing the collection is safe and fast. In CI pipelines, use Newman with the same flags:

newman run my-collection.json --iteration-data data.csv

Ensure the runner binary matches the version used for the UI run; mismatched versions can lead to different iteration counts due to internal limits. Check the official Postman docs for the current maximum row count. If you exceed the limit, split the file or run multiple collections.

Verification checklist

1. Create a minimal collection with a GET request using {{userId}}.
2. Prepare a 3‑row CSV:

   userId,expectedStatus
   1,200
   2,404
   3,500

3. Run the collection via the Runner, attach the CSV, and confirm three iterations.
4. Check the console for each resolved userId and ensure the status assertions match the expectedStatus column.
5. Run the same collection in Newman with newman run collection.json --iteration-data data.csv and verify identical results.