lambder 14.1.1 → 15.0.2

package/dist/testing/LambderTestApp.d.ts

@@ -10,6 +10,13 @@ import type { LambderSessionStore } from "../shared/contracts/LambderSessionStor
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
 import type { LambderCallSummary } from "../core/LambderCallSummary.js";
+import { LambderMemoryCache } from "../stores/LambderMemoryCache.js";
+import { LambderMemoryOneShotSecretStore } from "../stores/LambderMemoryOneShotSecretStore.js";
+import { LambderMemoryUploadBucket } from "../stores/LambderMemoryUploadBucket.js";
+import type { LambderDdbCache } from "../stores/LambderDdbCache.js";
+import type { LambderDdbOneShotSecretStore } from "../stores/LambderDdbOneShotSecretStore.js";
+import type { LambderS3UploadBucket } from "../stores/LambderS3UploadBucket.js";
+import type { LambderMockApp } from "../mock/LambderMockApp.js";
 import { LambderTestVisitor, type LambderTestVisitorArgs, type LambderTestVisitorOptions } from "./LambderTestVisitor.js";
 /**
  * What a test app may be told. Nothing is required: `lambderTestApp(lambder)`
@@ -17,7 +24,9 @@ import { LambderTestVisitor, type LambderTestVisitorArgs, type LambderTestVisito
  *
  * The stores sit where create() takes them (`session.store`,
  * `rateLimits.limiter`, `idempotency.store`, `files`), naming only the part a
- * test replaces; everything else the app configured there stays in force.
+ * test replaces; everything else the app configured there stays in force. One
+ * given for a subsystem the app was created without throws, naming the
+ * option.
  */
 export type LambderTestAppOptions = {
     /** The host visitors browse unless they name their own. Default: "localhost". An app that scopes its session cookie to a domain needs a host under it. */
@@ -44,6 +53,16 @@ export type LambderTestAppOptions = {
     };
     /** Default: the app's own source, which suits one that reads a local folder. Pass a LambderLocalFileSource over fixtures for an app whose production source is S3 or HTTP. */
     files?: LambderFileSource;
+    /**
+     * The mock apps that answer the app's invoke callers, by the function
+     * name each caller was built with. A LambderInvokeCaller built without a
+     * transport is answered by the mock its function has here, through
+     * lambderMockInvokeTransport; with none, every call it makes fails,
+     * naming the function. Default: none.
+     */
+    invokeMocks?: {
+        [functionName: string]: Pick<LambderMockApp<any>, "handleRequest">;
+    };
 };
 /**
  * A Lambder instance as a test app takes it: any instance, read for its
@@ -72,6 +91,15 @@ export type LambderTestedInstance<TSessionData, TContract> = Pick<Lambder<any, a
  * What the app reaches on its own (its database, a mailer) is the app's to
  * replace.
  *
+ * The Lambder classes an app builds itself, beside the instance, are put
+ * under test too, wherever they were built: each LambderDdbCache,
+ * LambderDdbOneShotSecretStore and LambderS3UploadBucket answers from a
+ * memory twin of its own (see memoryTwinOf), and each LambderInvokeCaller
+ * built without a transport from the mock app `invokeMocks` names for its
+ * function. Those classes register themselves as they are constructed, so
+ * one built before the test app and one built after (in a handler, say) are
+ * both reached.
+ *
  * The sibling of LambderMockApp, which serves a contract from mock handlers:
  * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
  * real handlers.
@@ -82,6 +110,8 @@ export type LambderTestedInstance<TSessionData, TContract> = Pick<Lambder<any, a
  *
  * One test app per instance: a second one puts its own stores under the same
  * instance and takes over its crash watch, so the first stops seeing either.
+ * The app's own classes are the process's rather than an instance's, so the
+ * test app created last puts its twins under every one of them.
  */
 export declare class LambderTestApp<TContract extends LambderApiContractShape = any, TSessionData = any> {
     /** The instance's handler: what `event()` and every visitor call. */
@@ -98,6 +128,8 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
     private readonly wiring;
     /** The memory stores this test app made itself, which reset() empties. One the test supplied is the test's: nothing here knows what else holds it. */
     private readonly ownStores;
+    /** The twin under each of the app's own stores, by the store, for memoryTwinOf and reset. */
+    private readonly memoryTwins;
     private visitorCount;
     private resetCount;
     private readonly crashList;
@@ -126,6 +158,31 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
      * have been handed, collected here instead of written to stdout.
      */
     get callSummaries(): readonly LambderCallSummary[];
+    /**
+     * Fails every test that leaves a crash behind: installs, through the
+     * runner's own `afterEach`, a check that throws when `crashes` is not
+     * empty, listing each crash with its stack. The crashes it reports are
+     * forgotten, so the next test starts clean whether or not it resets. A
+     * test that provokes a crash on purpose asserts on `crashes` and ends
+     * with `reset()`.
+     *
+     * ```typescript
+     * const app = lambderTestApp(lambder);
+     * app.assertNoCrashesAfterEach(afterEach);
+     * ```
+     */
+    assertNoCrashesAfterEach(afterEach: (check: () => void) => unknown): void;
+    /**
+     * The memory twin under one of the app's own stores, to seed, inspect or
+     * drive: what the app's LambderDdbCache, LambderDdbOneShotSecretStore or
+     * LambderS3UploadBucket answers from under this test app. An upload
+     * test hands the bucket twin's handleStorageRequest the request a
+     * client would send to the ticket's URL. Throws for anything this test
+     * app put no twin under.
+     */
+    memoryTwinOf(cache: LambderDdbCache): LambderMemoryCache;
+    memoryTwinOf(store: LambderDdbOneShotSecretStore): LambderMemoryOneShotSecretStore;
+    memoryTwinOf(bucket: LambderS3UploadBucket): LambderMemoryUploadBucket;
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
     get sessionManager(): LambderSessionManager<TSessionData>;
     /**
@@ -140,8 +197,8 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
      * no login endpoint has to exist or be called.
      *
      * ```typescript
-     * const admin = await app.signIn("user:ada", { userId: "ada", role: "admin" });
-     * expect(await admin.api("org.rename", { name })).toEqual({ ok: true });
+     * const owner = await app.signIn("user:ada", { userId: "ada", role: "owner" });
+     * expect(await owner.api("store.rename", { name })).toEqual({ ok: true });
      * ```
      */
     signIn<TProvidedGuards extends string = never>(sessionKey: string, data: TSessionData, ...[options]: LambderTestVisitorArgs<LambderTestVisitorOptions<TContract, TProvidedGuards> & {
@@ -168,10 +225,11 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
     event(event: unknown, context?: Partial<Context>): Promise<unknown>;
     /**
      * Rewinds what accumulated: sessions, rate-limit counters and replay
-     * records in the stores this test app made, the crashes and call
-     * summaries it recorded, and the cookies of every visitor it created
-     * (each empties its jar the next time it is used). For a beforeEach. The
-     * app's own data (its database) is the app's to rewind.
+     * records in the stores this test app made, the memory twins under the
+     * app's own stores, the crashes and call summaries it recorded, and the
+     * cookies of every visitor it created (each empties its jar the next
+     * time it is used). For a beforeEach. The app's own data (its database)
+     * is the app's to rewind, and so are the invoke mocks.
      */
     reset(): void;
 }

package/dist/testing/LambderTestApp.js

@@ -6,6 +6,11 @@ import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { LambderMemoryIdempotencyStore } from "../stores/LambderMemoryIdempotencyStore.js";
 import { LambderMemoryRateLimiter } from "../stores/LambderMemoryRateLimiter.js";
 import { LambderMemorySessionStore } from "../stores/LambderMemorySessionStore.js";
+import { LambderMemoryCache } from "../stores/LambderMemoryCache.js";
+import { LambderMemoryOneShotSecretStore } from "../stores/LambderMemoryOneShotSecretStore.js";
+import { LambderMemoryUploadBucket } from "../stores/LambderMemoryUploadBucket.js";
+import { lambderMockInvokeTransport } from "../mock/lambderMockInvokeTransport.js";
+import { liveSwappableInstances, watchSwappableInstances } from "../shared/util/LambderSwappableInstances.js";
 import { LambderTestVisitor } from "./LambderTestVisitor.js";
 /**
  * A real Lambder app under test: the instance an app already has, with memory
@@ -20,6 +25,15 @@ import { LambderTestVisitor } from "./LambderTestVisitor.js";
  * What the app reaches on its own (its database, a mailer) is the app's to
  * replace.
  *
+ * The Lambder classes an app builds itself, beside the instance, are put
+ * under test too, wherever they were built: each LambderDdbCache,
+ * LambderDdbOneShotSecretStore and LambderS3UploadBucket answers from a
+ * memory twin of its own (see memoryTwinOf), and each LambderInvokeCaller
+ * built without a transport from the mock app `invokeMocks` names for its
+ * function. Those classes register themselves as they are constructed, so
+ * one built before the test app and one built after (in a handler, say) are
+ * both reached.
+ *
  * The sibling of LambderMockApp, which serves a contract from mock handlers:
  * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
  * real handlers.
@@ -30,6 +44,8 @@ import { LambderTestVisitor } from "./LambderTestVisitor.js";
  *
  * One test app per instance: a second one puts its own stores under the same
  * instance and takes over its crash watch, so the first stops seeing either.
+ * The app's own classes are the process's rather than an instance's, so the
+ * test app created last puts its twins under every one of them.
  */
 export class LambderTestApp {
     /** The instance's handler: what `event()` and every visitor call. */
@@ -46,6 +62,8 @@ export class LambderTestApp {
     wiring;
     /** The memory stores this test app made itself, which reset() empties. One the test supplied is the test's: nothing here knows what else holds it. */
     ownStores = [];
+    /** The twin under each of the app's own stores, by the store, for memoryTwinOf and reset. */
+    memoryTwins = new WeakMap();
     visitorCount = 0;
     resetCount = 0;
     crashList = [];
@@ -74,9 +92,50 @@ export class LambderTestApp {
             sessionStore, rateLimiter, idempotencyStore, fileSource: options.files,
             callSummary: (summary) => { this.callSummaryList.push(summary); },
         });
+        // A store given for a subsystem the app does not have would be put
+        // under nothing: the suite it was meant for would run over no store
+        // while reading as if it ran over that one.
+        if (options.session?.store && !swap.sessions) {
+            throw new Error("lambderTestApp: the session.store option was given, but the app was created without sessions, so nothing reads sessions to put a store under.");
+        }
+        if (options.rateLimits?.limiter && !swap.rateLimits) {
+            throw new Error("lambderTestApp: the rateLimits.limiter option was given, but the app was created without rate limits, so nothing counts calls to put a limiter under.");
+        }
+        if (options.idempotency?.store && !swap.idempotency) {
+            throw new Error("lambderTestApp: the idempotency.store option was given, but the app was created without idempotency, so nothing records answers to put a store under.");
+        }
         if (options.files && !swap.files) {
             throw new Error("lambderTestApp: the files option was given, but the app was created without one, so nothing reads files to put a source under.");
         }
+        const invokeMocks = options.invokeMocks ?? {};
+        for (const [functionName, mockApp] of Object.entries(invokeMocks)) {
+            if (typeof mockApp?.handleRequest !== "function") {
+                throw new Error(`lambderTestApp: invokeMocks["${functionName}"] is not a LambderMockApp (what initLambderMock().create() returns).`);
+            }
+        }
+        // Every one of the app's own classes alive now, and every one
+        // constructed from now on, until another test app takes over.
+        const putTwinUnder = (swappable) => {
+            const kept = (twin) => { this.memoryTwins.set(swappable.instance, twin); return twin; };
+            const twins = {
+                cache: (cacheOptions) => kept(new LambderMemoryCache(cacheOptions)),
+                oneShotSecretStore: () => kept(new LambderMemoryOneShotSecretStore()),
+                uploadBucket: (bucketOptions) => kept(new LambderMemoryUploadBucket(bucketOptions)),
+                invokeTransport: ({ functionName, apiPath }) => {
+                    const mockApp = Object.hasOwn(invokeMocks, functionName) ? invokeMocks[functionName] : undefined;
+                    if (mockApp)
+                        return lambderMockInvokeTransport(mockApp, { apiPath });
+                    return async () => {
+                        throw new Error(`lambderTestApp: no invoke mock answers the function "${functionName}", and under a test app an invoke caller never reaches AWS. ` +
+                            `Pass invokeMocks: { "${functionName}": mockApp } to answer it from a LambderMockApp.`);
+                    };
+                },
+            };
+            swappable.swapIn(twins);
+        };
+        for (const swappable of liveSwappableInstances())
+            putTwinUnder(swappable);
+        watchSwappableInstances(putTwinUnder);
         lambder[LAMBDER_CRASH_WATCH]((error) => {
             this.crashList.push(error);
             const scope = this.crashScope.getStore();
@@ -131,6 +190,39 @@ export class LambderTestApp {
     get callSummaries() {
         return this.callSummaryList;
     }
+    /**
+     * Fails every test that leaves a crash behind: installs, through the
+     * runner's own `afterEach`, a check that throws when `crashes` is not
+     * empty, listing each crash with its stack. The crashes it reports are
+     * forgotten, so the next test starts clean whether or not it resets. A
+     * test that provokes a crash on purpose asserts on `crashes` and ends
+     * with `reset()`.
+     *
+     * ```typescript
+     * const app = lambderTestApp(lambder);
+     * app.assertNoCrashesAfterEach(afterEach);
+     * ```
+     */
+    assertNoCrashesAfterEach(afterEach) {
+        afterEach(() => {
+            if (this.crashList.length === 0)
+                return;
+            const crashes = this.crashList.splice(0);
+            const listed = crashes.map((crash, index) => {
+                const [first, ...frames] = (crash.stack ?? `${crash.name}: ${crash.message}`).split("\n");
+                return [`${index + 1}) ${first}`, ...frames.map((frame) => `   ${frame.trim()}`)].join("\n");
+            });
+            throw new Error(`The app crashed answering ${crashes.length === 1 ? "a request" : `${crashes.length} requests`} in this test:\n\n${listed.join("\n\n")}`);
+        });
+    }
+    memoryTwinOf(instance) {
+        const twin = this.memoryTwins.get(instance);
+        if (!twin) {
+            throw new Error("lambderTestApp: memoryTwinOf() was handed something this test app put no memory twin under. It takes a LambderDdbCache, " +
+                "LambderDdbOneShotSecretStore or LambderS3UploadBucket, and the test app created last puts its own twins under every one.");
+        }
+        return twin;
+    }
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
     get sessionManager() {
         return this.lambder.getSessionManager();
@@ -156,8 +248,8 @@ export class LambderTestApp {
      * no login endpoint has to exist or be called.
      *
      * ```typescript
-     * const admin = await app.signIn("user:ada", { userId: "ada", role: "admin" });
-     * expect(await admin.api("org.rename", { name })).toEqual({ ok: true });
+     * const owner = await app.signIn("user:ada", { userId: "ada", role: "owner" });
+     * expect(await owner.api("store.rename", { name })).toEqual({ ok: true });
      * ```
      */
     async signIn(sessionKey, data, ...[options]) {
@@ -193,14 +285,17 @@ export class LambderTestApp {
     }
     /**
      * Rewinds what accumulated: sessions, rate-limit counters and replay
-     * records in the stores this test app made, the crashes and call
-     * summaries it recorded, and the cookies of every visitor it created
-     * (each empties its jar the next time it is used). For a beforeEach. The
-     * app's own data (its database) is the app's to rewind.
+     * records in the stores this test app made, the memory twins under the
+     * app's own stores, the crashes and call summaries it recorded, and the
+     * cookies of every visitor it created (each empties its jar the next
+     * time it is used). For a beforeEach. The app's own data (its database)
+     * is the app's to rewind, and so are the invoke mocks.
      */
     reset() {
         for (const store of this.ownStores)
             store.reset();
+        for (const { instance } of liveSwappableInstances())
+            this.memoryTwins.get(instance)?.reset();
         this.crashList.length = 0;
         this.callSummaryList.length = 0;
         this.resetCount += 1;

package/dist/testing/LambderTestVisitor.d.ts

@@ -1,12 +1,14 @@
-import LambderCaller, { type LambderCallerGroupCalls, type LambderCallerMembers } from "../client/LambderCaller.js";
+import LambderCaller, { type LambderCallerMembers, type LambderCallOptions } from "../client/LambderCaller.js";
+import { type LambderContractActionOf, type LambderContractGroupsOf, type LambderContractNamesInGroup } from "../shared/wire/LambderApiGroupCalls.js";
+import type { LambderApiOutcome } from "../shared/wire/LambderApiOutcome.js";
 import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 import type { LambderHandler } from "../core/LambderCreateOptions.js";
 import { type LambderLambdaHttpResult } from "../invoke/LambderLambdaEvent.js";
 import type { LambderCreatedSession } from "../session/LambderSessionManager.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
-import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiContractShape, LambderContractRefusalMessage } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
-import type { LambderGuardInputsProviderOption } from "../shared/wire/LambderCallOptions.js";
+import type { LambderCallArgs, LambderContractOutputOf, LambderGuardInputsProviderOption } from "../shared/wire/LambderCallOptions.js";
 /**
  * How one visitor differs from the next. Everything is optional: a visitor
  * nobody described is a stranger on the app's host, at an address of its own.
@@ -73,12 +75,35 @@ export type LambderTestVisitorWiring<TSessionData> = {
 export type LambderTestVisitorArgs<TOptions, TProvidedGuards extends string> = [
     TProvidedGuards
 ] extends [never] ? [options?: TOptions] : [options: TOptions];
+/**
+ * A visitor's `api`: the endpoint's output, typed as the output alone, or a
+ * thrown Error saying what came back instead. A test step that should
+ * succeed reads its output on the next line; a refused or crashed step stops
+ * the test there, rather than as an undefined read further on.
+ */
+export type LambderTestVisitorApi<TContract extends LambderApiContractShape, TProvidedGuards extends string> = <TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TApiName>>>) => Promise<LambderContractOutputOf<TContract, TApiName>>;
+/**
+ * One endpoint as a visitor hands it out on its group: called, it is the
+ * visitor's `api` for that endpoint (the output, or a thrown Error saying what
+ * came back instead); `.outcome` is its `apiOutcome`, which never throws.
+ */
+export type LambderTestVisitorEndpoint<TContract, TName extends keyof TContract & string, TProvidedGuards extends string> = {
+    (...args: LambderCallArgs<TContract, TName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TName>>>): Promise<LambderContractOutputOf<TContract, TName>>;
+    outcome(...args: LambderCallArgs<TContract, TName, TProvidedGuards, LambderCallOptions<LambderContractRefusalMessage<TContract, TName>>>): Promise<LambderApiOutcome<LambderContractOutputOf<TContract, TName>, LambderContractRefusalMessage<TContract, TName>>>;
+};
+/** Every endpoint of a contract by group, as a visitor hands them out: `visitor.orders.place(input)`. */
+export type LambderTestVisitorGroupCalls<TContract, TProvidedGuards extends string> = {
+    readonly [TGroup in LambderContractGroupsOf<TContract>]: {
+        readonly [TName in LambderContractNamesInGroup<TContract, TGroup> as LambderContractActionOf<TName>]: LambderTestVisitorEndpoint<TContract, TName, TProvidedGuards>;
+    };
+};
 /**
  * One simulated browser in front of a real Lambder app: a cookie jar, an
- * address and a host of its own, and two ways in. `api` / `apiOutcome` are a
- * typed LambderCaller's, over the real handler in this process, so a call
- * runs the whole pipeline (rate limits, session, replay, guards, validation)
- * the way a browser's would. `request` is everything else a browser sends:
+ * address and a host of its own, and two ways in. `api` / `apiOutcome` go
+ * through a typed LambderCaller, over the real handler in this process, so a
+ * call runs the whole pipeline (rate limits, session, replay, guards,
+ * validation) the way a browser's would; `api` throws where the caller's
+ * would hand back undefined. `request` is everything else a browser sends:
  * pages, redirects, session routes, file requests. Both carry the same jar,
  * so a session started through one is the session the other presents.
  *
@@ -95,8 +120,14 @@ declare class LambderTestVisitorCore<TContract extends LambderApiContractShape =
      * An answer's logList is not printed; it is on the outcome.
      */
     readonly caller: LambderCaller<TContract, TProvidedGuards>;
-    /** The payload on success, `undefined` on a failure: LambderCaller.api, through this visitor. */
-    readonly api: LambderCallerMembers<TContract, TProvidedGuards>["api"];
+    /**
+     * The endpoint's output; throws on every failure, with an Error that
+     * names the endpoint and says what came back the way assertApiSuccess
+     * does: the reason, the status, the refusal's code and message, and for
+     * a crash the error the app threw, which is also the end of the Error's
+     * cause chain. `apiOutcome` is for a test that expects a failure.
+     */
+    readonly api: LambderTestVisitorApi<TContract, TProvidedGuards>;
     /**
      * The full outcome, never throwing: LambderCaller.apiOutcome, through
      * this visitor. Pair it with assertApiSuccess / assertApiFailure.
@@ -150,10 +181,10 @@ declare class LambderTestVisitorCore<TContract extends LambderApiContractShape =
 }
 /**
  * One simulated browser in front of a real Lambder app, with the app's
- * endpoints by group as a caller has them: `visitor.orders.place(input)`,
- * `visitor.orders.place.outcome(input)`.
+ * endpoints by group: `visitor.orders.place(input)` for the output (thrown on
+ * a failure), `visitor.orders.place.outcome(input)` for the outcome.
  */
-export type LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> = LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards> & LambderCallerGroupCalls<TContract, TProvidedGuards>;
+export type LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> = LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards> & LambderTestVisitorGroupCalls<TContract, TProvidedGuards>;
 export declare const LambderTestVisitor: {
     new <TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never>(...args: ConstructorParameters<typeof LambderTestVisitorCore<TContract, TSessionData, TProvidedGuards>>): LambderTestVisitor<TContract, TSessionData, TProvidedGuards>;
     readonly prototype: LambderTestVisitorCore<any, any, any>;

package/dist/testing/LambderTestVisitor.js

@@ -1,16 +1,18 @@
 import LambderCaller from "../client/LambderCaller.js";
-import { withApiGroupCalls } from "../shared/wire/LambderApiGroupCalls.js";
+import { withApiGroupCalls, } from "../shared/wire/LambderApiGroupCalls.js";
 import { lambderHandlerTransport } from "../invoke/lambderHandlerTransport.js";
 import { decodeLambdaHttpResult, localLambdaContext, synthesizeLambdaHttpEvent, } from "../invoke/LambderLambdaEvent.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { lambderCookieJarTransport } from "../shared/transport/lambderCookieJarTransport.js";
+import { assertApiSuccess } from "../shared/wire/LambderOutcomeAssertions.js";
 import { DEFAULT_MAX_RESTORED_PAYLOAD_BYTES } from "../shared/wire/LambderRequestPayload.js";
 /**
  * One simulated browser in front of a real Lambder app: a cookie jar, an
- * address and a host of its own, and two ways in. `api` / `apiOutcome` are a
- * typed LambderCaller's, over the real handler in this process, so a call
- * runs the whole pipeline (rate limits, session, replay, guards, validation)
- * the way a browser's would. `request` is everything else a browser sends:
+ * address and a host of its own, and two ways in. `api` / `apiOutcome` go
+ * through a typed LambderCaller, over the real handler in this process, so a
+ * call runs the whole pipeline (rate limits, session, replay, guards,
+ * validation) the way a browser's would; `api` throws where the caller's
+ * would hand back undefined. `request` is everything else a browser sends:
  * pages, redirects, session routes, file requests. Both carry the same jar,
  * so a session started through one is the session the other presents.
  *
@@ -26,7 +28,13 @@ class LambderTestVisitorCore {
      * An answer's logList is not printed; it is on the outcome.
      */
     caller;
-    /** The payload on success, `undefined` on a failure: LambderCaller.api, through this visitor. */
+    /**
+     * The endpoint's output; throws on every failure, with an Error that
+     * names the endpoint and says what came back the way assertApiSuccess
+     * does: the reason, the status, the refusal's code and message, and for
+     * a crash the error the app threw, which is also the end of the Error's
+     * cause chain. `apiOutcome` is for a test that expects a failure.
+     */
     api;
     /**
      * The full outcome, never throwing: LambderCaller.apiOutcome, through
@@ -77,12 +85,28 @@ class LambderTestVisitorCore {
                 outcome.error.cause = crash;
             return outcome;
         };
-        this.api = ((apiName, ...callArgs) => caller.api(apiName, ...callArgs));
+        // The plain call reads as the output, so a failure has nowhere to go
+        // but a throw. assertApiSuccess says what came back, as a test's own
+        // assertion would; the endpoint's name says which step of a setup it
+        // was.
+        const api = async (apiName, ...callArgs) => {
+            const outcome = await apiOutcome(apiName, ...callArgs);
+            try {
+                assertApiSuccess(outcome);
+            }
+            catch (err) {
+                const described = err;
+                throw new Error(`${apiName}: ${described.message}`, { cause: described.cause });
+            }
+            return outcome.payload;
+        };
+        this.api = api;
         this.apiOutcome = apiOutcome;
-        // Each group of the contract, as on a caller, through this visitor's
-        // own two calls: visitor.orders.place.outcome(input) carries the crash
-        // cause as visitor.apiOutcome does.
-        return withApiGroupCalls(this, (apiName, args) => caller.api(apiName, ...args), (apiName, args) => apiOutcome(apiName, ...args));
+        // Each group of the contract through this visitor's own two calls:
+        // visitor.orders.place(input) throws as visitor.api does, and
+        // visitor.orders.place.outcome(input) carries the crash cause as
+        // visitor.apiOutcome does.
+        return withApiGroupCalls(this, (apiName, args) => api(apiName, ...args), (apiName, args) => apiOutcome(apiName, ...args));
     }
     /**
      * This visitor's cookies, to inspect or clear; every call and request

package/dist/testing/bootLambdaPackage.d.ts

@@ -0,0 +1,105 @@
+import { type LambderApiOutcome } from "../shared/wire/LambderApiOutcome.js";
+/**
+ * One call the booted handler receives: a Lambder API call, which becomes
+ * the event a gateway (or, with `invoke`, another function) would deliver
+ * for it, or an event exactly as given (a schedule, a queue message, an
+ * HTTP request written out by hand).
+ */
+export type LambderPackageBootCall = {
+    /** The endpoint, as `group.action`. */
+    api: string;
+    /** The call's input. Default: none. */
+    payload?: unknown;
+    /** Headers the event carries beside the ones it owns. */
+    headers?: Record<string, string>;
+} | {
+    /** The event, handed to the handler as it is. */
+    event: unknown;
+    /** How the result names this call. Default: "event N", N its index. */
+    name?: string;
+};
+export type LambderPackageBootOptions = {
+    /** The assembled deployment package: the directory that becomes the zip, with its production dependencies installed, if it has any. */
+    packageDir: string;
+    /** The handler as the function's configuration names it: the module's path in the package without its extension, a dot, and the export. Default: "index.handler". The module is the first of `.js`, `.mjs` and `.cjs` that exists, as on Lambda. */
+    handler?: string;
+    /** What the handler receives, in order, in the one process, as a warm function receives it. Default: none, so the package is only imported. */
+    calls?: readonly LambderPackageBootCall[];
+    /** Where the server takes API calls, for the calls given as `api`. Default: "/api". */
+    apiPath?: string;
+    /** The Host an API call's event names. Default: "localhost". */
+    host?: string;
+    /** The API version an API call's envelope carries, for a server with a version floor. Default: none. */
+    apiVersion?: string;
+    /** Send API calls as another function's invoke rather than as a browser's request through a gateway. Default: false. */
+    invoke?: boolean;
+    /** Package names and scopes the Lambda runtime supplies, so the package leaves them out. Default: ["@aws-sdk"]. */
+    runtimeModules?: readonly string[];
+    /** The directory runtimeModules resolve from, as if a module there imported them: an install that has them. Default: the working directory, normally the project's root. */
+    runtimeModulesFrom?: string;
+    /** The process's environment, beside PATH: the variables the function's configuration sets. Nothing else of this process's environment reaches it. Default: none. */
+    env?: Record<string, string>;
+    /** Node's options for the process, such as the heap sizes Lambda starts the function with, so what is measured is what the function pays. Default: none. */
+    nodeFlags?: readonly string[];
+    /** How long starting the process and importing the handler module may take. Default: 30,000. */
+    importTimeoutMs?: number;
+    /** How long each call may take. Default: 30,000. */
+    callTimeoutMs?: number;
+};
+/** What loading the package cost, measured in the process that loaded it and nothing before it. */
+export type LambderPackageBootMeasurements = {
+    /** Importing the handler module and everything it imports statically: what a cold start pays before its first request. */
+    importMs: number;
+    /** The process's resident memory once that import finished. */
+    rssBytes: number;
+};
+/** The handler's answer to one call. */
+export type LambderPackageBootCallResult = {
+    /** The call's endpoint, or its event's name. */
+    name: string;
+    /** What the handler returned, as Lambda hands it back: through JSON, null for nothing. */
+    returned: unknown;
+    /** The HTTP status, when the handler answered with an HTTP response. */
+    status?: number;
+    /** For an API call, what a caller reads off the answer, for assertApiSuccess, assertApiFailure and assertApiRefusal. */
+    outcome?: LambderApiOutcome<unknown>;
+};
+export type LambderPackageBootResult = {
+    /** Whether the package imported and the handler answered every call. */
+    ok: boolean;
+    /** Where it failed: "import" (starting the process and importing the handler module) or "handler" (a call threw, ran out of time, or the process died during it). */
+    phase?: "import" | "handler";
+    /** The call that failed, as its result would have named it. */
+    failedCall?: string;
+    /** What went wrong, ready to print: the phase or the call, the error, and the end of the process's output when it died. */
+    error?: string;
+    /** The answer to each call the handler answered, in order: all of them when `ok`. */
+    calls: LambderPackageBootCallResult[];
+    /** Present once the import finished. */
+    measurements?: LambderPackageBootMeasurements;
+    /** What the process wrote to stdout and stderr. */
+    output: string;
+};
+/**
+ * Boots an assembled deployment package the way Lambda boots it, and hands
+ * its handler each call in turn: in a fresh node process, so nothing of the
+ * calling test's module graph or environment reaches it, with the package
+ * directory as the working directory, and with every import the package
+ * makes held to what the package carries. What the Lambda runtime supplies
+ * (`runtimeModules`, the AWS SDK by default) resolves from an install
+ * outside it instead, since the package rightly leaves it out.
+ *
+ * Makes no assertions: the result says whether the package imported and
+ * answered, what each call answered, what the import cost, and where it
+ * failed. Throws, before or after starting the process, for what is not
+ * the package's doing: a missing directory, a handler that names no module
+ * there or no function exported by it, an option out of range, or a Node
+ * without synchronous module hooks.
+ *
+ * ```typescript
+ * const boot = await bootLambdaPackage({ packageDir: "build/server", calls: [{ api: "status.ping" }] });
+ * expect(boot.ok, boot.error).toBe(true);
+ * assertApiSuccess(boot.calls[0]!.outcome!);
+ * ```
+ */
+export declare const bootLambdaPackage: (options: LambderPackageBootOptions) => Promise<LambderPackageBootResult>;