Skip to main content

Scripts overview

You can use scripts to automate tasks in the editor. Scripts can be written in Lua, JavaScript, or TypeScript.

  • Lua — wasmoon (Lua 5.1)
  • JavaScript / TypeScript — transpiled and executed by kulala-core

Current working directory​

The current working directory for scripts is:

  • the directory of the current HTTP file for inline scripts
  • the directory of the external script file for external scripts

Given the following folder structure:

.
├── http
│   └── example.http
│   └── example.js
│   └── example.lua
└── scripts
    └── my-script.js
    └── my-script.lua

The current working directory for my-script.js is the scripts directory, whereas the current working directory for example.js is the http directory.

All inline scripts are executed in the current working directory of the HTTP file, which is the http directory in this case.

Lua scripts​

Please read Lua scripting for more information.

Use lang=lua, lang=js, or lang=ts on inline script markers when needed, for example < {% lang=lua.

LSP support for auto completion​

For external scripts, you can use the kulala LSP to get auto completion for the client, request, response, test and assert objects.

To do this, add javascript/lua to lsp.filetypes in your Configuration options:

{
  opts = {
    lsp = {
      filetypes = { "http", "rest", "json", "yaml", "bruno", "javascript" }
    },
  },
}

Using npm modules in JavaScript scripts​

JavaScript and TypeScript scripts can require() npm packages when they are installed where kulala-core can resolve them (typically next to the script or HTTP file).

If you have a folder structure like this:

.
├── http
│   └── example.http
└── scripts
    └── my-script.js

You can use the require function to import modules in my-script.js:

const moment = require("moment");

as long as the module is installed in the same directory as the script, or globally.

The current working directory for my-script.js is the scripts directory.

So want to write a file in the http directory, you can use a relative path:

const fs = require("fs");
fs.writeFileSync("../http/my-file.txt", "Hello, world!");

Pre-request​

./pre-request-example.http
### REQUEST_ONE
< {%
  var crypto = require('crypto');
  var fs = require('fs');
  var TOKEN = fs.readFileSync('TOKEN.txt', 'utf8').trim();
  request.variables.set('GORILLA', TOKEN);
  request.variables.set('PASSWORD', crypto.randomBytes(16).toString('hex'));
%}
< ./pre-request.js
POST https://httpbin.org/post HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer Foo:bar

{
  "token": "{{GORILLA}}",
  "password": "{{PASSWORD}}",
  "deep": {
    "nested": [
      {
        "key": "foo"
      },
      {
        "key": "{{BONOBO}}"
      }
    ]
  }
}

###

### REQUEST_TWO
POST https://httpbin.org/post HTTP/1.1
accept: application/json
content-type: application/json

{
  "token": "{{REQUEST_ONE.response.body.$.json.token}}",
  "nested": "{{REQUEST_ONE.response.body.$.json.deep.nested[1].key}}",
  "gorilla": "{{GORILLA}}"
}
tip

Variables set via request.variables.set are only available in the current request.

./pre-request.js
client.global.set("BONOBO", "bar");
tip

Variables set via client.global.set are available in all requests and persist in kulala-core’s data store between Neovim sessions.

To clear a global variable, run lua require('kulala').scripts_clear_global('BONOBO').

See: scripts_clear_global.

./TOKEN.txt
THIS_IS_SOME_TOKEN_VALUE_123

Post-request​

./post-request-example.http
### REQUEST_ONE_
POST https://httpbin.org/post HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer Foo:bar

{
  "token": "SOME_TOKEN",
  "deep": {
    "nested": [
      {
        "key": "foo"
      }
    ]
  }
}

> {%
  var fs = require('fs');
  fs.writeFileSync('TOKEN.txt', response.body.json.token);
  client.global.set('GORILLA_TOKEN', response.body.json.token);
%}

###

### REQUEST_TWO_2_
POST https://httpbin.org/post HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "gorilla": "{{GORILLA_TOKEN}}"
}

> ./post-request.js

###

### REQUEST_THREE
POST https://httpbin.org/post HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "date_header_from_request_two": "{{BONOBO}}"
}
./post-request.js
client.global.set("BONOBO", response.headers.valueOf("Date"));
./pre-request-example.http
### REQUEST_ONE
< {%
  var crypto = require('crypto');
  var fs = require('fs');
  var TOKEN = fs.readFileSync('TOKEN.txt', 'utf8').trim();
  var PASSWORD = crypto.randomBytes(16).toString('hex');
  request.variables.set('GORILLA', TOKEN);
  request.variables.set('PASSWORD', PASSWORD);
  console.log(TOKEN)
  console.log(PASSWORD)
%}
< ./pre-request.js
POST https://httpbin.org/post HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer Foo:bar

{
  "token": "{{GORILLA}}",
  "password": "{{PASSWORD}}",
  "deep": {
    "nested": [
      {
        "key": "foo"
      },
      {
        "key": "{{BONOBO}}"
      }
    ]
  }
}

> {%
  var token = response.body.json.token
  var fs = require('fs');
  fs.writeFileSync('TOKEN.txt', token);
  client.global.set('GORILLA_TOKEN', token);
  console.log(token)
%}
tip

If you add console.log to script, the output will be displayed in the Script Output panel, when you have enabled the following configuration.

opts = {
  default_winbar_panes = { "body", "headers", "headers_body", "script_output" },
}