@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/run/open.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Opening and resolving one send through a protocol's run facet (spec §3.2). Apart from
+ * `exchange.ts` because it reads the built-in registry, whose modules build their handles there.
+ */
+import type { RunScope } from '../protocol/module.js';
+import type { SelectedRequest } from '../protocols.js';
+import type { ExchangeHandle, ExchangeOptions } from './exchange.js';
+import type { SendHost } from './host.js';
+/** Opens one send of `item` through its protocol's run facet (spec §3.2). */
+export declare function openExchange(item: SelectedRequest, host: SendHost, options: ExchangeOptions): ExchangeHandle;
+/** What a send of `item` would send, resolved and not connected (spec §3.3). */
+export declare function resolveExchange(item: SelectedRequest, host: SendHost, scope: RunScope): Promise<unknown>;

package/dist/run/open.js

@@ -0,0 +1,16 @@
+import { defaultRegistry } from '../protocols.js';
+function runFacet(item, scope) {
+    const registry = scope.context.registry ?? defaultRegistry();
+    const run = registry.require(item.kind).run;
+    if (run === undefined)
+        throw new Error(`The "${item.kind}" protocol cannot run requests`);
+    return run;
+}
+/** Opens one send of `item` through its protocol's run facet (spec §3.2). */
+export function openExchange(item, host, options) {
+    return runFacet(item, options.scope).open(item, options.scope, host, options);
+}
+/** What a send of `item` would send, resolved and not connected (spec §3.3). */
+export function resolveExchange(item, host, scope) {
+    return runFacet(item, scope).resolve(item, scope, host);
+}

package/dist/run/run.d.ts

@@ -1,17 +1,33 @@
-import type { AssertionResult } from '../assert/model.js';
-import type { RunContext } from './prepare.js';
-import type { SelectedRequest } from './select.js';
+import type { CallbackClock, CallbackWaiting } from '../assert/callback.js';
+import type { CaptureSource } from '../assert/capture-source.js';
+import type { AssertionResult, AssertionSubject } from '../assert/model.js';
+import { WirebenchError } from '../errors.js';
+import type { SelectedRequest, SentExchange } from '../protocols.js';
+import type { GoldenFile, GoldenRead, GoldenWrite } from '../snapshot/golden-file.js';
+import { type RequestScripting, type ScriptedRequest } from '../script/request-scripts.js';
+import type { TransferResult } from '../sequence/run.js';
+import type { BaselineReport } from './baseline.js';
+import type { RunContext } from './context.js';
+import { type ScriptSession, type ScriptSessionOptions, type SentScripts } from './script-support.js';
+export type { LiveEvent, SentExchange } from '../protocols.js';
 export type RequestOutcome = 'passed' | 'failed' | 'errored' | 'skipped';
+/** Reads the golden saved for a selected request (#36); the host knows where the project is saved. */
+export type BaselineSource = (item: SelectedRequest) => Promise<GoldenRead>;
+/** Saves a golden for a selected request (#217); the host knows where the project is saved. */
+export type BaselineSink = (item: SelectedRequest, golden: GoldenFile) => Promise<GoldenWrite>;
 /** What happened to one selected request. */
 export interface RequestResult {
     readonly path: string;
     readonly group: string;
     readonly name: string;
-    readonly protocol: 'soap' | 'rest';
+    /** The request's kind, as its module registered it. */
+    readonly protocol: string;
     readonly outcome: RequestOutcome;
     readonly status?: number;
     readonly durationMs?: number;
     readonly assertions: readonly AssertionResult[];
+    /** The `--baseline` comparison (#36); absent when not asked for, or when the send failed. */
+    readonly baseline?: BaselineReport;
     /** Set when errored before or during the send. */
     readonly error?: {
         readonly code: string;
@@ -25,6 +41,20 @@ export interface RequestResult {
         readonly request: string;
         readonly response: string;
     };
+    /** Set when this is a sequence step: which sequence, and which of its steps. */
+    readonly sequence?: {
+        readonly id: string;
+        readonly name: string;
+        readonly stepId: string;
+    };
+    /** A sequence step's transfers. A secret one carries no value. */
+    readonly transfers?: readonly TransferResult[];
+    /** Where the request went, for a sequence step. */
+    readonly origin?: string;
+    /** What the request's scripts logged, capped. NOT yet redacted. */
+    readonly scriptLog?: readonly string[];
+    /** True when the request has scripts and they are switched off, so none ran. */
+    readonly scriptsOff?: boolean;
 }
 export interface RunSummary {
     readonly total: number;
@@ -33,6 +63,20 @@ export interface RunSummary {
     readonly errored: number;
     readonly skipped: number;
     readonly durationMs: number;
+    /** Set when the run compared baselines (#36). */
+    readonly baseline?: {
+        readonly matched: number;
+        readonly differs: number;
+        readonly missing: number;
+    };
+    /** Set when the run updated baselines (#217). */
+    readonly baselineUpdate?: {
+        readonly updated: number;
+        readonly created: number;
+        readonly matched: number;
+        readonly skipped: number;
+        readonly refused: number;
+    };
 }
 export interface RunResult {
     readonly startedAt: string;
@@ -44,8 +88,84 @@ export interface RunOptions {
     readonly bail?: boolean;
     readonly defaultSlaMs?: number;
     readonly requireAssertions?: boolean;
+    /** Compare each response with its golden (#36). Sequence steps never are. */
+    readonly baseline?: {
+        readonly source: BaselineSource;
+        readonly require: boolean;
+    };
+    /** Save each changed response as its golden (#217). Never set with `baseline`; sequence steps never are. */
+    readonly updateBaseline?: {
+        readonly source: BaselineSource;
+        readonly sink: BaselineSink;
+    };
     readonly onRequestDone?: (result: RequestResult) => void;
+    /** Where callback assertions read captures (callback-assertion §2.2). Absent: they error, and the run goes on. */
+    readonly captures?: CaptureSource;
+    /** The clock callback waits poll by; a test seam. */
+    readonly callbackClock?: CallbackClock;
+    /** How often a waiting callback polls; `CALLBACK_LIMITS.pollIntervalMs` by default. A test seam. */
+    readonly callbackPollMs?: number;
+    /** Called after a request's send when it has callbacks to wait for. */
+    readonly onCallbackWaiting?: (path: string, waiting: readonly CallbackWaiting[]) => void;
+    /**
+     * Called once for each request that got a response: after the send and after any callback wait,
+     * before the request's other assertions are evaluated. It is not called when the send throws, nor
+     * when the callback wait throws. A host that records the send (the command line's `send` writes
+     * History) reads the exchange here.
+     */
+    readonly onSent?: (item: SelectedRequest, sent: SentRequest) => void;
+}
+/** One request as a run sends it: the response as assertions see it, and what a report keeps. */
+export interface SentRequest {
+    readonly subject: AssertionSubject;
+    readonly raw: {
+        readonly rawRequest: Uint8Array;
+        readonly rawResponse: Uint8Array;
+    };
+    /** The whole exchange, of whichever protocol sent it. */
+    readonly exchange?: SentExchange;
+    /** Where the request went: a URL's origin, or a gRPC target. */
+    readonly origin?: string;
+    /** What the request's scripts produced (#63). */
+    readonly script?: SentScripts;
+    /** True when the request has scripts and they are switched off. */
+    readonly scriptsOff?: boolean;
 }
+/** What a run's sender may change for one request. */
+export type RunSendOverrides = Pick<RunContext, 'sequence' | 'timeoutMs'>;
+/** Sends one selected request as a run does. Throws what preparing or sending throws. */
+export type RunRequestSender = (item: SelectedRequest, overrides?: RunSendOverrides) => Promise<SentRequest>;
+/**
+ * The scripts of one send, opened when the module first runs one. The secrets a request lists for
+ * its scripts are read then and not before, so they are asked for after everything resolving the
+ * request asks for, and before anything connecting it does. Exported for the desktop's sends,
+ * which pass `options` to record each secret value a script sets as the app's other sends do.
+ */
+export declare function deferredSession(scripting: RequestScripting, scripted: ScriptedRequest, context: RunContext, options?: ScriptSessionOptions): ScriptSession;
+/**
+ * A sender for one run: whatever a protocol loads for a container (a definition, a schema, an
+ * OpenAPI document) is loaded once, and one OAuth2 token source serves every request behind the same
+ * configuration. `runRequests` sends through it, and so does a sequence run, so a step is sent
+ * exactly as a selected request is. Which protocol sends a request is the registry's answer
+ * (`context.registry`, the built-in protocols by default).
+ *
+ * A request with scripts (#63) is type-checked first; its module then resolves it with its secrets
+ * behind placeholders, runs the pre-request script on that, puts the secrets back, connects, sends,
+ * and runs the post-response script on the response.
+ */
+export declare function createRunSender(context: RunContext): RunRequestSender;
+/**
+ * Type-checks the scripts of every selected request before a run sends anything (spec
+ * §Type-checking): each request whose scripts are switched on, against its own contract's types.
+ * Returns one error per request that fails, in selection order; empty when all pass.
+ */
+export declare function checkRunScripts(selected: readonly SelectedRequest[], context: RunContext): Promise<readonly WirebenchError[]>;
+/** What a result reports of a request's scripts: their log, or that they were switched off. */
+export declare function scriptReport(script: SentScripts | undefined, scriptsOff: boolean): Pick<RequestResult, 'scriptLog' | 'scriptsOff'>;
+/** A thrown value as a result's `error`, with the engine's code when it has one. */
+export declare function errorOf(e: unknown): NonNullable<RequestResult['error']>;
+/** A failed or errored exchange as a report keeps it: each side capped, not yet redacted. */
+export declare function cappedExchange(raw: SentRequest['raw']): NonNullable<RequestResult['exchange']>;
 /**
  * Sends `selected` in order and reports each. A request after an abort, or after the first
  * failure under `bail`, is `skipped` and never sent.