Script API

Every script sees the globals under Every script. A request script also sees those under Every request script, and the request (and, after the response, the response) of its protocol and phase. The Wb…Body and Wb…Message types come from the request’s contract — the operation’s XSD elements, its OpenAPI schemas or its .proto messages — and are unknown when the request has none. WbSecretName is the union of the names the request lists under scripts.secrets. WbStatus is every HTTP status from 100 to 599 as a literal type, and WbRange1 to WbRange5 are its hundreds, so checking response.status narrows the response.

A Postman script (api: postman) is JavaScript and is checked for syntax only; its pm object is described in the Scripts guide.

A mock operation’s dispatch.ts sees Every script and Mock dispatch scripts, and nothing else: no vars, props, secrets or tests. WbResponseName is the union of the operation’s response names, so respond refuses a name the operation does not have.

Every script

declare const crypto: {
  hash(algorithm: 'md5' | 'sha1' | 'sha256' | 'sha512', data: string, encoding?: 'hex' | 'base64'): string;
  hmac(algorithm: 'sha1' | 'sha256' | 'sha512', key: string, data: string, encoding?: 'hex' | 'base64'): string;
  randomUUID(): string;
};
declare const encoding: {
  base64(text: string): string;
  fromBase64(text: string): string;
  base64url(text: string): string;
  urlEncode(text: string): string;
};
declare function log(...values: unknown[]): void;
declare const console: {
  log(...values: unknown[]): void;
  info(...values: unknown[]): void;
  warn(...values: unknown[]): void;
  error(...values: unknown[]): void;
  debug(...values: unknown[]): void;
};

Every request script

/** A case-insensitive list of headers (or gRPC metadata), in order. Names may repeat. */
interface WbPairs {
  get(name: string): string | undefined;
  getAll(name: string): string[];
  has(name: string): boolean;
  list(): { name: string; value: string }[];
  toObject(): Record<string, string>;
}
/** Headers a pre-request script can change. A value may not hold CR, LF or NUL. */
interface WbWritablePairs extends WbPairs {
  /** Replaces every entry of that name with one, where the first one was. */
  set(name: string, value: string): void;
  add(name: string, value: string): void;
  delete(name: string): void;
}

interface WbExpectation<T> {
  toBe(expected: T): void;
  toEqual(expected: T): void;
  toBeDefined(): void;
  toBeUndefined(): void;
  toBeNull(): void;
  toBeTruthy(): void;
  toBeFalsy(): void;
  toContain(item: T extends readonly (infer I)[] ? I : string): void;
  toMatch(pattern: RegExp | string): void;
  toBeGreaterThan(value: number): void;
  toBeLessThan(value: number): void;
  toHaveLength(length: number): void;
  toHaveProperty(path: string | readonly string[], value?: unknown): void;
  readonly not: Omit<WbExpectation<T>, 'not'>;
}

/** This run's values: set here, read by later requests as `${#Sequence#name}`. */
declare const vars: {
  get(name: string): string | undefined;
  /** A value is used exactly as set: never expanded, always escaped where it lands. */
  set(name: string, value: string | number | boolean, options?: { secret?: boolean }): void;
};
/** Resolved properties. A secret is never returned. */
declare const props: { get(name: string): string | undefined };
/** The secrets this request's `scripts.secrets` lists, and no others. */
declare const secrets: { get(name: WbSecretName): string };
/** Records a test; a failed `expect` inside it fails the test, and the script goes on. */
declare function test(name: string, check: () => void): void;
declare function expect<T>(actual: T): WbExpectation<T>;

REST: shared by both phases

interface WbRestQuery {
  get(name: string): string | undefined;
  getAll(name: string): string[];
  list(): { name: string; value: string }[];
}
interface WbWritableRestQuery extends WbRestQuery {
  set(name: string, value: string): void;
  add(name: string, value: string): void;
  delete(name: string): void;
}
interface WbRestBody {
  /** `other` is a form, multipart or binary body, which a script cannot read or change. */
  readonly kind: 'none' | 'text' | 'other';
  readonly text: string;
  readonly json: WbRequestBody;
}
interface WbResponseArm<S extends number, B> {
  readonly status: S;
  readonly statusText: string;
  readonly headers: WbPairs;
  readonly text: string;
  /** The body parsed as JSON, typed from the contract's response for this status. */
  json(): B;
  readonly durationMs: number;
}
interface WbWritableRestBody {
  readonly kind: 'none' | 'text' | 'other';
  text: string;
  json: WbRequestBody;
}

REST: pre-request

declare const request: {
  method: string;
  /** The full URL. A script may change the path, query and fragment, never the scheme, host or port. */
  url: string;
  readonly query: WbWritableRestQuery;
  readonly headers: WbWritablePairs;
  readonly body: WbWritableRestBody;
};

REST: post-response

declare const request: {
  readonly method: string;
  readonly url: string;
  readonly query: WbRestQuery;
  readonly headers: WbPairs;
  readonly body: WbRestBody;
};
declare const response: WbResponse;

SOAP: pre-request

declare const request: {
  readonly endpoint: string;
  soapAction: string;
  readonly headers: WbWritablePairs;
  /** The whole envelope, after property expansion and before WS-Addressing and WS-Security. */
  envelope: string;
  /** The SOAP body's element, typed from the operation's input message. */
  body: WbSoapRequestBody;
};

SOAP: post-response

declare const request: {
  readonly endpoint: string;
  readonly soapAction: string;
  readonly headers: WbPairs;
  readonly envelope: string;
  readonly body: WbSoapRequestBody;
};
declare const response: {
  readonly status: number;
  readonly headers: WbPairs;
  readonly envelope: string;
  readonly text: string;
  /** The SOAP body's element, typed from the operation's output message. */
  readonly body: WbSoapResponseBody;
  readonly fault?: { readonly code: string; readonly reason: string };
  /** Strings an XPath expression selects in the response envelope. */
  select(xpath: string, namespaces?: Record<string, string>): string[];
  readonly durationMs: number;
};

gRPC: pre-request

declare const request: {
  readonly target: string;
  readonly method: string;
  readonly metadata: WbWritablePairs;
  message: WbRequestMessage;
};

gRPC: post-response

declare const request: {
  readonly target: string;
  readonly method: string;
  readonly metadata: WbPairs;
  readonly message: WbRequestMessage;
};
declare const response: {
  readonly status: { readonly code: number; readonly name: string; readonly message: string };
  readonly metadata: WbPairs;
  readonly trailers: WbPairs;
  readonly message: WbResponseMessage | undefined;
  readonly durationMs: number;
};

Mock dispatch scripts

/** The request the mock received. */
declare const request: {
  /** The operation's key: a SOAP operation name, or REST `<method> <path>`. */
  readonly operation: string;
  /** Upper case. */
  readonly method: string;
  /** The path as received, without the query, percent-encoding kept. */
  readonly path: string;
  /** Each query parameter's values, in order, decoded. */
  readonly query: { readonly [name: string]: readonly string[] };
  /** Every header in order; names may repeat. */
  readonly headers: readonly (readonly [name: string, value: string])[];
  /** REST: the values of the operation path's parameters. Empty on SOAP. */
  readonly pathParams: { readonly [name: string]: string };
  /** The body as text, cut to its first MiB. */
  readonly body: string;
};
/** The operation's responses that may be sent in the current scenario states, in order. */
declare const responses: readonly { readonly id: string; readonly name: WbResponseName }[];
/** Scenario states. Every scenario starts in `Started`. */
declare const scenarios: {
  get(name: string): string;
  /** A name and a state hold only letters, digits, _, . and -, at most 64. */
  set(name: string, state: string): void;
};
/** Sends the named response. Without a call, the operation's default response is sent. */
declare function respond(name: WbResponseName): void;