Datasets and data files

Test data drives data-driven runs: the collection runner runs once per row, and each column becomes a variable your requests and scripts can read. You can keep that data in two ways. A dataset is a table you edit in the app and save in the workspace, so it travels with your collections through Git. A data file is any CSV or JSON file on disk that you pick for one run.

12345

A dataset is a table of test data. Each row is one iteration of a run.

1. Replace the table with the contents of a CSV or JSON file
2. Open the runner for a collection with this dataset selected
3. Column menu: insert a column before this one, or delete it
4. Add a column at the end
5. Add a row

×

Create a dataset

1. Click Datasets in the API client’s left rail.

2. Click + at the top of the sidebar.

   A dataset named New Dataset opens with a few sample columns and rows to start from. If that name is taken, the new one is called New Dataset 2, New Dataset 3, and so on.

3. Click the name at the top and type a new one, for example Pet logins.

4. Rename the columns by clicking a column header and typing. Column names become variable names, so use names like username or petId.

5. Click a cell to edit it. Use Add Row for more rows.

Changes save automatically, like everything else in the workspace. You can also create a dataset from the runner’s Choose menu with New Dataset.

Edit a dataset

Control	What it does
Dataset name	The name shown in the sidebar, the runner and cloakctl. It’s also the file name in the workspace.
Column header	Click and type to rename the column.
Column menu (chevron)	Insert Column Before adds an empty column to the left. Delete Column removes the column and its values.
+ after the last column	Adds a column at the end, named column1, column2 and so on.
Row number and minus button	The minus button deletes that row.
Cells	Plain text. Values can contain {{variables}}, including {{vault:name}} secrets.
Add Row	Adds an empty row at the bottom.
Footer	The number of rows and columns.

To delete a whole dataset, right-click it in the sidebar and choose Delete. It goes to Recently Deleted for 30 days. Use Filter at the top of the sidebar to find a dataset by name.

Keep real passwords out of the table

Datasets are saved as plain CSV in the workspace and are usually committed to Git. Put secrets in the Vault and reference them in a cell as {{vault:ada_password}}. The runner fills them in when it sends the request.

Import and export

• Import CSV or JSON… replaces the dataset’s columns and rows with the contents of a file. A CSV file keeps its column order. For a JSON file, columns are added in alphabetical order of each object’s keys, as they first appear. See Data file formats.
• Export CSV… saves the table as Dataset name.csv, with values quoted where needed.

Run a collection with a dataset

1. Open the dataset and choose Run With… › the collection.

   The runner opens with the dataset already selected.

   Or, in an open runner, choose Choose › the dataset (each one is listed with its row count).

2. Check that the runner shows Data: Dataset name (N rows).

   Iterations is disabled, because the run makes one iteration per row.

3. Click Run.

12

With a dataset selected, the runner makes one iteration per row.

1. The selected dataset and its row count
2. Remove clears the data and turns Iterations back on

×

The runner reads the dataset when the run starts, so edits you make apply to the next run. If you delete a dataset that a runner had selected, the runner shows Data: dataset deleted.

Use a data file instead

A data file is a CSV or JSON file that isn’t stored in the workspace. Use it for one-off data, or for data generated by another tool.

1. In the runner, choose Choose › Data File (CSV or JSON)….

2. Pick a .csv, .json or plain text file.

   The runner shows Data: file name (N rows).

3. Click Run.

If the file can’t be read, Cloak Proxy shows Couldn’t read the data file: and the reason. To turn the file into a dataset you can edit, create a dataset and use Import CSV or JSON….

Data file formats

CSV

logins.csv

username,password,petId,expectedStatus
ada,{{vault:ada_password}},1,200
mallory,wrong,3,401
"Park, Ada","say ""hi""",42,404

• The first line holds the column names. Each following line is one row.
• The separator is detected from the first line: comma, semicolon or tab, whichever appears most. (Datasets saved in the workspace always use commas.)
• Quoted fields follow RFC 4180: wrap a value in double quotes to include the separator or a line break, and write a quote inside a quoted value as two quotes ("").
• Blank lines are skipped. A row with fewer values than columns gets empty values for the rest. Columns with an empty name are ignored.
• A UTF-8 byte order mark at the start is removed.

JSON

logins.json

[
  { "username": "ada", "password": "{{vault:ada_password}}", "petId": 1, "expectedStatus": 200 },
  { "username": "mallory", "password": "wrong", "petId": 3, "expectedStatus": 401 }
]

• The file must be an array of objects. Each object is one row; its keys are the column names.
• String values are used as they are. Numbers, true, false and null become their JSON text (1, true). Nested objects and arrays become compact JSON text.
• A file is read as JSON when its extension is .json or its text starts with [.
• Errors: A JSON data file must be an array of objects and Every item in the JSON data file must be an object.

Use the values in requests and scripts

During each iteration, the row’s columns are variables in the data scope:

Where	How
URL, params, headers, body, auth	{{username}}, {{petId}}
Scripts	pm.iterationData.get("expectedStatus")
Any variable lookup	pm.variables.get("username") resolves data values too

Data values override environment, collection and global variables with the same name. A value a script sets locally still wins. See Variables and environments for the full order.

Post-response script

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

pm.test(`Status is ${expected}`, () => {
  pm.response.to.have.status(expected);
});

Every value arrives as text, so convert numbers with Number() before comparing them.

Run with data from the command line

cloakctl collection run takes a data file path or a dataset name with -d (or --iteration-data):

Terminal

# A dataset in the workspace, by name (not case-sensitive)
cloakctl collection run "Petstore" -d "Pet logins"

# A CSV or JSON file
cloakctl collection run "Petstore" -d ./data/logins.csv

If the path doesn’t exist and no dataset has that name, cloakctl lists the datasets in the workspace. See Collection runner for every flag.

Where datasets are stored

Each dataset is a CSV file in the workspace’s datasets folder, named after the dataset. Because it’s plain CSV, a change to one cell is a one-line diff in Git.

• DirectoryWorkspace/

  • cloak-workspace.json
  • Directorycollections/

    • …
  • Directoryenvironments/

    • …
  • Directorydatasets/

    • Pet logins.csv

See Workspace and Git for the whole folder layout.

Related

Collection runnerIterations, order, delays and reports.

Variables and environmentsScopes, precedence and the Vault.

Scripts and testsRead iteration data in tests.

Workspace and GitHow datasets are saved and shared.