Scripting API

Info and execution

Details of the current send, and controls for skipping the request.

Declaration

relay.info
relay.execution
relay.iterationData

Overview

relay.info tells a script which request it's running for and in which phase, which helps a collection or folder script that runs for many requests. relay.execution controls the send, such as skipping it.

// In a collection's pre-request script: skip requests until there's a token.
if (relay.info.requestName !== "Log In" && !relay.environment.get("token")) {
  console.warn("No token yet. Send Log In first.");
  relay.execution.skipRequest();
}

Relay sends one request at a time and has no collection runner, so the members for iterations and run order have fixed values or no effect.

Topics

Run details

info.eventName

relay.info.eventName: "prerequest" | "test"

The phase that's running: "prerequest" for a pre-request script or "test" for a post-response script.

info.requestName

relay.info.requestName: string

The name of the request being sent.

info.requestId

relay.info.requestId: string

The id of the request being sent.

info.collectionName

relay.info.collectionName: string | undefined

The name of the request's collection, or undefined for a draft.

info.iteration

relay.info.iteration: number

The collection runner's iteration, which is always 0.

info.iterationCount

relay.info.iterationCount: number

The collection runner's number of iterations, which is always 1.

Controlling the send

execution.skipRequest()

relay.execution.skipRequest(): void

Stops the request from being sent. Pre-request scripts only.

execution.setNextRequest(name)

relay.execution.setNextRequest(name: string | null): void

Picks the collection runner's next request; it has no effect on a single send.

execution.location

relay.execution.location: string[]

The path of the item that's running, which is always empty.

Iteration data

iterationData.get(key)

relay.iterationData.get(key: string): undefined

Returns the value of key in the iteration's data, which is always undefined.

iterationData.has(key)

relay.iterationData.has(key: string): boolean

Returns whether the iteration's data has key, which is always false.

iterationData.toObject()

relay.iterationData.toObject(): object

Returns the iteration's data as an object, which is always empty.

iterationData.replaceIn(text)

relay.iterationData.replaceIn(text: string): string

Returns text unchanged.

Discussion

When a script calls skipRequest(), the script carries on to its end, but the pre-request scripts after it don't run and Relay doesn't send the request. Relay records the attempt in history as a failed response with the status text "Skipped by a pre-request script", and post-response scripts don't run. Calling skipRequest() in a post-response script throws an error.

The first time a script calls setNextRequest() in a send, Relay writes a note to the Console that it has no effect. relay.iterationData.set(), unset() and clear() throw an error.

See Also