How do you do data-driven testing with the Postman Collection Runner?

How it works

The Collection Runner (or Newman) accepts one data file per run. Each row of a CSV, or each object in a JSON array, is an iteration: the whole collection or selected folder runs once per row. Column names become data-scope variables, which override environment and collection variables of the same name.

users.csv:

caseName,email,password,expectedStatus,expectedError
valid user,qa1@example.com,Str0ng!Pass,201,
missing email,,Str0ng!Pass,400,email is required
weak password,qa2@example.com,123,400,password too short
duplicate,existing@example.com,Str0ng!Pass,409,email already registered

Request body:

{
  "email": "{{email}}",
  "password": "{{password}}"
}

Post-response script:

const expectedStatus = Number(pm.iterationData.get("expectedStatus"));
const caseName = pm.iterationData.get("caseName");

pm.test(`${caseName}: status ${expectedStatus}`, () => {
  pm.response.to.have.status(expectedStatus);
});

const expectedError = pm.iterationData.get("expectedError");
if (expectedError) {
  pm.test(`${caseName}: error message`, () => {
    pm.expect(pm.response.json().message).to.include(expectedError);
  });
}

Putting the case name in the test title makes failures readable in the run results and Newman reports, where otherwise you only see “iteration 3 failed”.

CSV vs JSON

• CSV is easy for non-developers to edit, but every value is a string, so convert numbers and booleans in scripts (Number(...)), and there is no nesting.
• JSON keeps types and supports nested objects, which helps for complex payloads:

[
  { "caseName": "valid", "payload": { "qty": 2, "giftWrap": true }, "expectedStatus": 201 },
  { "caseName": "zero qty", "payload": { "qty": 0 }, "expectedStatus": 422 }
]

For an object value, build the body in a pre-request script with pm.variables.set("body", JSON.stringify(pm.iterationData.get("payload"))) and use {{body}} as the raw body.

Running it

In the app: Runner, select the collection or folder, choose the data file, check the iteration count. From the command line:

newman run collection.json -e staging.postman_environment.json -d users.csv

Practical tips

• One data file applies to everything in the run, so put data-driven requests in their own folder and run that folder (--folder in Newman). Otherwise unrelated requests also repeat for every row.
• Make data independent: unique emails per run (a timestamp suffix) or clean-up requests, so a rerun does not fail with 409.
• Keep data files in version control next to the exported collection.
• Many rows of fine-grained validation might be better as unit tests in the service; use Postman data runs for API-level boundary and negative cases.

What interviewers look for

• Knowing each row is an iteration and how values are referenced in requests and scripts.
• Including expected outcomes in data so negative cases are covered.
• Practical handling of CSV string types and running a single folder.
• Keeping data-driven runs repeatable.