Run order and flow control in Postman - Deep Dive

Overview - Run order and flow control

What is it?

Run order and flow control in Postman means deciding the sequence in which your API requests run and how to manage their execution based on conditions. It helps you organize tests so some requests run before or after others, or only if certain conditions are met. This makes your testing efficient and logical, especially when requests depend on each other.

Why it matters

Without run order and flow control, tests might run randomly or all at once, causing failures or confusing results. You could waste time debugging issues caused by requests running too early or too late. Proper flow control ensures tests run in the right sequence, making your testing reliable and easier to understand.

Where it fits

Before learning run order and flow control, you should know how to create basic requests and write simple tests in Postman. After mastering this, you can explore advanced scripting, environment variables, and automation with Postman Collections and monitors.

Mental Model

Core Idea

Run order and flow control in Postman organize your API tests like a well-planned recipe, ensuring each step happens at the right time and only when needed.

Think of it like...

Imagine cooking a meal where you must prepare ingredients in order: you can't bake a cake before mixing the batter. Run order and flow control are like following the recipe steps carefully, so the meal turns out perfect.

┌───────────────┐
│ Start Runner  │
└──────┬────────┘
       │
┌──────▼───────┐
│ Request 1    │
│ (Pre-request)│
└──────┬───────┘
       │
┌──────▼───────┐
│ Test Script  │
│ (Check &     │
│  Decide Next)│
└──────┬───────┘
       │
┌──────▼───────┐
│ Conditional  │
│ Flow Control │
└──────┬───────┘
       │
┌──────▼───────┐
│ Request 2 or │
│ End Runner   │
└──────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Postman Request Sequence

Concept: Learn how Postman runs requests in the order they appear in a collection by default.

In Postman, when you run a collection, requests execute one after another from top to bottom. This default sequence means Request 1 runs first, then Request 2, and so on. You can reorder requests in the collection to change this sequence.

Result

Requests run in the order you arranged them, ensuring predictable execution.

Knowing that Postman runs requests sequentially by default helps you plan your tests logically and avoid unexpected behaviors.

2

Foundation

Using Pre-request and Test Scripts

Concept: Discover how scripts before and after requests control what happens during the run.

Each request in Postman can have a pre-request script that runs before the request and a test script that runs after. Pre-request scripts can set variables or prepare data. Test scripts check responses and can decide what to do next.

Result

Scripts allow dynamic control and validation during the test run.

Understanding scripts lets you customize each request's behavior and prepare for flow control.

3

Intermediate

Controlling Flow with Postman.setNextRequest()

🤔Before reading on: do you think Postman runs all requests no matter what, or can you skip some? Commit to your answer.

Concept: Learn how to use setNextRequest() to jump to a specific request or stop the run.

Postman provides a function called pm.setNextRequest('RequestName') inside test scripts. This tells Postman which request to run next, overriding the default order. If you pass null, the run stops immediately. This lets you skip requests or loop back.

Result

You can change the run order dynamically based on test results or conditions.

Knowing setNextRequest() lets you build flexible test flows that react to API responses, making tests smarter and more efficient.

4

Intermediate

Conditional Execution Based on Test Results

🤔Before reading on: can you make Postman run a request only if a previous test passed? Commit to yes or no.

Concept: Use test script logic to decide if the next request should run or the run should stop.

Inside test scripts, you can write JavaScript conditions. For example, if a response status is 200, you call pm.setNextRequest('NextRequest'). Otherwise, you call pm.setNextRequest(null) to stop. This way, you control flow based on success or failure.

Result

Tests run only when conditions are met, preventing wasted requests and clearer results.

Conditional flow control helps you build robust test suites that handle errors gracefully and avoid cascading failures.

5

Advanced

Looping and Repeating Requests in Runs

🤔Before reading on: do you think Postman can repeat a request multiple times automatically? Commit to yes or no.

Concept: Use setNextRequest() to create loops by directing Postman back to earlier requests.

By calling pm.setNextRequest('RequestName') with the name of a previous request, you can make Postman repeat that request. You can combine this with variables to limit loops, like counting iterations and stopping after a number.

Result

You can automate repeated tests, like retrying until success or testing multiple data sets.

Looping expands Postman's power to simulate real-world scenarios like retries or batch processing.

6

Expert

Managing Complex Flows with Multiple Conditions

🤔Before reading on: can you design a flow that chooses among several next requests based on different response codes? Commit to yes or no.

Concept: Combine multiple conditions and setNextRequest() calls to build branching flows like decision trees.

In test scripts, use if-else or switch statements to check response data or status codes. Depending on the result, call pm.setNextRequest() with different request names. This creates complex flows that adapt to many scenarios in one run.

Result

Your test runs behave like a smart program, handling many cases without manual intervention.

Mastering complex flow control lets you automate realistic API workflows and catch subtle bugs that simple linear tests miss.

Under the Hood

Postman runs collections by executing requests sequentially unless overridden. When a request finishes, Postman checks if pm.setNextRequest() was called. If yes, it jumps to that request by name; if null, it stops. This happens inside the Postman runtime environment, which interprets your scripts and manages the request queue dynamically.

Why designed this way?

Postman was designed to be simple for beginners with default sequential runs but flexible for experts via scripting. The setNextRequest() method provides a controlled way to alter flow without complex configuration, balancing ease of use and power.

┌─────────────┐
│ Start Run   │
└──────┬──────┘
       │
┌──────▼──────┐
│ Request N   │
│ Executes    │
└──────┬──────┘
       │
┌──────▼─────────────┐
│ Check pm.setNextRequest() │
└──────┬─────────────┘
       │
  ┌────▼─────┐      ┌──────▼─────┐
  │ Next Req │      │ Stop Run   │
  └──────────┘      └───────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Postman always run all requests in a collection regardless of test results? Commit to yes or no.

Common Belief: Postman runs every request in the collection no matter what happens in tests.

Reality: Postman can skip requests or stop running based on pm.setNextRequest() calls in test scripts.

Why it matters: Believing all requests always run leads to wasted time and confusing test failures when you expect conditional skipping.

Quick: Can you use pm.setNextRequest() outside test scripts? Commit to yes or no.

Common Belief: You can call pm.setNextRequest() anywhere, like in pre-request scripts or global scripts.

Reality: pm.setNextRequest() only works inside test scripts after a request runs, not in pre-request scripts or collection-level scripts.

Why it matters: Trying to control flow in the wrong script causes no effect, leading to frustration and broken test flows.

Quick: Does calling pm.setNextRequest(null) restart the collection run? Commit to yes or no.

Common Belief: Setting pm.setNextRequest(null) restarts the collection from the beginning.

Reality: pm.setNextRequest(null) stops the collection run immediately; it does not restart it.

Why it matters: Misunderstanding this causes unexpected test stops and confusion about test coverage.

Quick: Can you rely on request order in the collection UI to control flow if you use pm.setNextRequest()? Commit to yes or no.

Common Belief: The order of requests in the collection always controls the run order, even if you use pm.setNextRequest().

Reality: pm.setNextRequest() overrides the collection order, so the UI order is ignored when flow control is active.

Why it matters: Ignoring this leads to unexpected request execution and hard-to-debug test failures.

Expert Zone

1

pm.setNextRequest() only accepts the exact name of a request; typos cause silent failures where the run stops unexpectedly.

2

Using pm.setNextRequest() inside asynchronous code or callbacks can cause timing issues because Postman executes scripts synchronously.

3

When looping with pm.setNextRequest(), you must manage loop counters manually using variables to avoid infinite loops that hang the runner.

When NOT to use

Avoid complex flow control with pm.setNextRequest() when your tests are simple linear sequences; use the default order instead. For very complex workflows, consider external orchestration tools or Postman monitors with separate collections to keep tests maintainable.

Production Patterns

In real projects, teams use pm.setNextRequest() to skip tests if authentication fails, loop over data-driven tests by repeating requests with different inputs, and branch flows to test error handling paths. They combine this with environment variables and collection variables for flexible, reusable test suites.

Connections

State Machines

Run order and flow control in Postman behave like state machines where each request is a state and pm.setNextRequest() defines transitions.

Understanding Postman flow as a state machine helps design predictable and testable API workflows with clear transitions.

Conditional Logic in Programming

Postman flow control uses conditional statements similar to if-else in programming to decide next steps.

Knowing basic programming conditionals makes writing Postman test scripts intuitive and powerful for flow control.

Project Management Workflows

Just like tasks in a project depend on others and have conditional paths, Postman requests depend on previous results and control flow accordingly.

Seeing Postman runs as workflows clarifies why order and conditions matter, similar to managing project tasks.

Common Pitfalls

#1 Stopping the run unintentionally by calling pm.setNextRequest(null) too early.

Wrong approach:

pm.test('Stop run', function() {
pm.setNextRequest(null);
});

Correct approach:

pm.test('Conditional stop', function() {
if (pm.response.code !== 200) {
pm.setNextRequest(null);
}
});

Root cause:

Misunderstanding that pm.setNextRequest(null) stops the entire run immediately without conditions.

#2 Using pm.setNextRequest() with a wrong request name causing silent failures.

Wrong approach:

pm.setNextRequest('Reqest 2'); // typo in request name

Correct approach:

pm.setNextRequest('Request 2'); // exact request name

Root cause:

Not verifying exact request names leads to unexpected stops because Postman can't find the target request.

#3 Trying to control flow in pre-request scripts where pm.setNextRequest() has no effect.

Wrong approach:

pm.setNextRequest('Next Request'); // inside pre-request script

Correct approach:

// Move this code to test script
pm.setNextRequest('Next Request');

Root cause:

Confusing script types and their capabilities causes flow control code to be ignored.

Key Takeaways

Postman runs requests in collection order by default but allows dynamic control with pm.setNextRequest() in test scripts.

Flow control lets you skip, repeat, or branch requests based on test results, making tests smarter and more efficient.

Scripts before and after requests prepare data and decide the next steps, enabling conditional execution.

Misusing pm.setNextRequest() or misunderstanding its scope causes silent failures or unexpected stops.

Mastering run order and flow control unlocks powerful, realistic API testing workflows that catch complex bugs.