Your progress is only saved in this browser. to protect it and pick up on any device.

Connect a Postman API key to check your work

You do each step in Postman, then LiftOff uses your key to look at your workspace and confirm it's done. Connect once and it works for every module. Your key is saved in this browser and is only used to check your work in Postman.

0 of 3 steps0%

Now the dataset stops being a table and starts doing jobs. First it drives a collection run, then your scripts query it directly.

6

Build a Data-Driven Collection

A collection run turns each row of a dataset view into an iteration. Postman exposes every column as a variable, so your request only needs placeholders and your tests only need pm.iterationData.

  1. In your Datasets workspace, click + → Collection and name it:

    text
    Invoice Checks API
  2. Add a request and name it:

    text
    Check Invoice

    Leave the method as GET and paste this URL. Every {{...}} matches a column in the account_invoices view:

    https://postman-echo.com/get?invoiceId={{invoiceId}}&company={{company}}&amount={{amount}}
  3. Open the Scripts tab, select After response, and add:

    script.js
    pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
    });
    ​
    pm.test("Postman Echo saw this row's invoice", function () {
    const args = pm.response.json().args;
    pm.expect(args.invoiceId).to.eql(String(pm.iterationData.get("invoiceId")));
    pm.expect(args.company).to.eql(String(pm.iterationData.get("company")));
    });
  4. Save the request.

Postman Echo reflects your query string back inside args, so the second test proves that the right row reached the right request.

Expected outcome: An Invoice Checks API collection with one request that has {{invoiceId}} in the URL and tests reading pm.iterationData.

7

Run the Collection From a Dataset View

The Collection Runner can read straight from your dataset, so the data is always the current rows rather than a stale file on your desktop.

  1. Select Invoice Checks API, then click Run (to the left of Share).
  2. Choose Functional, then Local.
  3. Open the Iteration data dropdown and go to the Datasets tab. Select the billing-data dataset, then choose the account_invoices view.
  4. Leave the iteration count alone. By default Postman runs one iteration per row, which is four.
  5. Click Start run.

Expected outcome: 4 iterations, each 200 OK, 8 tests passed (2 tests × 4 rows).

Now bend the rules. Set Iterations to 6, which is more than the four rows, and see what the iteration strategy does when the rows run out:

StrategyWhat happens on iterations 5 and 6
Round robinStarts again from the first row
Repeat lastKeeps using the last row
Stop at endStops the run at row 4

Try swapping the view for invoice_summary too. The run now fails the company test, because that view has no company column. That's the point of views: they decide exactly what your run sees.

The same dataset also works with monitors, performance tests and the Postman CLI.

8

Query the Dataset From a Script

Iteration data hands your script one row at a time. pm.datasets goes further: your script can ask the dataset its own questions, at any moment, with SQL. You'll use it to check that every invoice the API handled really exists in the data.

  1. Open Check Invoice → Scripts → After response and add this below your existing tests. The dataset name in pm.datasets("") is left empty on purpose, and you'll fill it in next:

    script.js
    const ds = pm.datasets("");
    const invoiceId = String(pm.iterationData.get("invoiceId"));
    ​
    const result = await ds.executeQuery(
    "SELECT status FROM source_invoices WHERE invoiceId = ?",
    [invoiceId]
    );
    ​
    const rows = [];
    for await (const row of result.rows) {
    rows.push(row);
    }
    ​
    pm.test("Invoice " + invoiceId + " exists in the dataset", function () {
    pm.expect(rows.length).to.eql(1);
    });
  2. Click between the two quotes in pm.datasets(""). Postman lists the datasets in your workspace, so select billing-data and it fills in the dataset's ID for you. There's no need to look the ID up.

  3. Save the request and run the collection again from your account_invoices view.

executeQuery() runs SQL with ? placeholders that you fill from an array, and the rows come back on result.rows as an async iterable, which is why you read them with for await...of. If you've already saved a view, executeView() runs it without any SQL in the script.

Expected outcome: 12 tests passed across the four iterations (3 tests × 4 rows).

Troubleshooting: If no dataset is listed when you click between the quotes, check that the dataset is in the same workspace as your collection. If you see result is not async iterable, loop over result.rows, not result. If the new test fails with a dataset error, check that pm.datasets( holds the ID you selected and that the source name in your query is source_invoices. executeQuery needs a Solo, Team or Enterprise plan.

Where to go next

Nothing to do here. This is a quick map of what datasets can do beyond Cloud View.

TopicWhat to know
Local ViewWith a Git folder connected, a dataset is a .dataset.yaml file in your repo, so changes can be reviewed in pull requests.
MocksA coded mock can call pm.datasets to answer from your data. Try it in Coded Mocks with Native Git.
Git syncPulling Cloud items into Local View needs a remote repo, which is strongly advised for real projects. See Native Git in Postman.