Using environments in collection runs

Environments enables you to create robust requests that you can reuse. For more information about using variables and environments, see Variables. You also can use environments in the Collection Runner.

Let’s look at an example collection with one POST request that uses environment variables in its URL, body, and test script.

Getting started

Downloading sample file

To begin, download the sample collection.

Importing sample file

To import the sample in Postman, click the Import button in the header bar. In the IMPORT modal, select the sample JSON file to upload it.

import sample

The sample file displays in Postman as postman-echo.com/ in the sidebar.

sample collection

The test expects the value of foo in the response body to be equal to bar. Let us also assume that after some computation, we’re resetting the value of this variable to bar2.

set environment variable 

Running the sample collection

Downloading the sample environment

To run this collection correctly in the Collection Runner, you must supply the corresponding environment.

Download the sample environment JSON file.

Configuring the Collection Runner

In the Collection Runner, select the test environment from the environment dropdown on the left and run the collection. You’ll see the tests pass.

collection runner parameters  

If you switch back to the main Postman app window and check the value of the variable foo, you’ll see that it is now bar2.

By default, any variable changes in the environment (or globals) in the Collection Runner shows in the main Postman app window because Persist Variables is checked in the options. If you run the collection once again, you’ll see that it now fails, since we changed the value of the variable foo.

collection runner results

By default, Keep variable values is checked the first time you open the Collection Runner. If you do not want variables to be updated during the run, deselect the Keep variable values checkbox.

In this case, think of it as the Collection Runner saving the initial state of the environment (and globals), and restoring it after the run is complete. This action is useful when you reuse the same variables in your requests and want to run the same collection multiple times. It ensures the environment (and globals) state is not affected by a collection run.

keep variables

When you run a collection, Postman takes a layered approach in updating your current and initial values to protect your data. There are two options – ‘Keep variable values’ and ‘Automatically persist variable values’ that work in tandem with your variables to keep them the way you want. The behavior of these variables depends a lot on the way you set these two options in your settings. For a general understanding of inter-dependency of these settings, you may refer to the following flow chart.

keep vars

After running your collection, Postman first checks the setting ‘Keep variable values’. If it is off, it will not make any change to the variable values. If it is on Postman updates your current values. Once Postman updates the current values, it will still check if Auto-Persist is on/off. If this option is off, Postman will not persist the current value to the initial value. If this option is ‘on’, it will update the initial values.

For more information about collection runs, see: