LPS Methods Reference

This reference documents every built‑in LPS method, its arguments, return value, side‑effects, and usage examples. All methods can be used either:

As variable initializers (value resolved once and stored), or
Inline inside URLs/bodies/headers.

Common argument: Most methods support an optional variable argument. When you call a method inline, setting variable=<name> also stores the computed value into a variable with that name for later reuse.

Common argument — isGlobal: Every method that stores a variable also accepts isGlobal, which controls the scope of the stored variable. It defaults to false — the variable is scoped to the current session, so parallel virtual clients do not share or overwrite each other's value (the same scoping used by capture and counter). Set isGlobal=true to store the variable globally, shared across all sessions.
- '$setvariable(variable=cartId, value=${guid()})'          # per-session (default)
- '$setvariable(variable=region, value=us-east, isGlobal=true)'   # shared globally

Common argument — as (typed storage): A stored variable is a string by default. Add as to store it as another type — int, double, decimal, bool, or json. What's substituted inline is always text; as only changes the stored variable, so later you can do math with it, test it as a boolean, or navigate JSON (${roles[0]}).
- '$jwtclaim(token=${jwt}, claim=exp, as=int, variable=exp)'   # store a number
- '$read(source=env, name=RETRIES, as=int, variable=retries)' # store a number
It works on any method whose stored value can vary in type — find, findxml, read, readif, setvariable, jwtclaim, and the math methods (sum/min/avg/… as int/double/decimal). Default is string; find, findxml and readif default to auto (they infer the type). Fixed-type methods take no as and store their natural type: length, randomnumber, counter → int; the contains / startswith / equal / greaterthan / … predicates → bool (rendered lowercase true/false).

random
randomnumber
length
randomItem
timestamp / datetime
guid
uuid
base64encode
base64decode
urlencode
urldecode
hash
hmac
format
generateemail
jwtclaim
jwtsign
read
readif
counter
tolowercase
touppercase
contains
startswith
endswith
strcat
find
findxml
setvariable / set
setvariableif / setif
sum
min
max
multiply
average / avg
divide
subtract
mod
pow
abs
floor
ceil
round
clamp
greaterthan
smallerthan
greaterthanorequal
smallerthanorequal
greater
less
equal
stringequals

`random`

Description
Generates a random alphanumeric string (A–Z, a–z, 0–9).

Parameters

length (int, optional, default: 10) – Number of characters to generate.
variable (string, optional) – If provided, the generated value is also stored under this variable name.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – A random string of the requested length.

Side‑effects – If variable is provided, the result is stored to that variable (useful when called inline).

Example – as variable

variables:
- name: randomUserSuffix
  value: $random(length=12)

Example – inline while storing for reuse

httpRequest:
  url: "https://api.example.com/users?suffix=$random(length=6, variable=rand6)"
# later in the same run
  headers:
    X-User-Suffix: "${rand6}"

`randomnumber`

Description
Generates a random integer within the inclusive range [min, max].

Parameters

min (int, optional, default: 1) – Minimum value (inclusive).
max (int, optional, default: 100) – Maximum value (inclusive).
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – A string containing the integer value.

Example

variables:
- name: port
  value: $randomnumber(min=20000, max=30000)

`length`

Description
Returns the number of items in a resolved JSON array.

Parameters

source (string, optional) – Source expression to resolve first.
positional source (string, optional) – You can also pass the source as the first unnamed argument.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – A string containing the array length. Returns 0 when the resolved value is empty or is not a JSON array.

Side‑effects – Stores to variable when provided.

Example – inline against captured response

httpRequest:
  capture:
    to: users
    as: Json
  url: https://jsonplaceholder.typicode.com/users
  method: GET

skipIf: $length($users.Body) = 0

Example – positional argument

variables:
- name: usersCount
  value: $length($users.Body)

Example – store and reuse

variables:
- name: usersCount
  value: $length(source=$users.Body, variable=usersCount)

`randomItem`

Description
Returns one random item from a resolved JSON array.

Parameters

source (string, optional) – Source expression to resolve first.
positional source (string, optional) – You can also pass the source as the first unnamed argument.
variable (string, optional) – Also store the selected item to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The selected array item serialized as compact JSON. Returns empty string when the resolved value is empty, not a JSON array, or the array is empty.

Side‑effects – Stores to variable when provided.

Example – inline usage

variables:
- name: anyUser
  value: $randomItem($users.Body)

Example – store selected item for later access

variables:
- name: selectedUser
  value: $randomItem(source=$users.Body, variable=randomUser)

httpRequest:
  url: https://example.com/profile/${randomUser.id}
  httpMethod: Get

`timestamp` / `datetime`

Description
Returns the current UTC time plus an optional hour offset, formatted using a .NET date/time format string.

datetime is an alias of timestamp.

Parameters

format (string, optional, default: yyyy-MM-ddTHH:mm:ss) – .NET format, e.g., yyyy-MM-dd, HH:mm:ss, etc.
offsetHours (int, optional, default: 0) – Hours to add to UTC (can be negative).
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – A formatted date/time string.

Example

variables:
- name: todayKSA
  value: $timestamp(format=yyyy-MM-dd, offsetHours=3)

`guid`

Description
Generates a new GUID (e.g., 550e8400-e29b-41d4-a716-446655440000).

Parameters

variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The GUID string.

Example

variables:
- name: correlationId
  value: $guid()

`uuid`

Description
Generates a new UUID/GUID, with an optional prefix prepended to the value.

Parameters

prefix (string, optional, default: empty) – String to prepend to the UUID.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The (possibly prefixed) UUID string.

Example

variables:
- name: orderId
  value: $uuid(prefix=order-)

`base64encode`

Description
Encodes the provided UTF‑8 string to Base64.

Parameters

value (string, required) – Plain text to encode.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – Base64 string. Empty string if value is empty or not provided.

Example

variables:
- name: basicAuthToken
  value: $base64encode(value=user:pass)

`base64decode`

Description
Decodes a Base64 string to UTF‑8 text. Handles missing padding internally.

Parameters

value (string, required) – Base64 text to decode.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – Decoded UTF‑8 string. Empty string on invalid input or if value is empty.

Example

variables:
- name: plain
  value: $base64decode(value=SGVsbG8=)

`urlencode`

Description
Percent‑encodes a string for safe use in URLs (RFC 3986 semantics via Uri.EscapeDataString).

Parameters

value (string, required) – Text to encode.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – URL‑encoded string. Empty string if value is empty.

Example

variables:
- name: safeQuery
  value: $urlencode(value=Hello World!)

`urldecode`

Description
Decodes a percent‑encoded string (via Uri.UnescapeDataString).

Parameters

value (string, required) – Text to decode.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – Decoded string. Empty string if value is empty.

Example

variables:
- name: plainQuery
  value: $urldecode(value=Hello%20World%21)

`hash`

Description
Computes a hex‑encoded hash of the input (lowercase) using the selected algorithm.

Parameters

value (string, required) – Text to hash (UTF‑8).
algorithm (string, optional, default: SHA256) – One of MD5, SHA1, SHA256, SHA384, SHA512 (case‑insensitive).
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – Lowercase hex string of the hash. Empty string if an unsupported algorithm is specified.

Example

variables:
- name: pwdSha512
  value: $hash(value=MyPassword, algorithm=SHA512)

`hmac`

Description
Computes a keyed HMAC (hash‑based message authentication code) of a value using a shared secret. Same shape as hash, but the digest proves possession of the secret — the basis for webhook signatures (Stripe, Shopify, GitHub, …).

Parameters

value (string, required) – The payload/string to sign (UTF‑8).
key (string, required) – The shared secret (UTF‑8).
algorithm (string, optional, default: SHA256) – One of SHA1, SHA256, SHA384, SHA512 (case‑insensitive).
encoding (string, optional, default: hex) – Output encoding: hex (lowercase) or base64 (many webhook schemes expect base64).
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The HMAC digest as lowercase hex or base64. Empty string when key is missing or the algorithm is unsupported.

Side‑effects – Stores to variable when provided.

Example – webhook signature header

before:
  - '$hmac(value=${requestBody}, key=${webhookSecret}, algorithm=SHA256, encoding=base64, variable=signature)'
httpRequest:
  headers:
    X-Signature: '${signature}'

`format`

Description
Formats a text template using the .NET string.Format, then resolves any nested placeholders inside the result.

Parameters

template (string, required) – Format string with placeholders {0}, {1}, etc.
args (string, required) – Comma‑separated list of values used to fill {0}, {1}, …
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The formatted string after placeholder resolution.

Example

variables:
- name: welcome
  value: $format(template="User {0} has ID {1}", args=Alice,12345)

Example – nested placeholder resolution

variables:
- name: id
  value: 42
- name: msg
  value: $format(template="ID is {0}", args=${id})
# result: "ID is 42"

`strcat`

Description
Joins one or more values into a single string. Values are placeholder‑resolved first, then joined with an optional separator. Simpler than format when you only need to glue pieces together and don't need positional {0}/{1} templating.

Parameters

values (string, required) – The values to join. A bracketed list [a, b, c] is split on commas and each element is concatenated in order; any other value is treated as a single item. Elements and the separator may be wrapped in double quotes to preserve surrounding spaces.
separator (string, optional, default: empty) – Text inserted between elements. Wrap in double quotes to keep leading/trailing spaces (e.g. separator=" ").
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The concatenated string.

Side‑effects – Stores to variable when provided.

Example – build a URL path

variables:
- name: userId
  value: 42
- name: userUrl
  value: $strcat(values=[https://api.example.com/users/, ${userId}])
# result: "https://api.example.com/users/42"

Example – join with a separator

variables:
- name: fullName
  value: $strcat(values=[${firstName}, ${lastName}], separator=" ")
# result: "Sara Ali"

`generateemail`

Description
Generates a unique email using the given prefix and domain (adds an 8‑char unique suffix).

Parameters

prefix (string, optional, default: user) – Email local part prefix.
domain (string, optional, default: example.com) – Email domain.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – A unique email like tester-1a2b3c4d@myapp.com.

Example

variables:
- name: testEmail
  value: $generateemail(prefix=tester, domain=myapp.com)

`jwtclaim`

Description
Extracts a claim from a JWT payload. No signature verification is performed (use only in trusted test contexts).

Parameters

token (string, required) – The JWT string (header.payload.signature).
claim (string, required) – Claim key to extract (e.g., sub, aud, exp).
as (string, optional, default: string) – Type for the stored variable: string (default), int, double/float/number, decimal, bool, or json. A JWT claim can be a number (exp), boolean (email_verified), or object/array (roles) — use as to store it typed (e.g. as=json to path‑navigate a roles array). The inline return stays text.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The claim value as a string, or empty string if token/claim is missing or invalid.

Side‑effects – Stores to variable when provided.

Example

variables:
- name: userId
  value: $jwtclaim(token=${authToken}, claim=sub)

Example — typed claims

before:
  - '$jwtclaim(token=${authToken}, claim=exp, as=int, variable=exp)'             # numeric, comparable
  - '$jwtclaim(token=${authToken}, claim=email_verified, as=bool, variable=verified)'
  - '$jwtclaim(token=${authToken}, claim=roles, as=json, variable=roles)'        # ${roles[0]} = first role

`jwtsign`

Description
Builds and signs a compact JWT (header.payload.signature) — the write‑side counterpart of jwtclaim. Supports symmetric HS256/HS384/HS512 (an inline shared secret) and asymmetric RS256/RS384/RS512 and ES256/ES384/ES512 (a PEM private key). iat is added automatically, and exp is derived from expiresIn — without overriding any claim you set explicitly.

Parameters

claims (json, required) – A JSON object of claims, e.g. {"sub":"${clientId}","aud":"${tokenUrl}"}. Placeholders inside are resolved first.
algorithm (string, optional, default: HS256) – One of HS256/HS384/HS512 (HMAC), RS256/RS384/RS512 (RSA PKCS#1 v1.5), or ES256/ES384/ES512 (ECDSA, raw IEEE P1363 signature).
key (string) – The signing key inline: the shared secret for HS*, or a PEM private key for RS*/ES*. Alternatively, load the key from a source with the source/path/name parameters below (which take precedence over key).
source (string, optional) – Where to load the key from — file, env, or variable — using the same shared reader as read. When any of source/path/name is present, the key is loaded from that source instead of the inline key.
path (string, optional) – File path to the key (implies source=file). For RS*/ES* this is a PEM file: PKCS#8 BEGIN PRIVATE KEY, PKCS#1 BEGIN RSA PRIVATE KEY, or SEC1 BEGIN EC PRIVATE KEY.
name (string, optional) – The environment‑variable name (source=env) or stored‑variable name (source=variable) that holds the key.
encoding (string, optional, default: utf-8) – Text encoding when reading a key file (utf-8, utf-16, ascii).
expiresIn (int, optional, default: 0) – Seconds until expiry; when greater than 0, sets exp = now + expiresIn.
variable (string, optional) – Store the signed compact JWT to this variable.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The signed JWT string (header.payload.signature). Empty string when claims is missing/invalid JSON, the signing key resolves empty (no inline key and no source/path/name, or the referenced file/env/variable is empty), the PEM cannot be parsed, or the algorithm is unsupported.

Side‑effects – Stores to variable when provided. Adds iat (and exp when expiresIn > 0) unless already present in claims.

Security note – No signature verification is done here (this mints tokens); use only in trusted test contexts. Prefer loading secrets from a source (source=env, name=...) or a variable rather than inlining them in YAML. For RS*/ES*, keep private keys in files (path=...) or env/variables rather than pasting PEM into the plan. Encrypted PEM keys are not supported yet.

Example – RFC 7523 JWT‑bearer OAuth flow

before:
  - '$jwtsign(claims={"iss":"${clientId}","sub":"${clientId}","aud":"${tokenUrl}"}, key=${signingKey}, algorithm=HS256, expiresIn=300, variable=assertion)'
httpRequest:
  url: '${tokenUrl}'
  method: POST
  headers:
    Content-Type: application/x-www-form-urlencoded
  payload:
    type: Raw
    raw: 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${assertion}'

Example – RS256 with a private key file

before:
    # Sign with an RSA private key loaded from disk; the header alg becomes RS256.
    - '$jwtsign(claims={"iss":"${clientId}","sub":"${clientId}","aud":"${tokenUrl}"}, path=./keys/private.pem, algorithm=RS256, expiresIn=300, variable=assertion)'

Example – key from an environment variable

before:
    # HMAC secret read from $env:JWT_SIGNING_KEY (never inlined in the plan).
    - '$jwtsign(claims={"sub":"${clientId}"}, source=env, name=JWT_SIGNING_KEY, algorithm=HS256, expiresIn=300, variable=assertion)'
    # The same works for an RS256 PEM held in an env var or a stored variable:
    - '$jwtsign(claims={"sub":"${clientId}"}, source=variable, name=privatePem, algorithm=RS256, variable=assertion)'

`read`

Description
Reads text from a file, environment variable, or another variable.

Parameters

source (string, optional) – One of file, env, variable.
- If omitted: if path is provided, file is assumed; otherwise variable is assumed.
path (string, optional) – File path when using file source.
name (string, optional) – Env var name (when source=env) or variable name (when source=variable).
encoding (string, optional, default: utf-8) – Supported: utf-8/utf8, unicode/utf-16, ascii (file source only).
as (string, optional, default: string) – Type for the stored variable: string (default), int, double/float/number, decimal, bool, or json. The inline return is always text — as only changes the variable's stored type (the same mechanism as readif). The default is string to preserve existing behavior (unlike readif, which defaults to auto). The navigable structured types (csv/xml) are only available on plan variables: definitions, not as a method as.
variable (string, optional) – Also store the value to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The text content read, or empty string if not found/invalid.

Side‑effects – Stores to variable when provided, using the type from as (default string).

Examples

Read from file

variables:
- name: fileContent
  value: $read(path=../data/sample.txt)

Read from environment

variables:
- name: pathEnv
  value: $read(source=env, name=PATH)

Read from another variable

variables:
- name: copyOfId
  value: $read(source=variable, name=id)

Read and store as a typed value

before:
    # inline substitution is text, but the stored 'threshold' variable is an int
    - '$read(source=env, name=THRESHOLD, as=int, variable=threshold)'

`readif`

Description
The conditional counterpart of read. Evaluates a boolean condition; when it is true, it performs the same read as read (from a file, environment variable, or another variable) and stores the result. When it is false, it stores default if provided, otherwise the variable is left untouched (no read happens).

Parameters

condition (string, required) – A boolean expression (Flee syntax, same engine as skipIf). Placeholders are resolved before it is evaluated.
source / path / name / encoding – Same as read; used only when condition is true.
default (string, optional) – Value stored when condition is false. When omitted, the variable is left unchanged.
as (string, optional, default: auto) – Force the stored type: int | double | decimal | bool | string | json. Numeric types evaluate arithmetic in the value (see Arithmetic in numeric values).
isGlobal (bool, optional, default: false) – By default the variable is stored scoped to the current session; set isGlobal=true to store it globally (shared across all sessions).
variable (string, required) – Store the result under this variable name.

Returns – The read value (condition true) or the resolved default (condition false). Empty string when the condition is false and no default is provided.

Side‑effects – Stores to variable only for the branch actually taken. A false condition without default performs no read and no store.

Example – read a config file only when a flag is on

before:
  - '$readif(condition=${useOverrides} == true, source=file, path=../data/overrides.json, as=json, variable=overrides, default={})'

Example – pull a token from the environment only in CI

before:
  - '$readif(condition="${env}" == "ci", source=env, name=API_TOKEN, variable=token)'

`counter`

Description
Maintains a stateful counter that advances by step starting from start. When the counter exceeds the reset boundary, it wraps back to start.

Parameters

start (int, optional, default: 0) – The value the counter starts with.
reset (int, optional, default: 100000) – The boundary at which the counter resets to start. For positive step, the counter resets when it exceeds this value. For negative step, the counter resets when it goes below this value.
step (int, optional, default: 1) – Used to increment or decrement the counter each time the method executes.
name (string, optional) – Named counter ID to keep multiple independent sequences.
isGlobal (bool, optional, default: false) – When true, the counter is shared globally across all sessions. When false, each session maintains its own counter.
variable (string, optional) – Also store the value to this variable when provided.

Returns – The current counter value (as string). Empty string if an unexpected error occurs.

State & Scope

By default, counters are session-specific and do not collide with other sessions unless isGlobal is set to true.
Using different name values creates distinct counters even with the same start/reset.

Side‑effects

Stores to variable when provided.
When the counter exceeds the reset boundary, it resets to start.

Example – incrementing counter

variables:
- name: seq
  value: $counter(start=1, reset=3, step=1, name=myCounter, isGlobal=false, variable=myVar)
# Subsequent evaluations of the same expression:
# 1 → 2 → 3 → 1 → 2 → ...

Example – decrementing counter

variables:
- name: countdown
  value: $counter(start=10, reset=1, step=-1, name=countdown)
# Subsequent evaluations:
# 10 → 9 → 8 → ... → 2 → 1 → 10 → ...

`tolowercase`

Description
Converts a string to lower case using culture-invariant rules.

Parameters

source (string, required) – The string or placeholder expression to convert. Can also be passed as a positional (unnamed) argument.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The lower-cased string. Empty string if source is empty or not provided.

Side-effects – Stores to variable when provided.

Example – inline

variables:
- name: lowerName
    value: $tolowercase(source=Hello World)
# result: "hello world"

Example – from captured variable

variables:
- name: normalizedName
    value: $tolowercase(source=${users.Body[0].name})

Example – store and reuse

variables:
- name: normalized
    value: $tolowercase(source=${users.Body[0].name}, variable=normalized)

`touppercase`

Description
Converts a string to upper case using culture-invariant rules.

Parameters

source (string, required) – The string or placeholder expression to convert. Can also be passed as a positional (unnamed) argument.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The upper-cased string. Empty string if source is empty or not provided.

Side-effects – Stores to variable when provided.

Example – inline

variables:
- name: upperCode
    value: $touppercase(source=active)
# result: "ACTIVE"

Example – from captured variable

variables:
- name: upperName
    value: $touppercase(source=${users.Body[$length($users.Body)-1].name})

`contains`

Description
Checks whether a string contains a given substring. Returns "true" or "false" as a string.

Parameters

source (string, required) – The string to search within. Can also be passed as the first positional (unnamed) argument.
value (string, required) – The substring to look for.
ignoreCase (bool, optional, default: false) – When true, comparison is case-insensitive.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – "true" if the substring is found, "false" otherwise. Returns "false" when source or value is missing.

Side-effects – Stores to variable when provided.

Example – basic

skipIf: '$contains(source=${users.Body[0].name}, value=Leanne)'

Example – case-insensitive

skipIf: '$contains(source=${users.Body[0].name}, value=leanne, ignoreCase=true)'

Example – store and reuse

variables:
- name: hasLeanne
    value: $contains(source=${users.Body[0].name}, value=Leanne, variable=hasLeanne)

`startswith`

Description
Checks whether a string starts with a given prefix. Returns "true" or "false" as a string.

Parameters

source (string, required) – The string to test. Can also be passed as the first positional (unnamed) argument.
value (string, required) – The prefix to check for.
ignoreCase (bool, optional, default: false) – When true, comparison is case-insensitive.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – "true" if the string starts with the prefix, "false" otherwise. Returns "false" when source or value is missing.

Side-effects – Stores to variable when provided.

Example – basic

skipIf: '$startswith(source=${users.Body[0].name}, value=Leanne)'

Example – case-insensitive

skipIf: '$startswith(source=${users.Body[0].name}, value=leanne, ignoreCase=true)'

Example – using a captured variable

iterations:
    - name: users
        httpRequest:
            capture:
                to: users
                as: Json
                makeGlobal: true
            url: https://jsonplaceholder.typicode.com/users
            method: GET
    - name: httpbinOrg
        httpRequest:
            skipIf: '$startswith(source=${users.Body[9].name}, value=Clementina)'
            httpMethod: Get
            url: https://jsonplaceholder.typicode.com/

`endswith`

Description
Checks whether a string ends with a given suffix. Returns "true" or "false" as a string.

Parameters

source (string, required) – The string to test. Can also be passed as the first positional (unnamed) argument.
value (string, required) – The suffix to check for.
ignoreCase (bool, optional, default: false) – When true, comparison is case-insensitive.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – "true" if the string ends with the suffix, "false" otherwise. Returns "false" when source or value is missing.

Side-effects – Stores to variable when provided.

Example – basic

skipIf: '$endswith(source=${users.Body[0].email}, value=.biz)'

Example – case-insensitive

skipIf: '$endswith(source=${users.Body[0].email}, value=.BIZ, ignoreCase=true)'

Example – store and reuse

variables:
- name: isBizEmail
    value: $endswith(source=${users.Body[0].email}, value=.biz, variable=isBizEmail)

`find`

Description
Declarative replacement for a for loop over a JSON array. find iterates the elements of a JSON array, evaluates a boolean predicate against each element (the current element is referenced with the bare alias item), optionally projects a field, and stores the result — with its natural type — into a variable.

Parameters

source (string, required) – The JSON to search, usually a captured response body such as $users.Body. May also be a literal JSON array/object or any expression that resolves to JSON. Keeps the $ prefix.
path (string, optional) – A JSONPath to the array of candidate elements inside source (e.g. $.data.orders[*]). If omitted, source itself is treated as the array.
where (string, optional) – A boolean predicate evaluated per element. Reference the current element's fields with the bare alias item (e.g. item.status == "shipped"). item fields are auto‑quoted by JSON type — do not wrap them in quotes yourself. If omitted, every element matches.
select (string, optional) – The value to project from each matched element (e.g. item.id). If omitted, the whole element is used (stored as navigable JSON).
match (string, optional, default: first) – Which match(es) to return:
- first – the first matching element (stops early).
- last – the last matching element.
- index:N – the Nth match (0‑based).
- count – the number of matches (stored as an integer).
- all – every match, as a JSON array.
default (string, optional) – Value stored/returned when nothing matches (for count, the default is 0).
as (string, optional, default: auto) – Force the stored type: auto | json | int | double | decimal | bool | string. With auto, the type is inferred (objects/arrays → JSON, integers → int, etc.).
variable (string, optional) – Store the result under this variable name.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The projected value (or whole element) for single‑match modes; a JSON array for match=all; an integer for match=count.

Side‑effects – Stores the result to variable using the proper type, so it can be navigated later (e.g. ${matchedUser.id}).

Syntax notes

Inside where/select, use bare item — find reads the field directly and quotes strings for you: where=item.company.name == "Acme", where=item.total > 100.
To reference external variables in where, use the normal placeholder form: where=item.total > ${threshold}.
source keeps the $ prefix (source=$users.Body); do not quote item.

Example – find one and reuse it

before:
  - '$find(source=$users.Body, where=item.username == "Bret", select=item.id, match=first, variable=userId)'
httpRequest:
  url: https://jsonplaceholder.typicode.com/users/${userId}/albums
  method: GET

Example – count and all

# how many users have id > 5 (stored as an integer)
$find(source=$users.Body, where=item.id > 5, match=count, variable=bigUserCount)

# collect every matching id as a JSON array
$find(source=$users.Body, where=item.address.city == "Gwenborough", select=item.id, match=all, variable=ids)

Example – store the whole (navigable) object, then verify

before:
  - '$find(source=$users.Body, where=item.company.name == "Romaguera-Crona", match=first, variable=matchedUser)'
skipIf: '"${matchedUser.username}" != "Bret"'
httpRequest:
  url: https://jsonplaceholder.typicode.com/users/${matchedUser.id}/todos
  method: GET

See the full runnable examples in examples/19.Find.md.

`findxml`

Description
The XPath‑based counterpart of find for XML sources. Selects a node set with path (XPath), optionally filters it with where (an XPath predicate), projects a value with select (a relative XPath), and stores the result using the same match modes as find.

find works on JSON (JSONPath); findxml works on XML (XPath). Use whichever matches your captured as: type.

Parameters

source (string, required) – The XML to search, usually a captured response body such as $orders.Body. Keeps the $ prefix.
path (string, optional, default: /*/*) – An XPath selecting the candidate node set (e.g. /orders/order). The default selects the direct children of the root element.
where (string, optional) – An XPath predicate written without the surrounding [ ], used to filter the node set, e.g. status="shipped", @kind="b", total>100. Use double quotes for string literals so the single‑quoted YAML expression is not broken.
select (string, optional) – A relative XPath projecting a value from each matched node, e.g. id, @status, text(). If omitted, the matched node's text (or attribute value) is used.
match (string, optional, default: first) – first | last | index:N | count | all (same semantics as find).
default (string, optional) – Value returned/stored when nothing matches (count defaults to 0, all to an empty array).
as (string, optional, default: auto) – Force the stored type (int, double, string, …). Projected XML values are text by default.
namespaces (string, optional) – Declare XPath prefix→URI bindings as prefix=uri;prefix=uri, then use those prefixes in path/where/select (e.g. path=/s:Envelope/s:Body with namespaces=s=http://schemas.xmlsoap.org/soap/envelope/). Each binding is split on its first =, so URIs may safely contain : and /.
ignoreNamespaces (bool, optional, default: false) – When true, strips all namespaces from the source before matching so plain, unprefixed XPath (e.g. /orders/order) matches regardless of any xmlns (default or prefixed) on the document. Handy for SOAP and other heavily namespaced payloads when you don't want to declare prefixes.
variable (string, optional) – Store the result under this variable name.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The projected value for single‑match modes; a JSON array of projected values for match=all; an integer for match=count.

Side‑effects – Stores the result to variable when provided.

Notes

XML namespaces are supported two ways: declare prefixes with namespaces= and use them in your XPath, or set ignoreNamespaces=true to strip namespaces so unprefixed XPath matches. (XPath 1.0 treats an unprefixed name as no namespace, so a document that declares an xmlns will not match a bare /orders/order unless you do one of these.)
External entities are disabled (protects against XXE); this holds for both the normal and ignoreNamespaces code paths.

Example – filter and project

For a captured orders response shaped like:

<orders>
  <order kind="online"><id>1</id><status>shipped</status><total>150</total></order>
  <order kind="store"><id>2</id><status>pending</status><total>50</total></order>
  <order kind="online"><id>3</id><status>shipped</status><total>300</total></order>
</orders>

before:
  # first shipped order's id -> 1
  - '$findxml(source=$orders.Body, path=/orders/order, where=status="shipped", select=id, match=first, variable=firstShippedId)'
  # last shipped order's total -> 300
  - '$findxml(source=$orders.Body, path=/orders/order, where=status="shipped", select=total, match=last, variable=lastShippedTotal)'
  # 2nd order with total>100 (0-based) -> id 3
  - '$findxml(source=$orders.Body, path=/orders/order, where=total>100, select=id, match=index:1, variable=secondBig)'
  # how many are shipped -> 2 (stored as an integer)
  - '$findxml(source=$orders.Body, path=/orders/order, where=status="shipped", match=count, variable=shippedCount)'
  # every shipped id as a JSON array -> ["1","3"]
  - '$findxml(source=$orders.Body, path=/orders/order, where=status="shipped", select=id, match=all, variable=shippedIds)'
  # attribute filter + attribute projection -> "online"
  - '$findxml(source=$orders.Body, path=/orders/order, where=@kind="online", select=@kind, match=first, variable=firstKind)'
  # no select -> the matched node's text; status of order #2 -> "pending"
  - '$findxml(source=$orders.Body, path=/orders/order[id="2"], select=status, match=first, variable=order2Status)'
  # no match -> the default value
  - '$findxml(source=$orders.Body, path=/orders/order, where=status="cancelled", select=id, match=first, default=NONE, variable=cancelledId)'

Example – namespaced XML (SOAP)

Every element in this response is namespaced (a soap: prefix on the envelope plus an o: prefix on the order elements):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
                             xmlns:o="urn:acme:orders">
    <soap:Body>
        <o:orders>
            <o:order><o:id>1</o:id><o:status>shipped</o:status></o:order>
            <o:order><o:id>2</o:id><o:status>pending</o:status></o:order>
        </o:orders>
    </soap:Body>
</soap:Envelope>

before:
    # Option A - declare the prefixes you use in the XPath
    - '$findxml(source=$soap.Body, path=/soap:Envelope/soap:Body/o:orders/o:order, where=o:status="shipped", select=o:id, match=first, namespaces=soap=http://schemas.xmlsoap.org/soap/envelope/;o=urn:acme:orders, variable=firstShippedId)'
    # Option B - ignore namespaces entirely and use plain, unprefixed XPath
    - '$findxml(source=$soap.Body, path=/Envelope/Body/orders/order, where=status="shipped", select=id, match=first, ignoreNamespaces=true, variable=firstShippedId)'

`setvariable` / `set`

Description
Stores a value into a variable, optionally coercing it to a specific type. set is an alias of setvariable.

Parameters

variable (string, required) – The name of the variable to store into.
value (string, required) – The value to store. Placeholders are resolved first.
as (string, optional) – Type override: int | double | decimal | bool | string | json. When omitted, the value is stored as a string. Use as=json to store navigable JSON. When as is a numeric type, an arithmetic value is evaluated (see Arithmetic in numeric values).
isGlobal (bool, optional, default: false) – By default the variable is stored scoped to the current session; set isGlobal=true to store it globally (shared across all sessions).

Returns – The stored value as a string.

Side‑effects – Stores the (typed) value to variable.

Example

before:
  - '$setvariable(variable=greeting, value=hello)'          # stored as a string
  - '$set(variable=retries, value=3, as=int)'               # alias + typed as int
  - '$setvariable(variable=payload, value=[1,2,3], as=json)' # navigable JSON
  - '$set(variable=total, value=2+3, as=int)'               # arithmetic -> 5

Arithmetic in numeric values

When as is a numeric type (int, integer, double, float, number, decimal), the value (and, for the conditional variants, the default) is treated as an arithmetic expression and evaluated before it is stored — so 2+3 stores 5, not the text "2+3". This applies to setvariable / set, setvariableif / setif, and readif.

Supported operators: + - * / and parentheses ( ).
Division is integer for whole operands – 10/4 is 2. Write 10.0/4 or 1.5+1 for a real quotient (2.5).
Placeholders resolve first, so ${a}+${b} computes from the resolved numbers.
Without a numeric as (or with as=string/no as), the value is stored verbatim – no arithmetic, no auto‑number inference. So value=2+3 stays the string "2+3".

before:
  - '$setvariable(variable=area, value=${width}*${height}, as=int)'   # e.g. 4*3 -> 12
  - '$set(variable=avg, value=(1+2+3)/3, as=double)'                  # 2
  - '$set(variable=ratio, value=10.0/4, as=double)'                   # 2.5
  - '$setvariable(variable=literal, value=2+3)'                       # "2+3" (string, not evaluated)

`setvariableif` / `setif`

Description
Conditional store: evaluates a boolean condition and stores value into variable when it is true. When it is false, it stores default if provided, otherwise the variable is left untouched. setif is an alias of setvariableif.

Parameters

variable (string, required) – The name of the variable to store into.
condition (string, required) – A boolean expression (Flee syntax, same engine as skipIf). Placeholders are resolved before it is evaluated.
value (string, required) – The value stored when condition is true. Resolved only when this branch is taken.
default (string, optional) – The value stored when condition is false. When omitted, the variable is left unchanged.
as (string, optional) – Type override: int | double | decimal | bool | string | json. Numeric types evaluate arithmetic in value/default (see Arithmetic in numeric values).
isGlobal (bool, optional, default: false) – By default the variable is stored scoped to the current session; set isGlobal=true to store it globally (shared across all sessions).

Returns – The stored value for the branch taken. Empty string when the condition is false and no default is provided.

Side‑effects – Stores the (typed) value only for the branch actually taken.

Example – tier based on a captured total

before:
  - '$setvariableif(variable=tier, condition=${order.total} > 100, value=premium, default=standard)'

Example – set a value only when one is missing (leave it untouched otherwise)

before:
  - '$setif(variable=pageSize, condition="${pageSize}" == "", value=20, as=int)'

Example – conditional arithmetic

before:
  # double the price when a discount is NOT active, otherwise keep it
  - '$setvariableif(variable=charge, condition=${discount} == 0, value=${price}*2, default=${price}, as=double)'

`sum`

Description
Adds all numeric values in a source array.

Parameters

source (string, required) – A JSON array whose elements may be literals or placeholders ([${x}, 10, 4, ${z}]), or a variable that resolves to a JSON array (${prices}). May also be passed positionally.
as (string, optional) – Type override for the stored result (int | double | decimal | bool | string | json).
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The sum. Whole results are returned as integers, otherwise as doubles. Empty string when the source has no numeric values.

Side‑effects – Stores to variable when provided. Non‑numeric elements are skipped with a warning.

Example

before:
  - '$sum(source=[${x}, 10, 4, ${z}], variable=total)'
  - '$sum(source=${prices}, variable=cartTotal)'   # variable holding a JSON array

`min`

Description
Returns the smallest numeric value in a source array.

Parameters

source (string, required) – A JSON array or a variable resolving to one. May be passed positionally.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The smallest value (int if whole, else double). Empty string when there are no numeric values.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$min(source=[8, 2, 5], variable=lowest)'   # 2

`max`

Description
Returns the largest numeric value in a source array.

Parameters

source (string, required) – A JSON array or a variable resolving to one. May be passed positionally.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The largest value (int if whole, else double). Empty string when there are no numeric values.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$max(source=[8, 2, 5], variable=highest)'  # 8

`multiply`

Description
Multiplies all numeric values in a source array.

Parameters

source (string, required) – A JSON array or a variable resolving to one. May be passed positionally.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The product (int if whole, else double). Empty string when there are no numeric values.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$multiply(source=[2, 3, 4], variable=product)'  # 24

`average` / `avg`

Description
Returns the arithmetic mean of a source array. avg is an alias of average.

Parameters

source (string, required) – A JSON array or a variable resolving to one. May be passed positionally.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The mean, always as a double. Empty string when there are no numeric values.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$average(source=[1, 2, 3, 4], variable=mean)'  # 2.5
  - '$avg(source=${latencies}, variable=avgLatency)'

`divide`

Description
Divides a by b.

Parameters

a (number, required) – The dividend.
b (number, required) – The divisor.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The quotient, always as a double. Returns an empty string (with a warning) when b is zero or an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$divide(a=10, b=4, variable=ratio)'   # 2.5

`subtract`

Description
Subtracts b from a.

Parameters

a (number, required) – The minuend.
b (number, required) – The subtrahend.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – a - b (int if whole, else double). Empty string when an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$subtract(a=100, b=35, variable=remaining)'  # 65

`mod`

Description
Returns the remainder of a divided by b.

Parameters

a (number, required) – The dividend.
b (number, required) – The divisor.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – a % b (int if whole, else double). Returns an empty string (with a warning) when b is zero or an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$mod(a=10, b=3, variable=leftover)'  # 1

`pow`

Description
Raises base to the power of exponent.

Parameters

base (number, required) – The base.
exponent (number, required) – The exponent.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – base ^ exponent (int if whole, else double). Empty string when an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$pow(base=2, exponent=10, variable=capacity)'  # 1024

`abs`

Description
Returns the absolute value of a number.

Parameters

source (number, required) – The number. May be passed positionally ($abs(-7)).
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The absolute value (int if whole, else double). Empty string when the source is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$abs(source=-5, variable=magnitude)'  # 5
  - '$abs(-7)'                             # 7 (positional)

`floor`

Description
Rounds a number down to the nearest integer.

Parameters

source (number, required) – The number. May be passed positionally.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The largest integer less than or equal to source. Empty string when the source is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$floor(source=2.7, variable=low)'  # 2

`ceil`

Description
Rounds a number up to the nearest integer.

Parameters

source (number, required) – The number. May be passed positionally.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The smallest integer greater than or equal to source. Empty string when the source is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$ceil(source=2.1, variable=high)'  # 3

`round`

Description
Rounds a number to a given number of decimal places (away from zero).

Parameters

source (number, required) – The number. May be passed positionally.
digits (int, optional, default: 0) – The number of decimal places (0–15).
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – The rounded value. With digits=0 it is an integer; otherwise a double. Empty string when the source is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$round(source=3.14159, digits=2, variable=pi)'  # 3.14
  - '$round(source=2.6, variable=nearest)'           # 3

`clamp`

Description
Bounds a value into the inclusive range [min, max].

Parameters

value (number, required) – The value to bound.
min (number, required) – The lower bound.
max (number, required) – The upper bound.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – value limited to [min, max]. If min > max the bounds are swapped (with a warning). Empty string when an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$clamp(value=15, min=0, max=10, variable=bounded)'  # 10

`greaterthan`

Description
Returns whether a is greater than b.

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
variable (string, optional) – Store the "true"/"false" result to this variable.
numberVariable (string, optional) – Also store the greater of the two operands (max(a, b)) to this variable.
isGlobal (bool, optional, default: false) – Store the variable(s) in the current session scope; set isGlobal=true to store them globally (shared across all sessions).

Returns – "true" when a > b, otherwise "false". Returns "false" when an operand is missing/non‑numeric.

Side‑effects – Stores the boolean to variable, and the greater number to numberVariable, when provided.

Example

before:
  - '$greaterthan(a=${p95}, b=250, variable=slaBreached, numberVariable=worstLatency)'

`smallerthan`

Description
Returns whether a is smaller than b.

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
variable (string, optional) – Store the "true"/"false" result to this variable.
numberVariable (string, optional) – Also store the lesser of the two operands (min(a, b)) to this variable.
isGlobal (bool, optional, default: false) – Store the variable(s) in the current session scope; set isGlobal=true to store them globally (shared across all sessions).

Returns – "true" when a < b, otherwise "false". Returns "false" when an operand is missing/non‑numeric.

Side‑effects – Stores the boolean to variable, and the lesser number to numberVariable, when provided.

Example

before:
  - '$smallerthan(a=${p95}, b=100, variable=isFast, numberVariable=bestCase)'

`greaterthanorequal`

Description
Returns whether a is greater than or equal to b.

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
variable (string, optional) – Store the "true"/"false" result to this variable.
numberVariable (string, optional) – Also store the greater of the two operands (max(a, b)) to this variable.
isGlobal (bool, optional, default: false) – Store the variable(s) in the current session scope; set isGlobal=true to store them globally (shared across all sessions).

Returns – "true" when a >= b, otherwise "false". Returns "false" when an operand is missing/non‑numeric.

Side‑effects – Stores the boolean to variable, and the greater number to numberVariable, when provided.

Example

before:
  - '$greaterthanorequal(a=5, b=5, variable=atLeastFive)'  # true

`smallerthanorequal`

Description
Returns whether a is smaller than or equal to b.

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
variable (string, optional) – Store the "true"/"false" result to this variable.
numberVariable (string, optional) – Also store the lesser of the two operands (min(a, b)) to this variable.
isGlobal (bool, optional, default: false) – Store the variable(s) in the current session scope; set isGlobal=true to store them globally (shared across all sessions).

Returns – "true" when a <= b, otherwise "false". Returns "false" when an operand is missing/non‑numeric.

Side‑effects – Stores the boolean to variable, and the lesser number to numberVariable, when provided.

Example

before:
  - '$smallerthanorequal(a=9, b=5, variable=withinFive)'  # false

`greater`

Description
Returns the greater of two numbers (unlike greaterthan, it returns the number itself, not a boolean).

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – max(a, b) (int if whole, else double). Empty string when an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$greater(a=${p90}, b=${p95}, variable=worstLatency)'

`less`

Description
Returns the lesser of two numbers (unlike smallerthan, it returns the number itself, not a boolean).

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
as (string, optional) – Type override for the stored result.
variable (string, optional) – Also store the result to this variable when provided.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – min(a, b) (int if whole, else double). Empty string when an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$less(a=${configured}, b=${maxAllowed}, variable=effectiveLimit)'

`equal`

Description
Returns whether two numbers are equal, with an optional tolerance for approximate matches.

Parameters

a (number, required) – The left operand.
b (number, required) – The right operand.
tolerance (number, optional, default: 0) – Maximum absolute difference allowed (|a - b| <= tolerance).
variable (string, optional) – Store the "true"/"false" result to this variable.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – "true" when the numbers are equal (within tolerance), otherwise "false". Returns "false" when an operand is missing/non‑numeric.

Side‑effects – Stores to variable when provided.

Example

before:
  - '$equal(a=${count}, b=100, variable=isExact)'
  - '$equal(a=${count}, b=100, tolerance=2, variable=isNear)'  # |count - 100| <= 2

`stringequals`

Description
Returns whether two strings are equal, with an optional case‑insensitive comparison.

Parameters

a (string, required) – The first string. Placeholders are resolved first.
b (string, required) – The second string. Placeholders are resolved first.
ignoreCase (bool, optional, default: false) – When true, the comparison is case‑insensitive.
variable (string, optional) – Store the "true"/"false" result to this variable.
isGlobal (bool, optional, default: false) – Store the variable in the current session scope; set isGlobal=true to store it globally (shared across all sessions).

Returns – "true" when the two strings are equal, otherwise "false".

Side‑effects – Stores to variable when provided.

Example

before:
  - '$stringequals(a=${status}, b=OK, ignoreCase=true, variable=isOk)'

See the full runnable examples in examples/DeclerativeMethods.md.

General Notes

When a method is assigned to a variable, it is generally evaluated once and reused.
The optional variable argument is most useful when you call methods inline and still want to persist the produced value for later steps.
jwtclaim does not validate signatures; use for testing only.
datetime is an alias of timestamp.
String comparison methods (contains, startswith, endswith, stringequals) return "true" or "false" as text values.
Numeric methods store their result typed — whole numbers as integers, otherwise doubles (divide and average are always doubles) — so downstream expressions can keep doing math. Use as to override the stored type.
For numeric array methods (sum, min, max, multiply, average), source may be an inline JSON array, an array mixing literals and placeholders ([${x}, 10, 4, ${z}]), or a variable that resolves to a JSON array; non‑numeric elements are skipped.
Numeric comparison methods (greaterthan, smallerthan, greaterthanorequal, smallerthanorequal, equal) return "true"/"false"; the greater/smaller family can also store the winning number via numberVariable.

LPS Methods Reference

Table of Contents

random

randomnumber

length

randomItem

timestamp / datetime

guid

uuid

base64encode

base64decode

urlencode

urldecode

hash

hmac

format

strcat

generateemail

jwtclaim

jwtsign

read

readif

counter

tolowercase

touppercase

contains

startswith

endswith

find

findxml

setvariable / set

Arithmetic in numeric values

setvariableif / setif

sum

min

max

multiply

average / avg

divide

subtract

mod

pow

abs

floor

ceil

round

clamp

greaterthan

smallerthan

greaterthanorequal

smallerthanorequal

greater

less

equal

stringequals

General Notes

`random`

`randomnumber`

`length`

`randomItem`

`timestamp` / `datetime`

`guid`

`uuid`

`base64encode`

`base64decode`

`urlencode`

`urldecode`

`hash`

`hmac`

`format`

`strcat`

`generateemail`

`jwtclaim`

`jwtsign`

`read`

`readif`

`counter`

`tolowercase`

`touppercase`

`contains`

`startswith`

`endswith`

`find`

`findxml`

`setvariable` / `set`

`setvariableif` / `setif`

`sum`

`min`

`max`

`multiply`

`average` / `avg`

`divide`

`subtract`

`mod`

`pow`

`abs`

`floor`

`ceil`

`round`

`clamp`

`greaterthan`

`smallerthan`

`greaterthanorequal`

`smallerthanorequal`

`greater`

`less`

`equal`

`stringequals`