@wirebench/engine 2.2.1 → 3.1.0

package/dist/run/run.js

@@ -5,17 +5,25 @@
  * picture, not the first thing that went wrong. An errored assertion outranks a failed one for the
  * request's outcome, because "we could not tell" is a different problem from "it is wrong".
  */
-import { evaluateAssertions } from '../assert/index.js';
-import { isWirebenchError } from '../errors.js';
-import { definitionCacheDir } from '../project/paths.js';
-import { sendRest } from '../rest/send.js';
-import { sendSoapRequest } from '../send.js';
-import { bindingContextFor, validateMessage } from '../validate/index.js';
-import { summarizeWsa } from '../wsa/policy-detect.js';
-import { parseWsdlBundle } from '../wsdl/merge.js';
-import { readDefinitionCache } from '../wsdl/cache.js';
-import { buildSchemaSet } from '../xsd/schema-set.js';
-import { prepareSend } from './prepare.js';
+import { sendAwaitingCallbacks } from '../assert/callback.js';
+import { checkRequestAssertions } from '../assert/check.js';
+import { isWirebenchError, WirebenchError } from '../errors.js';
+import { featureDisabled } from '../protocol/registry.js';
+import { defaultRegistry } from '../protocols.js';
+import { scriptProperties } from '../script/props.js';
+import { activeScripts } from '../script/request-scripts.js';
+import { SecretPlaceholders } from '../script/send.js';
+import { finishBaselineUpdate, planBaselineUpdate } from './baseline-update.js';
+import { BASELINE_PROTOCOLS, checkBaseline } from './baseline.js';
+import { scopesFor } from './context.js';
+import { openExchange } from './open.js';
+import { createRunTokenSource } from './oauth2-token.js';
+import { createRunScope, scopeWith } from './scope.js';
+import { listedSecrets, mergeScriptValues, scriptAssertions, scriptSession, } from './script-support.js';
+/** A request's own assertions; a gRPC request that never had any, and a protocol without them, carry none. */
+const assertionsOf = (item) => ('assertions' in item.request ? item.request.assertions : undefined) ?? [];
+/** A request's scripts, as saved; a protocol without scripts has none. */
+const scriptsOf = (item) => 'scripts' in item.request ? item.request.scripts : undefined;
 /** Enough of each exchange to keep for a report: a failing response can be megabytes. */
 const EXCHANGE_CAP_BYTES = 64 * 1024;
 function capped(bytes) {
@@ -33,138 +41,268 @@ function erroredResult(item, error) {
         outcome: 'errored',
         assertions: [],
         error,
-        unasserted: item.request.assertions.length === 0,
+        unasserted: assertionsOf(item).length === 0,
     };
 }
-function parseClark(clark) {
-    const match = /^\{([^}]*)\}(.*)$/.exec(clark);
-    return match === null
-        ? { namespaceUri: '', localName: clark }
-        : { namespaceUri: match[1] ?? '', localName: match[2] ?? '' };
+function outcomeOf(assertions) {
+    if (assertions.some((a) => a.outcome === 'errored'))
+        return 'errored';
+    if (assertions.some((a) => a.outcome === 'failed'))
+        return 'failed';
+    return 'passed';
+}
+/** The run facet of the module for `item`'s kind. */
+function runOf(registry, item) {
+    const run = registry.require(item.kind).run;
+    if (run === undefined) {
+        throw new Error(`The "${item.kind}" protocol cannot run requests`);
+    }
+    return run;
 }
 /**
- * Reads the interface's definition from `interfaces/<slug>/definition/`, as the app hydrates it
- * with `prefer-cache` — minus the network fallback: a run never fetches a WSDL. An interface that
- * does not cache its definition, or whose cache is absent or unreadable, has no contract here.
+ * 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.
  */
-async function loadDefinition(projectDir, iface) {
-    if (!iface.cacheDefinition) {
+export function deferredSession(scripting, scripted, context, options = {}) {
+    let opening;
+    const open = () => {
+        opening ??= listedSecrets(scripted.scripts.secrets, context.host.getSecret).then((secrets) => 
+        // The run records a value as it merges it (`mergeScriptValues`); nothing about the send is
+        // shown before that.
+        scriptSession(scripting, scripted, {
+            vars: context.sequence ?? {},
+            props: scriptProperties(scopesFor(context)),
+            secrets,
+        }, options));
+        return opening;
+    };
+    return {
+        pre: async (before) => (await open()).pre(before),
+        post: async (sent, response) => (await open()).post(sent, response),
+    };
+}
+/**
+ * Why a request's active scripts cannot run in this registry, as the error its send reports (spec
+ * §5.3, §9): the `scripts` feature is off, or the request's protocol has no scripting facet.
+ * Undefined when they can run, and for a protocol the registry does not hold: looking its module up
+ * refuses that request first, with the protocol's own `feature-disabled`.
+ */
+function scriptsRefusal(item, registry) {
+    const module = registry.find(item.kind);
+    if (module === undefined)
         return undefined;
+    if (!registry.features.isEnabled('scripts')) {
+        return featureDisabled(registry.features, 'scripts');
     }
-    try {
-        const bundle = await readDefinitionCache(definitionCacheDir(projectDir, iface.slug));
-        const definition = parseWsdlBundle(bundle);
-        return {
-            definition,
-            bundle,
-            schemaSet: buildSchemaSet(bundle),
-            defaultActionByOperation: summarizeWsa(definition).defaultActionByOperation,
-        };
-    }
-    catch {
-        return undefined;
+    if (module.scripting === undefined) {
+        return new WirebenchError('script-unsupported', `"${item.path}" has scripts, and ${item.kind} requests cannot have them`, {
+            details: { path: item.path, protocol: item.kind },
+        });
     }
+    return undefined;
 }
-function soapSubject(exchange, loaded, item) {
-    const fault = exchange.response?.fault;
-    const bodyText = exchange.response?.envelopeXml ?? new TextDecoder().decode(exchange.http.body);
-    const binding = loaded === undefined
-        ? undefined
-        : bindingContextFor(loaded.definition, { bindingName: parseClark(item.operation.bindingName), operationName: item.operation.name }, 'response');
-    const contentType = exchange.http.headers['content-type'];
-    return {
-        protocol: 'soap',
-        status: exchange.http.status,
-        durationMs: exchange.durationMs,
-        bodyText,
-        bodyKind: exchange.response?.isSoap === true ? 'xml' : 'other',
-        fault: {
-            present: fault !== undefined,
-            ...(fault !== undefined ? { summary: [fault.code, fault.reason].filter((s) => s.length > 0).join(' — ') } : {}),
-        },
-        ...(loaded !== undefined && binding !== undefined
-            ? {
-                validateContract: () => validateMessage({
-                    xml: bodyText,
-                    direction: 'response',
-                    schemaSet: loaded.schemaSet,
-                    bundle: loaded.bundle,
-                    binding,
-                    http: { ...(contentType !== undefined ? { contentType } : {}) },
-                }).then((r) => r.problems),
-            }
-            : {}),
+/**
+ * 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 function createRunSender(context) {
+    const registry = context.registry ?? defaultRegistry();
+    // One token source for the whole run: requests behind the same OAuth2 configuration share a token.
+    const host = {
+        ...context.host,
+        tokens: context.host.tokens ??
+            createRunTokenSource({
+                getSecret: context.host.getSecret,
+                ...(context.host.onSecretValue !== undefined ? { onSecretValue: context.host.onSecretValue } : {}),
+            }),
     };
-}
-function restSubject(exchange) {
-    return {
-        protocol: 'rest',
-        status: exchange.status,
-        durationMs: exchange.durationMs,
-        bodyText: exchange.text,
-        bodyKind: exchange.language === 'json' ? 'json' : exchange.language === 'xml' ? 'xml' : 'other',
+    const scope = createRunScope({ ...context, host });
+    return async (item, overrides = {}) => {
+        const itemContext = {
+            ...scope.context,
+            ...(overrides.sequence !== undefined ? { sequence: overrides.sequence } : {}),
+            ...(overrides.timeoutMs !== undefined ? { timeoutMs: overrides.timeoutMs } : {}),
+        };
+        const itemScope = scopeWith(scope, itemContext);
+        const run = runOf(registry, item);
+        const scripts = activeScripts(scriptsOf(item));
+        if (scripts === undefined) {
+            const sent = await openExchange(item, itemContext.host, { scope: itemScope, interactive: false, run: true })
+                .result;
+            return scriptsOf(item) !== undefined ? { ...sent, scriptsOff: true } : sent;
+        }
+        const refused = scriptsRefusal(item, registry);
+        if (refused !== undefined)
+            throw refused;
+        const scripting = context.scripting;
+        if (scripting === undefined) {
+            throw new WirebenchError('script-unavailable', `"${item.path}" has scripts, and this run cannot run them`, {
+                details: { path: item.path },
+            });
+        }
+        const scripted = {
+            protocol: item.kind,
+            path: item.path,
+            name: item.request.name,
+            slug: item.request.slug,
+            scripts,
+            types: await run.scriptTypes(item, itemScope),
+        };
+        await scripting.check(scripted);
+        return openExchange(item, itemContext.host, {
+            scope: itemScope,
+            interactive: false,
+            run: true,
+            scripts: { session: deferredSession(scripting, scripted, itemContext), placeholders: new SecretPlaceholders() },
+        }).result;
     };
 }
-function outcomeOf(assertions) {
-    if (assertions.some((a) => a.outcome === 'errored'))
-        return 'errored';
-    if (assertions.some((a) => a.outcome === 'failed'))
-        return 'failed';
-    return 'passed';
+/**
+ * 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 async function checkRunScripts(selected, context) {
+    const scripting = context.scripting;
+    const errors = [];
+    if (scripting === undefined)
+        return errors;
+    const registry = context.registry ?? defaultRegistry();
+    const scope = createRunScope(context);
+    for (const item of selected) {
+        const scripts = activeScripts(scriptsOf(item));
+        if (scripts === undefined)
+            continue;
+        const refused = scriptsRefusal(item, registry);
+        if (refused !== undefined) {
+            errors.push(refused);
+            continue;
+        }
+        try {
+            await scripting.check({
+                protocol: item.kind,
+                path: item.path,
+                name: item.request.name,
+                slug: item.request.slug,
+                scripts,
+                types: await runOf(registry, item).scriptTypes(item, scope),
+            });
+        }
+        catch (error) {
+            errors.push(isWirebenchError(error)
+                ? error
+                : new WirebenchError('script-type-error', error instanceof Error ? error.message : String(error)));
+        }
+    }
+    return errors;
+}
+/** The `--baseline` check for one sent request: `unsupported` for a protocol without goldens. */
+async function baselineOf(item, subject, baseline) {
+    if (!BASELINE_PROTOCOLS.has(item.kind)) {
+        return { report: { status: 'unsupported' } };
+    }
+    return checkBaseline(await baseline.source(item), subject, baseline.require);
+}
+/** The `--update-baseline` step for one sent request whose own outcome did not error. */
+async function baselineUpdateOf(item, subject, failed, update, containsKnownSecret) {
+    if (!BASELINE_PROTOCOLS.has(item.kind)) {
+        return { report: { status: 'unsupported' } };
+    }
+    const plan = planBaselineUpdate({
+        read: await update.source(item),
+        subject,
+        failed,
+        ...(containsKnownSecret !== undefined ? { containsKnownSecret } : {}),
+        now: () => new Date(),
+    });
+    if (plan.kind === 'done')
+        return plan.check;
+    let outcome;
+    try {
+        outcome = await update.sink(item, plan.golden);
+    }
+    catch (error) {
+        outcome = { status: 'failed', message: error instanceof Error ? error.message : String(error) };
+    }
+    return finishBaselineUpdate(plan.report, outcome);
 }
 /** Runs one request; a throw anywhere on the way becomes an errored result, never a stopped run. */
-async function runOne(item, context, options, definitionFor) {
+async function runOne(item, send, options, overrides, context) {
     try {
-        const loaded = item.kind === 'soap' ? await definitionFor(item.iface) : undefined;
-        const prepared = await prepareSend(item, {
-            ...context,
-            ...(loaded !== undefined
-                ? {
-                    defaultWsaActionFor: (s) => loaded.defaultActionByOperation[`${s.operation.bindingName}|${s.operation.name}`] ?? '',
-                }
-                : {}),
+        const own = assertionsOf(item);
+        // The cursor is taken inside this helper, before the send (§2.3 step 1).
+        const { sent, callbacks } = await sendAwaitingCallbacks(own, () => scopesFor({ ...context, ...(overrides.sequence !== undefined ? { sequence: overrides.sequence } : {}) }), () => send(item, overrides), {
+            ...(options.captures !== undefined ? { captures: options.captures } : {}),
+            ...(options.callbackClock !== undefined ? { clock: options.callbackClock } : {}),
+            ...(options.callbackPollMs !== undefined ? { pollIntervalMs: options.callbackPollMs } : {}),
+            ...(context.signal !== undefined ? { signal: context.signal } : {}),
+            onWaiting: (waiting) => options.onCallbackWaiting?.(item.path, waiting),
         });
-        let subject;
-        let raw;
-        if (prepared.kind === 'soap' && item.kind === 'soap') {
-            const exchange = await sendSoapRequest(prepared.input, { scopes: prepared.scopes });
-            subject = soapSubject(exchange, loaded, item);
-            raw = exchange.http;
-        }
-        else if (prepared.kind === 'rest') {
-            const exchange = await sendRest(prepared.input);
-            subject = restSubject(exchange);
-            raw = exchange;
-        }
-        else {
-            throw new Error('prepareSend returned a send of the wrong protocol');
-        }
-        const own = item.request.assertions;
-        const withDefault = options.defaultSlaMs !== undefined && !own.some((a) => a.type === 'sla')
-            ? [...own, { type: 'sla', maxMs: options.defaultSlaMs }]
-            : own;
-        const assertions = await evaluateAssertions(subject, withDefault);
-        const outcome = outcomeOf(assertions);
+        options.onSent?.(item, sent);
+        const { subject, raw, script } = sent;
+        const immediate = await checkRequestAssertions(subject, own, options.defaultSlaMs !== undefined ? { defaultSlaMs: options.defaultSlaMs } : {});
+        const checked = [...immediate, ...callbacks, ...scriptAssertions(script?.tests ?? [])];
+        // `--update-baseline` writes only for a request its own checks did not error (#217).
+        const ownOutcome = script?.error === undefined ? outcomeOf(checked) : 'errored';
+        const compared = options.baseline !== undefined
+            ? await baselineOf(item, subject, options.baseline)
+            : options.updateBaseline !== undefined && ownOutcome !== 'errored'
+                ? await baselineUpdateOf(item, subject, ownOutcome === 'failed', options.updateBaseline, context.containsKnownSecret)
+                : undefined;
+        const assertions = compared?.assertion !== undefined ? [...checked, compared.assertion] : checked;
+        const error = script?.error ?? compared?.error;
+        const outcome = error !== undefined ? 'errored' : outcomeOf(assertions);
         return {
-            ...identity(item),
-            outcome,
-            status: subject.status,
-            durationMs: subject.durationMs,
-            assertions,
-            unasserted: own.length === 0,
-            ...(outcome !== 'passed'
-                ? { exchange: { request: capped(raw.rawRequest), response: capped(raw.rawResponse) } }
-                : {}),
+            sent,
+            result: {
+                ...identity(item),
+                outcome,
+                status: subject.status,
+                durationMs: subject.durationMs,
+                assertions,
+                // The synthetic baseline assertion does not count: --require-assertions keeps its meaning.
+                unasserted: own.length === 0 && (script?.tests.length ?? 0) === 0,
+                ...(error !== undefined ? { error } : {}),
+                ...(compared !== undefined ? { baseline: compared.report } : {}),
+                ...scriptReport(script, sent.scriptsOff === true),
+                ...(outcome !== 'passed'
+                    ? { exchange: { request: capped(raw.rawRequest), response: capped(raw.rawResponse) } }
+                    : {}),
+            },
         };
     }
     catch (e) {
-        return erroredResult(item, {
-            code: isWirebenchError(e) ? e.code : 'internal-error',
-            message: e instanceof Error ? e.message : String(e),
-            ...(isWirebenchError(e) && e.details !== undefined ? { details: e.details } : {}),
-        });
+        return { result: erroredResult(item, errorOf(e)) };
     }
 }
+/** What a result reports of a request's scripts: their log, or that they were switched off. */
+export function scriptReport(script, scriptsOff) {
+    return {
+        ...(script !== undefined && script.log.lines.length > 0 ? { scriptLog: script.log.lines } : {}),
+        ...(scriptsOff ? { scriptsOff: true } : {}),
+    };
+}
+/** A thrown value as a result's `error`, with the engine's code when it has one. */
+export function errorOf(e) {
+    return {
+        code: isWirebenchError(e) ? e.code : 'internal-error',
+        message: e instanceof Error ? e.message : String(e),
+        ...(isWirebenchError(e) && e.details !== undefined ? { details: e.details } : {}),
+    };
+}
+/** A failed or errored exchange as a report keeps it: each side capped, not yet redacted. */
+export function cappedExchange(raw) {
+    return { request: capped(raw.rawRequest), response: capped(raw.rawResponse) };
+}
 /**
  * Sends `selected` in order and reports each. A request after an abort, or after the first
  * failure under `bail`, is `skipped` and never sent.
@@ -172,16 +310,10 @@ async function runOne(item, context, options, definitionFor) {
 export async function runRequests(selected, context, options = {}) {
     const started = performance.now();
     const startedAt = new Date().toISOString();
-    const definitions = new Map();
-    const definitionFor = (iface) => {
-        let loaded = definitions.get(iface.id);
-        if (loaded === undefined) {
-            loaded = loadDefinition(context.projectDir, iface);
-            definitions.set(iface.id, loaded);
-        }
-        return loaded;
-    };
+    const send = createRunSender(context);
     const results = [];
+    // Values scripts set, which later requests of the run read as `${#Sequence#name}` (#63).
+    const runValues = new Map(Object.entries(context.sequence ?? {}));
     let stopped = false;
     for (const item of selected) {
         let result;
@@ -190,14 +322,18 @@ export async function runRequests(selected, context, options = {}) {
                 ...identity(item),
                 outcome: 'skipped',
                 assertions: [],
-                unasserted: item.request.assertions.length === 0,
+                unasserted: assertionsOf(item).length === 0,
             };
         }
-        else if (item.request.assertions.length === 0 && options.requireAssertions === true) {
+        else if (assertionsOf(item).length === 0 &&
+            activeScripts(scriptsOf(item))?.post === undefined &&
+            options.requireAssertions === true) {
             result = erroredResult(item, { code: 'assertions-required', message: 'This request has no assertions.' });
         }
         else {
-            result = await runOne(item, context, options, definitionFor);
+            const ran = await runOne(item, send, options, { sequence: Object.fromEntries(runValues) }, context);
+            result = ran.result;
+            mergeScriptValues(runValues, ran.sent?.script?.values ?? [], context.host.onSecretValue, context.containsKnownSecret);
         }
         results.push(result);
         options.onRequestDone?.(result);
@@ -206,7 +342,10 @@ export async function runRequests(selected, context, options = {}) {
         }
     }
     const count = (outcome) => results.filter((r) => r.outcome === outcome).length;
-    const environment = context.project.environments.find((e) => e.id === context.environmentId)?.name;
+    const baselineCount = (status) => results.filter((r) => r.baseline?.status === status).length;
+    // Inside a workspace the environment a run names is the workspace's.
+    const environments = context.workspace?.workspace.environments ?? context.project.environments;
+    const environment = environments.find((e) => e.id === context.environmentId)?.name;
     return {
         startedAt,
         ...(environment !== undefined ? { environment } : {}),
@@ -217,6 +356,26 @@ export async function runRequests(selected, context, options = {}) {
             errored: count('errored'),
             skipped: count('skipped'),
             durationMs: Math.round(performance.now() - started),
+            ...(options.baseline !== undefined
+                ? {
+                    baseline: {
+                        matched: baselineCount('matched'),
+                        differs: baselineCount('differs'),
+                        missing: baselineCount('missing'),
+                    },
+                }
+                : {}),
+            ...(options.updateBaseline !== undefined
+                ? {
+                    baselineUpdate: {
+                        updated: baselineCount('updated'),
+                        created: baselineCount('created'),
+                        matched: baselineCount('matched'),
+                        skipped: baselineCount('skipped'),
+                        refused: baselineCount('refused'),
+                    },
+                }
+                : {}),
         },
         requests: results,
     };

package/dist/run/scope.d.ts

@@ -0,0 +1,11 @@
+/** What a protocol module is given for one run: the run's context and its one cache (spec §3.3). */
+import type { RunScope } from '../protocol/module.js';
+import type { RunContext } from './context.js';
+/**
+ * A scope for one run. `memo` keeps one value per key for the scope's lifetime: a compiled WSDL, a
+ * proto set, an OpenAPI document. A load that rejects is remembered too, since nothing in a run can
+ * fix a cache, and every later request behind the key reports the same error.
+ */
+export declare function createRunScope(context: RunContext): RunScope;
+/** `scope` with another context and the same cache: what one request of the run is sent with. */
+export declare function scopeWith(scope: RunScope, context: RunContext): RunScope;

package/dist/run/scope.js

@@ -0,0 +1,26 @@
+/**
+ * A scope for one run. `memo` keeps one value per key for the scope's lifetime: a compiled WSDL, a
+ * proto set, an OpenAPI document. A load that rejects is remembered too, since nothing in a run can
+ * fix a cache, and every later request behind the key reports the same error.
+ */
+export function createRunScope(context) {
+    const loads = new Map();
+    return {
+        context,
+        memo(key, load) {
+            const known = loads.get(key);
+            if (known !== undefined) {
+                return known;
+            }
+            const loading = load();
+            // Observed here so a rejection nobody awaits yet is never reported as unhandled.
+            loading.catch(() => undefined);
+            loads.set(key, loading);
+            return loading;
+        },
+    };
+}
+/** `scope` with another context and the same cache: what one request of the run is sent with. */
+export function scopeWith(scope, context) {
+    return { context, memo: (key, load) => scope.memo(key, load) };
+}

package/dist/run/script-support.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What a run needs to run a request's scripts (#63): the script's view of properties and listed
+ * secrets, and the results a report shows — tests as assertions, values for later requests.
+ */
+import type { AssertionResult } from '../assert/model.js';
+import { type GetSecret } from '../secrets/resolve.js';
+import type { RequestSnapshotBase, ResponseSnapshotBase } from '../protocol/module.js';
+import type { ScriptLog, ScriptTest, ScriptValue } from '../script/model.js';
+import { type RequestScripting, type ScriptedRequest, type ScriptRunValues } from '../script/request-scripts.js';
+/** What running a request's scripts produced, carried with the sent request. */
+export interface SentScripts {
+    readonly tests: readonly ScriptTest[];
+    readonly values: readonly ScriptValue[];
+    readonly log: ScriptLog;
+    /** A post-response script that failed: the response is kept, the request errors. */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/** The values of the secrets a request's scripts list. */
+export declare function listedSecrets(names: readonly string[], getSecret: GetSecret): Promise<Record<string, string>>;
+/** A script's tests as a report's assertions. */
+export declare function scriptAssertions(tests: readonly ScriptTest[]): AssertionResult[];
+/**
+ * Adds a script's values to a run's values. A value marked secret, or holding a credential the run
+ * knows, is reported for masking first (ADR-0015).
+ */
+export declare function mergeScriptValues(target: Map<string, string>, values: readonly ScriptValue[], onSecretValue: ((value: string) => void) | undefined, containsKnownSecret: ((value: string) => boolean) | undefined): void;
+/** One send's scripts: the pre-request script on the prepared request, the post-response script on the response. */
+export interface ScriptSession {
+    /**
+     * Runs the pre-request script, if there is one, on `before`; the request as it will be sent.
+     *
+     * @throws WirebenchError the script's failure: the request is not sent
+     */
+    readonly pre: <S extends RequestSnapshotBase>(before: S) => Promise<S>;
+    /**
+     * Runs the post-response script, if there is one, and returns what both scripts did. The
+     * post-response script sees the pre-request script's values; its failure is returned, not thrown.
+     */
+    readonly post: (sent: RequestSnapshotBase, response: ResponseSnapshotBase) => Promise<SentScripts>;
+}
+export interface ScriptSessionOptions {
+    /** Told each value a script sets that is secret, or holds a known secret, as soon as it is set. */
+    readonly onSecretValue?: (value: string) => void;
+    readonly containsKnownSecret?: (value: string) => boolean;
+}
+/**
+ * The scripts of one send of `scripted`. The run and the app both send through this, so a value a
+ * script marks secret is masked before anything about the send is shown, in either.
+ */
+export declare function scriptSession(scripting: RequestScripting, scripted: ScriptedRequest, values: ScriptRunValues, options?: ScriptSessionOptions): ScriptSession;