Scripts #

Yaade provides the ability to execute scripts written in a sandboxed version of JavaScript. It is sandboxed because most JavaScript functionality is deactivated, like calls to window or document to prevent potentially malicious code.

Some valid functionality includes:

const x = 2 * 5
let y = "hello world"
const s = y.split(" ")
if (s.length === 2) {
    y = `foo=${s[0]}`
}
const j = s.join("_")

But the following commands are not valid:

import "..."
window.localStorage
console.log("hello world")
const cookies = document.cookie

Execution Order #

There are four types of scripts that are executed in the following order:

1. Collection-level Request Script
2. Request Script
3. Response Script
4. Collection-level Response Script

As other requests can be executed in the request scripts, the scripts are executed in a depth-first manner. This means that if a request script executes another request, the request script of the target request is executed before the response script of the source request.

Example:

// Request Script of Request 1
await exec(2)
// ... more code

Now if request 1 is executed, the execution order is as follows:

1. Collection-level Request Script of Request 1
2. First part of Request Script of Request 1
3. Collection-level Request Script of Request 2
4. Request Script of Request 2
5. Response Script of Request 2
6. Collection--level Response Script of Request 2
7. The rest of Request Script of Request 1
8. Response Script of Request 1
9. Collection-level Response Script of Request 1

Special Commands #

Listed below are special commands available in scripts run in Yaade.

Set Environment Variables #

The env.set function allows you to set a variable in the currently selected environment.

env.set("hello", "world")
env.set("foo", "bar" + "buz")

Get Environment Variables #

Just like you are able to set an environment variable env.get allows you to get an existing variable.

const foo = env.get("bar")

JSON Path #

The jp function allows you to traverse a JSON object using a JSON-Path expression. Check out the original proposal or the jsonpath npm library for detailed examples.

env.set("token", jp("$.access_token", res.body))

Logging #

The log function provides a basic way for logging. It logs into the console and prepends some information about execution environment, like request id and environment name. The structure of this info is [<script type>: <request id> - <environment>] <logging-content>.

const o = {"foo": "bar"}
log("hello world")
// output: [Request Script: 2 - dev] hello world {foo: 'bar'}

DateTime #

The DateTime object allows you to work with dates and times in scripts. It is a direct reference to the DateTime object of Luxon. Check out the Luxon example page for detailed examples.

const now = DateTime.utc().toISO()
// result: 2023-03-26T12:43:37.956Z

Request Scripts #

Request scripts are executed before sending a request. Following are commands that can exclusively be used in request scripts.

Execute another Request #

Request scripts allow you to execute other requests before the actual request is sent. This provides a powerful tool to chain requests. The signature of the command is very simple: const exec: (requestId: number, envName?: string) => Promise<unknown>. Because exec is asynchronous one can use await to wait for the result of the command.

// A simple example to extract a JWT from the response of another request
const res = await exec(15, env.name)
if (res.status === 200) {
    env.set("token", jp("$.accessToken", res.body))
}

The environment name should match an existing environment in the collection of the request to be executed. To use the same name as the currently selected environment of the source request, use env.name. If left blank, no environment will be used for interpolation.

The result of a successful exec call is the response of the target request. It contains the body as a string, headers as an object with keys and values and status code as integer.

const res = await exec(12)
const headers = res.headers
const contentType = headers["Content-Type"]
const body = res.body
const status = res.status
if (status === 200) {
    env.set("type", contentType)
}

Access the Request #

The req object exposes the request that will be sent. The request itself is immutable though and can only be changed by changing the environment. The request script is executed before the interpolation step, therefore the req object won't contain the resolved environment variables.

const uri = req.uri // string of the request URI
const headers = req.headers // map of key value pairs
const body = req.body // body as string
const method = req.method // string of the request method for REST requests

Response Scripts #

Response scripts are executed after a request has been sent. Following are commands that can exclusively be used in response scripts.

Access the Response #

The res object exposes the response received when executing the request. It contains the body as a string, headers as an object with keys and values and status code as integer.

const headers = res.headers
const contentType = headers["Content-Type"]
const body = res.body
const status = res.status
if (status === 200) {
    env.set("type", contentType)
}