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.

random
randomnumber
length
randomItem
timestamp / datetime
guid
uuid
base64encode
base64decode
urlencode
urldecode
hash
format
generateemail
jwtclaim
read
counter
tolowercase
touppercase
contains
startswith
endswith

`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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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)

`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.

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"

`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.

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).
variable (string, optional) – Also store the value to this variable when provided.

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

Example

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

`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).
variable (string, optional) – Also store the value to this variable when provided.

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

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)

`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.

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.

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.

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.

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://httpbin.org/

`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.

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)

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) return "true" or "false" as text values.

LPS Methods Reference

Table of Contents

random

randomnumber

length

randomItem

timestamp / datetime

guid

uuid

base64encode

base64decode

urlencode

urldecode

hash

format

generateemail

jwtclaim

read

counter

tolowercase

touppercase

contains

startswith

endswith

General Notes

`random`

`randomnumber`

`length`

`randomItem`

`timestamp` / `datetime`

`guid`

`uuid`

`base64encode`

`base64decode`

`urlencode`

`urldecode`

`hash`

`format`

`generateemail`

`jwtclaim`

`read`

`counter`

`tolowercase`

`touppercase`

`contains`

`startswith`

`endswith`