js

package
v0.7.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package js runs a scenario written as a JavaScript or TypeScript file, using the embedded Goja ECMAScript runtime — no Node.js, no network fetch of a runtime, and no separate build step for the author. A scenario file exports a default function:

export default function () {
  // one iteration's worth of work
}

A .ts file is accepted too: it is transpiled to JavaScript (types stripped, ESM import/export rewritten to a form this package can read back out) with esbuild before Goja ever sees it. esbuild is a committed dependency of this binary, not an external tool — nothing about this package requires Node, npm, or network access to work.

AGENTS.md's first rule is that a test is always a real file; this package's whole job is turning that file into something the engine can call for a VU. Per FR-CLI-08, a VU also gets real HTTP and WebSocket access via the global `http` and `ws` objects described below, backed by internal/scripting/netapi — this package still knows nothing about gRPC, and nothing about FR-CLI-06's allowlist policy itself, only that NewVU is given a netapi.SafetyCheck to run before every call.

A scenario can carry a value from one call into the next the way FR-CLI-08's LaunchPad example needs to:

export default function () {
  const created = http.post("http://localhost:8080/launches", { body: JSON.stringify({name: "demo"}) });
  const launch = created.json();
  const conn = ws.connect("ws://localhost:8080/launches/" + launch.id + "/ignite");
  conn.send(JSON.stringify({action: "ignite"}));
  for (;;) {
    const frame = conn.receive(5000);
    if (frame === null) break; // connection closed
    const msg = JSON.parse(frame);
    if (msg.status === "complete" || msg.status === "aborted") break;
  }
  conn.close();
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Option added in v0.4.0

type Option func(*VU)

Option changes how NewVU builds a VU. An option is needed, rather than a setter called afterwards, when the script's top-level code has to see it: the top level runs inside NewVU.

func WithInputs added in v0.4.0

func WithInputs(in netapi.Inputs) Option

WithInputs exposes the `env` and `data` globals (FR-CLI-17). Without it, `env` is an empty object and `data` has no files.

type Script

type Script struct {
	// contains filtered or unexported fields
}

Script is a loaded, compiled scenario file, ready to be instantiated into any number of VUs.

func Load

func Load(path string) (*Script, error)

Load reads and compiles the scenario file at path. A .ts, .tsx, or .jsx file is transpiled first; anything else is treated as plain JavaScript. Load returns an error for anything that stops every VU identically — a missing file, a syntax error, a transpile failure — so the caller can fail the whole run immediately instead of discovering it only when the first VU starts.

func (*Script) NewVU

func (s *Script) NewVU(check netapi.SafetyCheck, timeout time.Duration, opts ...Option) (*VU, error)

NewVU creates a fresh VU from the script: a new runtime, the script's top-level code run once (so top-level state like a counter declared with let/const starts fresh for this VU), its default export resolved and validated, and the `http`/`ws` globals wired up.

check is run (if non-nil) against the host of every call a script makes through http or ws, before connecting — see internal/scripting/netapi.SafetyCheck's doc comment for why this has to happen per call rather than once up front. timeout bounds each individual HTTP request and WebSocket handshake; it does not bound ws.receive, which takes its own optional timeout argument.

type VU

type VU struct {
	// contains filtered or unexported fields
}

VU is one virtual user's instance of a Script: its own Goja runtime running its own copy of the script's top-level state, the default export function pulled out of it, and (per FR-CLI-08) its own HTTP client and set of open WebSocket connections, scoped to this VU's lifetime the same way the VU's own runtime is. A goja.Runtime is not safe for concurrent use, so the engine must create one VU per virtual user via NewVU — never share a single VU across goroutines.

func (*VU) Close

func (v *VU) Close() error

Close releases v's resources: the VU's HTTP client's idle connections and every WebSocket connection it ever opened via ws.connect, even one a script never explicitly closed itself.

func (*VU) Iteration

func (v *VU) Iteration(ctx context.Context) error

Iteration runs the script's default export once. It implements engine.IterationFunc's signature (func(context.Context) error) directly, so a *VU can be used anywhere the engine wants one, without an adapter: `executor.Run(ctx, vu.Iteration, recorder)`.

ctx is also what every http/ws call this iteration makes uses to bound and cancel itself — it's stashed on v for the native functions above to read, since goja.FunctionCall gives them no way to receive it directly.

If ctx is cancelled while the function is running, Iteration interrupts the runtime and returns promptly instead of waiting for a runaway script to finish on its own.

func (*VU) SetCheckRecorder added in v0.4.0

func (v *VU) SetCheckRecorder(rec netapi.CheckRecorder)

SetCheckRecorder sets where this VU reports the outcome of every check() its script makes. Call it before the first Iteration. With no recorder (or nil), check() still runs the tests and returns the result, but nothing is counted.

func (*VU) SetStepRecorder added in v0.6.0

func (v *VU) SetStepRecorder(rec netapi.StepRecorder)

SetStepRecorder sets where this VU reports the timing and outcome of every step() its script runs. Call it before the first Iteration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL