Understanding Iterations

Key Attributes of an Iteration

• Name: Identifier for the iteration.
• HTTP Request: Configuration for the request, including the method, URL, headers, and payload.
• Mode: Defines how the iteration operates (see Iteration Modes).
• Startup Delay: Optional delay in milliseconds before starting the iteration.
• MaximizeThroughput: Set maximizeThroughput: true to push send-rate as fast as other constraints allow. Maximizing the throughput will result in higher CPU and Memory usage

Structure

• The plan is at the document root (no plan: key).
• Rounds are required; each round contains one or more iterations.
• Each iteration typically contains an httpRequest.

Iteration Features

Iteration Modes

Iteration Modes control the pattern and timing of HTTP requests, offering flexibility to simulate various user behaviors and system loads (see Iteration Modes).

SkipIf

The skipIf property allows conditional execution of an iteration. If the condition evaluates to true, the iteration will be skipped. Conditions can use Flee expressions and may reference session/global variables, placeholders, and metrics.

Example use cases:

• Skip login attempts if login failed to get a response.
• Skip requests when a certain error condition has been met.

skipIf: ${LoginResponse.StatusCode} = 401
skipIf: ${LoginResponse.Body.token} = ""
skipIf: ${Metrics.Load.Heavy.Duration.P90ResponseTime} > 250

Before Expressions

The before property runs a list of expressions before the iteration's skipIf and its request(s) — a pre-execution hook for preparing data. Each expression is evaluated in order for its side effects (typically a $find(..., variable=x) that stores a variable); the returned value is discarded.

This closes an ordering gap: skipIf/URL/headers are evaluated before a request is sent, so before lets you set up a variable and then use it in the same iteration/request. before is available at both iteration level (runs once per iteration) and httpRequest level (runs before each request).

before:
  - '$find(source=$users.Body, where=item.username == "Bret", select=item.id, match=first, variable=userId)'
skipIf: ${userId} != 1

See the Before Expressions article and the find method.

After Expressions

The after property runs a list of expressions after the iteration/request executes — a post-execution hook. Like before, each expression is evaluated in order for its side effects (typically a $find(..., variable=x) that stores a variable); the returned value is discarded.

Because it runs after execution, after can read the response and captured variables and prepare data for the next step. It is available at both iteration level (runs once when the iteration completes) and httpRequest level (runs after each request completes). Request-level after runs on both success and failure, but not when skipIf skipped the request or on cancellation.

after:
  - '$find(source=$users.Body, where=item.id > 5, match=count, variable=bigUserCount)'
  - '$greaterthan(a=${bigUserCount}, b=3, variable=hasManyUsers)'

See the before & after Expressions article.

Failure Rules

The failureRules property defines rules that are applied after the iteration finishes. These rules classify the outcome of the iteration as either Failed or Success. This is useful for reporting and post-run analysis.

Each rule can use either:

• metric: an inline metric expression
• expression: a Flee boolean expression
• both together in the same rule

If expression evaluates to true, the rule triggers immediately and independently of metric.

failureRules:
  - metric: "ErrorRate > 0.10"
    errorStatusCodes: ">= 500"
  - expression: '${Metrics.CheckoutRound.Pay.Throughput.RPS} < 50'
  - metric: "TotalTime.P90 > 250"
    expression: '${Metrics.CheckoutRound.Pay.ResponseCode.ResponseSummaries[0].Count} > 25'
  - metric: "TotalTime.P50 > 200"
  - metric: "TotalTime.Avg > 180"

CLI Usage

lps --url https://example.com -rc 1000 --failurerule "ErrorRate > 0.05;>= 500" --failurerule "TotalTime.P90 > 250"

Format: "metric[;errorStatusCodes]"

Termination Rules

The terminationRules property lets you define real-time termination conditions for an iteration. These rules are evaluated continuously by the Master node (aggregating all workers). An iteration will be terminated only if a rule is continuously violated for the entire grace period. For example, with a grace period of 10 seconds, if the violation clears before the 10th second, the test continues without termination.

Each rule can use either:

• metric: an inline metric expression
• expression: a Flee boolean expression
• both together in the same rule

If expression evaluates to true, termination happens immediately and independently of metric or gracePeriod.

When metric is used, gracePeriod controls how long the metric condition must stay violated before the iteration is terminated.

terminationRules:
  - metric: "ErrorRate > 0.2"
    errorStatusCodes: ">= 500"
    gracePeriod: "00:00:10"
  - expression: '${Metrics.SearchRound.Results.Throughput.RPS} <= 40'
  - metric: "TotalTime.P90 > 200"
    gracePeriod: "00:00:05"
    expression: '${Metrics.SearchRound.Results.ResponseCode.ResponseSummaries[0].Count} > 50'
  - metric: "TotalTime.P50 > 400"
    gracePeriod: "00:00:15"

CLI Usage

lps --url https://example.com -rc 1000 --terminationrule "ErrorRate > 0.10;00:05:00;>= 500" --terminationrule "TotalTime.P90 > 500;00:00:30"

Format: "metric;gracePeriod[;errorStatusCodes]"

Metric Expression Reference

Both failureRules and terminationRules support expression for general boolean conditions, and metric for inline metric expressions. The metric format below applies to the metric property.

Expression Format

MetricName[.Statistic] Operator Threshold

Supported Metrics

SkipRatio formula: skipped / (executed + skipped)

SkippedRequestsCount is also supported as a scalar metric in rule expressions such as "SkippedRequestsCount > 25". It does not support aggregations like .P95.

Supported Operators

Error Status Code Filtering

The optional errorStatusCodes property filters which HTTP status codes count as errors when calculating ErrorRate.

Complete Iteration Example

name: IterationFeaturesPlan # Represents the plan name
rounds:
  - name: FeatureRound
    numberOfClients: 50
    arrivalDelay: 100
    runInParallel: false
    iterations:
      - name: LoginIteration
        httpRequest:
          url: https://httpbin.org/post
          method: POST
          headers:
            Content-Type: application/json
          payload:             
            raw: |
                { "username": "user", "password": "pass" }
      - name: Home
        httpRequest:
          url: https://httpbin.org/
          httpMethod: Get

        # SkipIf (iteration)
        skipIf: ${LoginResponse.StatusCode} = 401

        # Failure Rules (evaluated once the iteration execution is completed)
        failureRules:
          - metric: "ErrorRate > 0.10"
            errorStatusCodes: ">= 400"
          - expression: '${Metrics.FeatureRound.Home.Throughput.RPSCD} < 10'
          - metric: "SkipRatio > 0.15"
          - metric: "TotalTime.P90 > 250"
          - metric: "TotalTime.P50 > 200"
          - metric: "TotalTime.Avg > 180"

        # Termination Rules (evaluated in real-time during execution)
        terminationRules:
          - metric: "ErrorRate > 0.2"
            errorStatusCodes: ">= 400"
            gracePeriod: "00:00:03"
          - expression: '${Metrics.FeatureRound.Home.Throughput.RPS} <= 40'
          - metric: "TotalTime.P90 > 2000"
            gracePeriod: "00:00:05"

Global Iterations and References

Iterations can also be defined as global iterations and referenced later within rounds using the reference property. This allows for reusable iteration configurations across multiple rounds, reducing redundancy and improving maintainability.

name: GlobalIterationPlan
iterations:
- name: GlobalIteration
  mode: DCB
  duration: 300
  batchSize: 100
  coolDownTime: 1000
  httpRequest:
    url: https://httpbin.org/headers
    httpMethod: GET
    httpVersion: 2.0
rounds:
- name: TestRound
  numberOfClients: 1
  reference: ["GlobalIteration"]