rq.globals (Global variables)

The rq.globals object reads and changes global variables from a script. Global variables work like environment variables, but every request in every collection and environment can read them. This makes them the place for configuration or state that needs to be shared everywhere.

Methods

`rq.globals.get(key)`

Returns the value of a global variable. Parameters:

key (string): The variable’s name

Returns: The value, or undefined if the variable does not exist or is disabled. A number, boolean or array variable comes back as that type. A variable you set earlier in the same script comes back as set stored it. Example:

const version = rq.globals.get("appVersion");
console.log("App Version:", version);

`rq.globals.set(key, value, type?)`

Creates or updates a global variable. Parameters:

key (string): The variable’s name. It must not be empty.
value (any): The value to store. A variable that already exists converts the value to its type: set("count", "42") on a number variable stores 42. A new variable keeps the value exactly as you pass it. null or undefined removes the variable, the same as unset(key).
type (string, optional): The type to give the variable before the value is stored: "string", "number", "boolean", "array", "object" or "any". You can also pass { type }.

See How values are saved for what the next request reads. Example:

rq.globals.set("appVersion", "1.0.0");
rq.globals.set("regions", ["eu", "us"], "array");

`rq.globals.has(key)`

Checks whether a global variable exists and is enabled. Parameters:

key (string): The variable’s name

Returns: true if the variable exists and is enabled, otherwise false. Example:

if (!rq.globals.has("appVersion")) {
  console.log("No app version yet");
}

`rq.globals.unset(key)`

Removes a global variable. A disabled variable is left alone. Parameters:

key (string): The variable’s name. It must not be empty.

Example:

rq.globals.unset("appVersion");

`rq.globals.clear()`

Removes every global variable, disabled ones included. Example:

rq.globals.clear();

`rq.globals.toObject()`

Returns the enabled global variables as one object of names and values. Disabled variables are left out. Returns: An object such as { appVersion: "1.0.0", maxRetries: 3 }. Each value has the type get returns for it. Example:

const all = rq.globals.toObject();
console.log("Variables:", Object.keys(all));

`rq.globals.replaceIn(template)`

Replaces each {{name}} in a template with the value of that global variable. Parameters:

template (string, object or array): Text containing {{name}} references. In an object or an array, every string inside is replaced.

Returns: The template with the references replaced. A value that is not text is written the way JavaScript’s String() writes it, so an array becomes a,b. A name with no enabled variable, and a dynamic variable such as {{$guid}}, stays as written. Each reference is replaced once, so a {{name}} inside a value stays as written. To replace names from every scope, use rq.variables.replaceIn. Example:

const header = rq.globals.replaceIn("MyApp/{{appVersion}}");

`rq.globals.toObjectResolved(scope?, overrides?)`

Returns a plain copy of rq.globals, the same as toJSON(), with every {{name}} inside it replaced. For a plain object of names and values, use toObject(). Parameters:

scope (object, optional): The object whose replaceIn replaces the references. Pass rq.variables to replace names from every scope. Defaults to rq.globals.
overrides (array of objects, optional): Objects whose properties are copied onto the result, in order.

Returns: An object with id, values and mutations. Example:

const resolved = rq.globals.toObjectResolved(rq.variables);
resolved.values.forEach((item) => console.log(item.key, item.value));

`rq.globals.toJSON()`

Returns a plain copy of rq.globals. JSON.stringify(rq.globals) uses it. Returns: An object with:

id: The same as rq.globals.id
values: An array of { key, value, type } items, one per variable, with disabled: true on a disabled variable. An array variable’s value is its JSON text.
mutations: The changes this script recorded, as { stream, compacted, autoCompact }

Example:

console.log(JSON.stringify(rq.globals));

`rq.globals.syncVariablesFrom(object, track?)`

Copies the names and values of a plain object into the global variables. An existing variable gets the new value, converted to its type, and a new name becomes a new variable. Variables the object does not name are kept. The changes are saved the same way as set, but are not recorded in mutations. Parameters:

object (object): The names and values to copy in
track (boolean, optional): Set to true to get back what changed

Returns: With track set to true, an object that maps each new name to "created" and each name whose value changed to "updated". A name whose value did not change is not listed. Without track, undefined. Example:

// "retries" exists and "region" does not
const changes = rq.globals.syncVariablesFrom({ region: "eu", retries: 5 }, true);
console.log(changes); // { region: "created", retries: "updated" }

`rq.globals.syncVariablesTo(object?)`

Copies every global variable, disabled ones included, into a plain object. Parameters:

object (object, optional): The object to copy into. Any key in it that the global variables do not hold is deleted from it. Without it, a new object is used.

Returns: The object, with one property per variable. Each value has the type get returns for it. Example:

const copy = rq.globals.syncVariablesTo();
console.log(copy.appVersion);

`rq.globals.values`

Your global variables, as a list. Unlike get, has and toObject, the list includes disabled variables. Each item is one variable with key, value, type and disabled. Call the item’s get() to read its value as its type, since an array variable’s value is its JSON text, and its set(value) to change it. The list has these methods:

Read: one(key) returns the variable with that name, and get(key) its value. has(key) checks whether the list holds that name. count() returns the number of variables, all() an array of them, idx(index) the one at a position, and indexOf(key) its position, or -1. toObject() returns an object of names and values, and toJSON() an array of plain { key, value, type } items.
Loop: each(fn), map(fn), filter(fn), find(fn) and reduce(fn, initial) work like the array methods of the same name. fn receives each variable and its position.
Change: add({ key, value, type, disabled }) adds a variable. upsert({ key, value, type, disabled }) updates the variable with that name, or adds it when there is none. remove(key) removes the variable with that name, and remove(fn) removes every variable fn returns true for. clear() removes every variable.
Text: replace(text) replaces each {{name}} in text with the list’s value for that name.
Copy: syncFromObject(object, track?, prune?) works like syncVariablesFrom, and with prune set to true it also removes the variables the object does not name. syncToObject(object?) works like syncVariablesTo.

Changes made through values are saved the same way as set, but are not recorded in mutations. Example:

rq.globals.values.each((variable) => {
  console.log(variable.key, variable.get(), variable.disabled === true);
});
rq.globals.values.upsert({ key: "region", value: "eu" });

`rq.globals.id`

The id of your global variables. Example:

console.log(rq.globals.id);

`rq.globals.mutations`

A record of the set and unset calls this script made on rq.globals, in order. Recording is on from the start of the script. clear() records an unset for each variable it removes, and applyMutation records the call it makes. Changes made through values or syncVariablesFrom are not recorded.

stream (array): One entry per call: [key, value] for set and [key] for unset. value is what you passed, before any conversion.
compacted (object): The last change to each name, filled by compact() or by autoCompact
count(): Returns the number of recorded changes
compact(): Keeps only the last change to each name, moving the entries from stream into compacted
applyOn(target): Makes the recorded changes again on another object, such as rq.environment

Example:

rq.globals.set("token", "abc");
rq.globals.unset("oldToken");
console.log(rq.globals.mutations.stream); // [["token", "abc"], ["oldToken"]]

// Make the same changes to the active environment
rq.globals.mutations.applyOn(rq.environment);

`rq.globals.enableTracking(options?)`

Starts recording set and unset calls in mutations. Recording is already on when a script starts, so calling this does nothing until you call disableTracking(). After that, it starts a new, empty record. Parameters:

options (object, optional): { autoCompact: true } keeps only the last change to each name, in mutations.compacted

Example:

rq.globals.disableTracking();
rq.globals.enableTracking({ autoCompact: true });
rq.globals.set("page", 1);
rq.globals.set("page", 2);
console.log(rq.globals.mutations.compacted); // { page: ["page", 2] }

`rq.globals.disableTracking()`

Stops recording changes in mutations. What was already recorded stays in mutations. Example:

rq.globals.disableTracking();

`rq.globals.applyMutation(instruction, key, value?)`

Makes one change, named by instruction: "set" calls set(key, value) and "unset" calls unset(key). Any other instruction does nothing. Parameters:

instruction (string): "set" or "unset"
key (string): The variable’s name
value (any, optional): The value, for "set"

Example:

rq.globals.applyMutation("set", "region", "eu");

`rq.globals.addLayer(list)`

Adds a list of variables to read when the global variables have no enabled variable of that name. get, has, toObject and replaceIn read the lists in the order you add them. Writes still go to the global variables only. Parameters:

list: Another object’s values, such as rq.environment.values

Example:

rq.globals.addLayer(rq.environment.values);
const baseUrl = rq.globals.get("baseUrl"); // the environment's value when no global variable has that name

How values are saved

rq.globals saves values the same way as rq.environment. Within one script, get returns the value set stored. When the script ends, the value is saved, and the next request reads the saved form: an object, for example, comes back as its JSON text. See How values are saved for every kind of value, Typed variables for how a variable’s type converts the value you set, and Disabled variables for how disabled variables behave. Array variables work as described in Working with array variables.

Common Use Cases

Store Application Version

Keep track of the application or API version being tested:

// In setup script
rq.globals.set("appVersion", "1.0.0");
rq.globals.set("apiVersion", "v2");

// In any request
const version = rq.globals.get("appVersion");
console.log("Testing with app version:", version);

Track Global State

Maintain state that needs to be shared across all collections:

// Track total requests made
const totalRequests = Number(rq.globals.get("totalRequests") || 0);
rq.globals.set("totalRequests", totalRequests + 1);
console.log("Total requests made:", totalRequests + 1);

Store User Preferences

Keep user preferences that apply globally:

rq.globals.set("preferredLanguage", "en");
rq.globals.set("dateFormat", "YYYY-MM-DD");
rq.globals.set("timezone", "UTC");

Global Timestamp

Set a global timestamp that all requests can reference:

// Set once at the beginning of a test run
rq.globals.set("testRunStartTime", Date.now());

// Reference in any request
const startTime = Number(rq.globals.get("testRunStartTime"));
const elapsed = Date.now() - startTime;
console.log("Time since test start:", elapsed, "ms");

Feature Flags

Turn features on or off for every request. Comparing the text works whether the flag is a boolean or a string variable:

// Enable or disable features globally
rq.globals.set("enableLogging", true);
rq.globals.set("enableDebugMode", false);

// Check a flag in any request
if (String(rq.globals.get("enableDebugMode")) === "true") {
  console.log("Debug mode is enabled");
}

Store Common Constants

Define constants that are used across all collections:

rq.globals.set("MAX_PAGE_SIZE", "100");
rq.globals.set("DEFAULT_PAGE_SIZE", "20");
rq.globals.set("API_KEY_HEADER", "X-API-Key");

Variable Scope Hierarchy

When the same name exists in several scopes, {{name}} in a request and rq.variables.get read the most specific one:

Runtime > Data file > Environment > Collection > Global

Global variables are the last fallback: every request can read them, and any more specific scope overrides them. See Variable Precedence for the full order.

Best Practices

Use Sparingly: Reserve global variables for truly global data. Prefer collection or environment variables when possible.

Naming Convention: Use clear, uppercase names for global constants

rq.globals.set("MAX_RETRY_ATTEMPTS", "5");
rq.globals.set("DEFAULT_TIMEOUT_MS", "30000");

Document Purpose: Comment your global variable usage

// Global feature flag for new API version
rq.globals.set("useV2Api", true);

Check Existence: Verify a variable exists before using it

if (!rq.globals.has("myGlobalVar")) {
  console.error("Global variable 'myGlobalVar' not set");
}

Initialize Early: Set global variables in a dedicated setup script or request
Clean Up: Remove globals once you are done with them
rq.globals.unset("temporaryFlag");
Type Conversion: A number, boolean or array variable comes back as that type, and a string variable as a string. Convert a string variable when you need something else:
const maxRetries = Number(rq.globals.get("maxRetries") || 3); const enableFeature = String(rq.globals.get("enableFeature")) === "true";

Getting Started

API Design

Mock Server

Collaboration & Projects

Account & Administration

rq.globals (Global variables)

Methods

`rq.globals.get(key)`

`rq.globals.set(key, value, type?)`

`rq.globals.has(key)`

`rq.globals.unset(key)`

`rq.globals.clear()`

`rq.globals.toObject()`

`rq.globals.replaceIn(template)`

`rq.globals.toObjectResolved(scope?, overrides?)`

`rq.globals.toJSON()`

`rq.globals.syncVariablesFrom(object, track?)`

`rq.globals.syncVariablesTo(object?)`

`rq.globals.values`

`rq.globals.id`

`rq.globals.mutations`

`rq.globals.enableTracking(options?)`

`rq.globals.disableTracking()`

`rq.globals.applyMutation(instruction, key, value?)`

`rq.globals.addLayer(list)`

How values are saved

Common Use Cases

Store Application Version

Track Global State

Store User Preferences

Global Timestamp

Feature Flags

Store Common Constants

Variable Scope Hierarchy

Best Practices

​Methods

​rq.globals.get(key)

​rq.globals.set(key, value, type?)

​rq.globals.has(key)

​rq.globals.unset(key)

​rq.globals.clear()

​rq.globals.toObject()

​rq.globals.replaceIn(template)

​rq.globals.toObjectResolved(scope?, overrides?)

​rq.globals.toJSON()

​rq.globals.syncVariablesFrom(object, track?)

​rq.globals.syncVariablesTo(object?)

​rq.globals.values

​rq.globals.id

​rq.globals.mutations

​rq.globals.enableTracking(options?)

​rq.globals.disableTracking()

​rq.globals.applyMutation(instruction, key, value?)

​rq.globals.addLayer(list)

​How values are saved

​Common Use Cases

​Store Application Version

​Track Global State

​Store User Preferences

​Global Timestamp

​Feature Flags

​Store Common Constants

​Variable Scope Hierarchy

​Best Practices

​Related Documentation

Methods

`rq.globals.get(key)`

`rq.globals.set(key, value, type?)`

`rq.globals.has(key)`

`rq.globals.unset(key)`

`rq.globals.clear()`

`rq.globals.toObject()`

`rq.globals.replaceIn(template)`

`rq.globals.toObjectResolved(scope?, overrides?)`

`rq.globals.toJSON()`

`rq.globals.syncVariablesFrom(object, track?)`

`rq.globals.syncVariablesTo(object?)`

`rq.globals.values`

`rq.globals.id`

`rq.globals.mutations`

`rq.globals.enableTracking(options?)`

`rq.globals.disableTracking()`

`rq.globals.applyMutation(instruction, key, value?)`

`rq.globals.addLayer(list)`

How values are saved

Common Use Cases

Store Application Version

Track Global State

Store User Preferences

Global Timestamp

Feature Flags

Store Common Constants

Variable Scope Hierarchy

Best Practices

Related Documentation