lambder 7.2.5 → 7.3.1

package/dist/invoke/lambderHandlerTransport.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from "aws-lambda";
 import type { LambderApiTransport } from "../shared/transport/LambderApiTransport.js";
 import type { LambderHandler } from "../core/LambderCreateOptions.js";
+import type { LambderHttpEventFormat } from "../core/LambderContext.js";
 export type LambderHandlerTransportOptions = {
     /** The Host the handler sees (ctx.host), and the siteHost the envelope carries when the caller has none. Default: the apiPath's own host when it is absolute, otherwise "localhost". */
     host?: string;
@@ -10,6 +11,8 @@ export type LambderHandlerTransportOptions = {
     maxResponseBytes?: number;
     /** Fields of the Lambda context the handler receives. */
     context?: Partial<Context>;
+    /** The gateway shape the handler is called with: "v2" (an HTTP API, a Function URL) or "v1" (a REST API). Default: "v2". A handler answers both alike; name the one your deployment delivers when the difference is what you are testing. */
+    eventFormat?: LambderHttpEventFormat;
 };
 /**
  * A transport that calls a Lambder handler in this process, the way a

package/dist/invoke/lambderHandlerTransport.js

@@ -50,7 +50,7 @@ export const lambderHandlerTransport = (handler, options = {}) => {
             clientIp: request.clientIp ?? clientIp,
             cookies: request.cookies,
             body: JSON.stringify(buildTransportEnvelope({ ...request, siteHost: request.siteHost || host })),
-        }, { invoke: false });
+        }, { invoke: false, eventFormat: options.eventFormat });
         let result;
         try {
             result = await stopWaitingWhenAborted(handler(event, localLambdaContext("lambder-local", options.context)), request.signal);

package/dist/mock.d.ts

@@ -26,6 +26,8 @@ export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSe
 export type { LambderSessionCrypto } from "./session/LambderSessionCrypto.js";
 export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderRefusalMessage } from "./shared/wire/LambderApiRefusal.js";
+export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";
+export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderApiRequest } from "./api/LambderApiRequest.js";
 export type { LambderApiAnswer } from "./api/LambderApiAnswer.js";
 export type { LambderSessionRecord } from "./shared/contracts/LambderSessionStore.js";

package/dist/mock.js

@@ -25,3 +25,6 @@ export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
 export { LambderWebCrypto, LambderPlainSessionCrypto } from "./session/LambderSessionCrypto.js";
 export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+// The outcome assertions a test over the mock app narrows with; the same two
+// `lambder/testing` exports for a test over the real server.
+export { assertApiSuccess, assertApiFailure } from "./shared/wire/LambderOutcomeAssertions.js";

package/dist/session/LambderSessionManager.d.ts

@@ -1,5 +1,6 @@
 import type { LambderSessionCrypto } from "./LambderSessionCrypto.js";
 import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /**
  * A freshly created (or regenerated) session: the persisted record plus the
  * RAW cookie secrets, which exist only here and in the cookies the caller
@@ -92,13 +93,23 @@ export declare const isMintedSessionToken: (token: string) => boolean;
  * stored too.
  */
 export default class LambderSessionManager<SessionData = any> {
-    private readonly store;
+    /** Replaceable through the backend swap alone; see LAMBDER_BACKEND_SWAP. */
+    private store;
     private readonly sessionSalt;
     private readonly enableSlidingExpiration;
     private readonly slidingWriteIntervalSeconds;
     private readonly dataRefresh;
     private readonly crypto;
     constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, crypto, }: LambderSessionManagerOptions<SessionData>);
+    /** A store this manager's crypto may sit in front of. Asked of every store it is given, the one at creation and a swapped one alike. */
+    private assertCryptoFitsStore;
+    /**
+     * Puts the manager over another store, for `lambder/testing`. The model
+     * (salt, tokens, expiry, dataRefresh) stays this manager's own, so a test
+     * runs the app's sessions as configured over a store that dies with the
+     * process. Sessions held by the store it leaves are simply out of reach.
+     */
+    [LAMBDER_BACKEND_SWAP](store: LambderSessionStore<SessionData>): void;
     /**
      * The salted partition hash of a sessionKey: sha256 of the key followed
      * by the salt, with NO separator between them.

package/dist/session/LambderSessionManager.js

@@ -1,6 +1,7 @@
 import { LambderWebCrypto } from "./LambderSessionCrypto.js";
 import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -79,6 +80,7 @@ export const isMintedSessionToken = (token) => {
  * stored too.
  */
 export default class LambderSessionManager {
+    /** Replaceable through the backend swap alone; see LAMBDER_BACKEND_SWAP. */
     store;
     sessionSalt;
     enableSlidingExpiration;
@@ -96,14 +98,28 @@ export default class LambderSessionManager {
             assertPositiveInteger(dataRefresh.ttlSeconds, "session.dataRefresh.ttlSeconds");
         this.dataRefresh = dataRefresh ?? null;
         this.crypto = crypto ?? new LambderWebCrypto();
+        this.assertCryptoFitsStore(store);
+        if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
+            throw new Error("Lambder: session sessionSalt is empty. It salts the hash that partitions the store, so it has to be a real, stable secret.");
+        }
+    }
+    /** A store this manager's crypto may sit in front of. Asked of every store it is given, the one at creation and a swapped one alike. */
+    assertCryptoFitsStore(store) {
         if (!this.crypto.isCryptographic && !store.isMemoryOnly) {
             throw new Error("Lambder: this session crypto does not hash and does not draw cryptographically random bytes, " +
                 "so it may only sit in front of a store that dies with the process. Over a persistent store every " +
                 "record would be a usable credential and the sessionSalt would be readable from it.");
         }
-        if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
-            throw new Error("Lambder: session sessionSalt is empty. It salts the hash that partitions the store, so it has to be a real, stable secret.");
-        }
+    }
+    /**
+     * Puts the manager over another store, for `lambder/testing`. The model
+     * (salt, tokens, expiry, dataRefresh) stays this manager's own, so a test
+     * runs the app's sessions as configured over a store that dies with the
+     * process. Sessions held by the store it leaves are simply out of reach.
+     */
+    [LAMBDER_BACKEND_SWAP](store) {
+        this.assertCryptoFitsStore(store);
+        this.store = store;
     }
     /**
      * The salted partition hash of a sessionKey: sha256 of the key followed

package/dist/shared/util/LambderTestingDoors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The keys of the two doors `lambder/testing` opens on a built instance.
+ *
+ * Symbols rather than named methods, and exported by no entry point: the
+ * package's exports map is what a consumer can import, so only
+ * `lambder/testing` can name a key, and nothing on the typed surface of an
+ * instance offers either door to a serving app.
+ */
+/**
+ * Puts other stores under the instance.
+ *
+ * An app is one module-level instance whose handlers and guards close over it
+ * (`app.getSessionController(ctx)`), so a test cannot be handed a copy over
+ * other stores: the copy's closures would still reach the original and the
+ * production table under it. The stores are therefore replaced in place, and
+ * every class that holds one answers to this key with a method that takes the
+ * replacement.
+ */
+export declare const LAMBDER_BACKEND_SWAP: unique symbol;
+/**
+ * Watches what the instance throws while answering a request.
+ *
+ * A crash is answered by the app's global error handler, or by the framework's
+ * own 500, and either way the answer deliberately says nothing about what was
+ * thrown: that is right for a client and useless to a test, whose author needs
+ * the error and its stack. The watcher is handed the error and changes nothing
+ * about the answer, so what an app does with a crash stays testable.
+ */
+export declare const LAMBDER_CRASH_WATCH: unique symbol;

package/dist/shared/util/LambderTestingDoors.js

@@ -0,0 +1,29 @@
+/**
+ * The keys of the two doors `lambder/testing` opens on a built instance.
+ *
+ * Symbols rather than named methods, and exported by no entry point: the
+ * package's exports map is what a consumer can import, so only
+ * `lambder/testing` can name a key, and nothing on the typed surface of an
+ * instance offers either door to a serving app.
+ */
+/**
+ * Puts other stores under the instance.
+ *
+ * An app is one module-level instance whose handlers and guards close over it
+ * (`app.getSessionController(ctx)`), so a test cannot be handed a copy over
+ * other stores: the copy's closures would still reach the original and the
+ * production table under it. The stores are therefore replaced in place, and
+ * every class that holds one answers to this key with a method that takes the
+ * replacement.
+ */
+export const LAMBDER_BACKEND_SWAP = Symbol("lambder.backendSwap");
+/**
+ * Watches what the instance throws while answering a request.
+ *
+ * A crash is answered by the app's global error handler, or by the framework's
+ * own 500, and either way the answer deliberately says nothing about what was
+ * thrown: that is right for a client and useless to a test, whose author needs
+ * the error and its stack. The watcher is handed the error and changes nothing
+ * about the answer, so what an app does with a crash stays testable.
+ */
+export const LAMBDER_CRASH_WATCH = Symbol("lambder.crashWatch");

package/dist/shared/wire/LambderOutcomeAssertions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Two assertions over a call's outcome, for tests.
+ *
+ * An outcome is a discriminated union, so a test that expects a refusal has
+ * to narrow before it can read what the refusal carries, and the narrowing is
+ * the same three lines every time: check `ok`, branch on it, check `reason`.
+ * Written by hand, the failing case prints "expected false to be true" and
+ * says nothing about what actually came back, which is the one thing worth
+ * knowing when a call that should have been refused went through, or crashed
+ * instead.
+ *
+ * These narrow through an `asserts` signature, so the lines after one read
+ * the arm it proved, and they throw a plain Error naming what the outcome
+ * was. No test runner is imported: the same two functions serve vitest, jest
+ * and node:test, from `lambder/testing` over a real server and from
+ * `lambder/mock` over a mock one. Pure and dependency-free, like the outcome
+ * vocabulary they read.
+ *
+ * Typed structurally over `ok` and `reason` rather than over
+ * LambderApiOutcome, so a LambderInvokeOutcome, whose failure side names
+ * other reasons, is narrowed by the same functions and a misspelled reason is
+ * a compile error against whichever union was passed.
+ */
+/** What both callers' outcomes have in common: the discriminant, and a reason on the failure side. */
+type LambderOutcomeShape = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Every reason the failure side of an outcome union can carry. */
+type LambderFailureReasonOf<TOutcome> = TOutcome extends {
+    ok: false;
+    reason: infer TReason;
+} ? TReason : never;
+/**
+ * The failure arms that can carry one of the given reasons, each narrowed to
+ * it. Per arm rather than through Extract: one arm may carry several reasons
+ * (`network`, `timeout`, `server` and `unknown` share theirs), and Extract
+ * would drop that arm for any single one of them.
+ */
+type LambderFailureWithReason<TOutcome, TReason> = TOutcome extends {
+    ok: false;
+    reason: infer TArmReason;
+} ? [TReason & TArmReason] extends [never] ? never : TOutcome & {
+    reason: TReason & TArmReason;
+} : never;
+/** What else a failure is expected to carry, beside its reason. */
+export type LambderExpectedFailure = {
+    /** The refusal's machine-readable code (`errorMessage.code`), e.g. a LAMBDER_REFUSAL_CODES value or the app's own. */
+    code?: string;
+    /** The HTTP status the answer came with. */
+    status?: number;
+};
+/**
+ * Asserts that a call succeeded, and narrows the outcome to its success arm,
+ * so `outcome.payload` reads directly on the next line.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.create", { sku });
+ * assertApiSuccess(outcome);
+ * expect(outcome.payload?.orderId).toBeDefined();
+ * ```
+ */
+export declare function assertApiSuccess<TOutcome extends LambderOutcomeShape>(outcome: TOutcome): asserts outcome is Extract<TOutcome, {
+    ok: true;
+}>;
+/**
+ * Asserts that a call failed, with the given reason when one is named, and
+ * narrows the outcome to the arms that reason can be, so what it carries
+ * (`zodError` after "validation", `response` after an envelope reason,
+ * `error` after the rest) reads directly on the next line.
+ *
+ * ```typescript
+ * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
+ * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * ```
+ */
+export declare function assertApiFailure<TOutcome extends LambderOutcomeShape, TReason extends LambderFailureReasonOf<TOutcome> = LambderFailureReasonOf<TOutcome>>(outcome: TOutcome, reason?: TReason, expected?: LambderExpectedFailure): asserts outcome is LambderFailureWithReason<TOutcome, TReason>;
+export {};

package/dist/shared/wire/LambderOutcomeAssertions.js

@@ -0,0 +1,113 @@
+/**
+ * Two assertions over a call's outcome, for tests.
+ *
+ * An outcome is a discriminated union, so a test that expects a refusal has
+ * to narrow before it can read what the refusal carries, and the narrowing is
+ * the same three lines every time: check `ok`, branch on it, check `reason`.
+ * Written by hand, the failing case prints "expected false to be true" and
+ * says nothing about what actually came back, which is the one thing worth
+ * knowing when a call that should have been refused went through, or crashed
+ * instead.
+ *
+ * These narrow through an `asserts` signature, so the lines after one read
+ * the arm it proved, and they throw a plain Error naming what the outcome
+ * was. No test runner is imported: the same two functions serve vitest, jest
+ * and node:test, from `lambder/testing` over a real server and from
+ * `lambder/mock` over a mock one. Pure and dependency-free, like the outcome
+ * vocabulary they read.
+ *
+ * Typed structurally over `ok` and `reason` rather than over
+ * LambderApiOutcome, so a LambderInvokeOutcome, whose failure side names
+ * other reasons, is narrowed by the same functions and a misspelled reason is
+ * a compile error against whichever union was passed.
+ */
+const MAX_DESCRIBED_VALUE_LENGTH = 300;
+/** A value as it can be printed in an assertion message: JSON, cut short, never throwing over a cyclic one. */
+const describeValue = (value) => {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > MAX_DESCRIBED_VALUE_LENGTH ? `${text.slice(0, MAX_DESCRIBED_VALUE_LENGTH)}...` : text;
+};
+/**
+ * The error a failure carries, which becomes the cause of the assertion's
+ * own: a test runner prints the chain, so an app that crashed under
+ * `lambder/testing` shows the handler's stack under the failed assertion.
+ */
+const errorOf = (outcome) => {
+    const error = outcome.error;
+    return error instanceof Error ? error : undefined;
+};
+/** One line saying what an outcome was, for the message of an assertion it failed. */
+const describeOutcome = (outcome) => {
+    if (outcome.ok)
+        return `a success carrying ${describeValue(outcome.payload)}`;
+    const failure = outcome;
+    const details = [];
+    if (failure.status !== undefined)
+        details.push(`status ${failure.status}`);
+    if (failure.errorMessage !== undefined)
+        details.push(`errorMessage ${describeValue(failure.errorMessage)}`);
+    if (failure.zodError !== undefined)
+        details.push(`zodError ${describeValue(failure.zodError.message)}`);
+    // The error's own message, and its cause when it has one: an in-process
+    // transport reports a handler that threw as a failure whose cause is
+    // what actually threw, and that is the line a test author needs.
+    if (failure.error instanceof Error) {
+        const cause = failure.error.cause instanceof Error ? ` (cause: ${failure.error.cause.message})` : "";
+        details.push(`error "${failure.error.message}"${cause}`);
+    }
+    return `a failure with reason "${failure.reason}"${details.length ? `, ${details.join(", ")}` : ""}`;
+};
+/**
+ * Asserts that a call succeeded, and narrows the outcome to its success arm,
+ * so `outcome.payload` reads directly on the next line.
+ *
+ * ```typescript
+ * const outcome = await visitor.apiOutcome("order.create", { sku });
+ * assertApiSuccess(outcome);
+ * expect(outcome.payload?.orderId).toBeDefined();
+ * ```
+ */
+export function assertApiSuccess(outcome) {
+    if (!outcome.ok)
+        throw new Error(`Expected the call to succeed, but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+}
+/**
+ * Asserts that a call failed, with the given reason when one is named, and
+ * narrows the outcome to the arms that reason can be, so what it carries
+ * (`zodError` after "validation", `response` after an envelope reason,
+ * `error` after the rest) reads directly on the next line.
+ *
+ * ```typescript
+ * assertApiFailure(await member.apiOutcome("org.delete", { id }), "notAuthorized");
+ * assertApiFailure(await guest.apiOutcome("signup", form), "errorMessage", { code: LAMBDER_REFUSAL_CODES.rateLimited, status: 429 });
+ * ```
+ */
+export function assertApiFailure(outcome, reason, expected = {}) {
+    const wanted = [
+        reason !== undefined ? `reason "${String(reason)}"` : null,
+        expected.code !== undefined ? `code "${expected.code}"` : null,
+        expected.status !== undefined ? `status ${expected.status}` : null,
+    ].filter((part) => part !== null).join(", ");
+    const refuse = () => {
+        throw new Error(`Expected the call to fail${wanted ? ` with ${wanted}` : ""}, but it was ${describeOutcome(outcome)}.`, { cause: errorOf(outcome) });
+    };
+    if (outcome.ok)
+        return refuse();
+    if (reason !== undefined && outcome.reason !== reason)
+        return refuse();
+    if (expected.code !== undefined) {
+        // Only the structured errorMessage carries a code; a plain string has none to match.
+        const errorMessage = outcome.errorMessage;
+        const code = errorMessage && typeof errorMessage === "object" ? errorMessage.code : undefined;
+        if (code !== expected.code)
+            return refuse();
+    }
+    if (expected.status !== undefined && outcome.status !== expected.status)
+        return refuse();
+}

package/dist/testing/LambderTestApp.d.ts

@@ -0,0 +1,178 @@
+import type { Context } from "aws-lambda";
+import type Lambder from "../core/Lambder.js";
+import { type LambderHttpEventFormat } from "../core/LambderContext.js";
+import type { LambderHandler } from "../core/LambderCreateOptions.js";
+import type LambderSessionManager from "../session/LambderSessionManager.js";
+import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js";
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import { LambderTestVisitor, type LambderTestVisitorArgs, type LambderTestVisitorOptions } from "./LambderTestVisitor.js";
+/**
+ * What a test app may be told. Nothing is required: `lambderTestApp(lambder)`
+ * is a working test app over memory stores.
+ *
+ * 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.
+ */
+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. */
+    host?: string;
+    /**
+     * The gateway shape the handler is called with: "v2" (an HTTP API, a
+     * Function URL) or "v1" (a REST API). Default: "v2". A handler answers
+     * both alike through its context, so this matters to code that reads the
+     * raw `ctx.event`, and to anyone who wants the suite to run on exactly
+     * what production delivers.
+     */
+    eventFormat?: LambderHttpEventFormat;
+    /** Default: a fresh LambderMemorySessionStore. Pass your own to run the suite over another store (DynamoDB Local, say). */
+    session?: {
+        store?: LambderSessionStore<any>;
+    };
+    /** Default: a fresh LambderMemoryRateLimiter. */
+    rateLimits?: {
+        limiter?: LambderRateLimiter;
+    };
+    /** Default: a fresh LambderMemoryIdempotencyStore. */
+    idempotency?: {
+        store?: LambderIdempotencyStore;
+    };
+    /** 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;
+};
+/**
+ * A Lambder instance as a test app takes it: any instance, read for its
+ * session data type and, through the ApiContract property rather than the
+ * class parameter, for its contract. The property is what lets a large app
+ * name its flattened contract interface explicitly
+ * (`lambderTestApp<SessionData, ApiContractType>(lambder)`) and keep the
+ * cheap type check that interface exists for.
+ */
+export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any> & {
+    readonly ApiContract: TContract;
+};
+/**
+ * A real Lambder app under test: the instance an app already has, with memory
+ * stores put under it in place, and as many simulated browsers in front of it
+ * as a test needs. No HTTP, no AWS, and nothing in the app restructured.
+ *
+ * The app's own declarations all run as written: its guards, its named
+ * rate-limit policies, its idempotency settings, its session salt, cookie
+ * options and dataRefresh, its hooks and error handlers. Only where things
+ * rest is replaced, and from the moment this is created the stores the app
+ * was configured with are out of the instance's reach, so a test cannot touch
+ * a production table even by mistake. What the app reaches on its own (its
+ * database, a mailer) is the app's to replace.
+ *
+ * The sibling of LambderMockApp, which serves a contract from mock handlers:
+ * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
+ * real handlers instead.
+ *
+ * Time is not this class's: fake `Date` with the test runner
+ * (`vi.useFakeTimers({ toFake: ["Date"] })`), which moves the framework, the
+ * memory stores and the app's own handlers together.
+ *
+ * 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.
+ */
+export declare class LambderTestApp<TContract extends LambderApiContractShape = any, TSessionData = any> {
+    /** The instance's handler: what `event()` and every visitor call. */
+    readonly handler: LambderHandler;
+    /** The host visitors browse unless they name their own. */
+    readonly host: string;
+    /** The session store now under the instance, for assertions; null when the app has no sessions. A LambderMemorySessionStore unless one was given. */
+    readonly sessionStore: LambderSessionStore<TSessionData> | null;
+    /** The rate limiter now under the instance; null when the app declares no rate limits. */
+    readonly rateLimiter: LambderRateLimiter | null;
+    /** The idempotency store now under the instance; null when the app has no idempotency. */
+    readonly idempotencyStore: LambderIdempotencyStore | null;
+    private readonly lambder;
+    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;
+    private visitorCount;
+    private resetCount;
+    private readonly crashList;
+    /**
+     * The call a crash happened under. The app answers a crash with a 500
+     * that says nothing about it, so the error has to travel beside the
+     * answer, and with calls running concurrently (a duplicate sent while
+     * the original is in flight is an ordinary idempotency test) only the
+     * async context says which call a crash belongs to.
+     */
+    private readonly crashScope;
+    constructor(lambder: LambderTestedInstance<TSessionData, TContract>, options?: LambderTestAppOptions);
+    /**
+     * Every error the app threw while answering a request since the last
+     * reset, in order: what reached its global error handler, or the
+     * framework's last-resort 500. The answers themselves say nothing about
+     * what was thrown, so this is where a test reads it, and
+     * `expect(app.crashes).toEqual([])` is how one says nothing crashed.
+     * A refusal is not a crash, and neither is an error an `event()` rejects
+     * with, which the test already holds.
+     */
+    get crashes(): readonly Error[];
+    /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
+    get sessionManager(): LambderSessionManager<TSessionData>;
+    /**
+     * A new simulated browser: its own cookie jar, and its own address unless
+     * one is given. A stranger until it signs in, through the app's own login
+     * API or through `signIn`.
+     */
+    visitor<TProvidedGuards extends string = never>(...[options]: LambderTestVisitorArgs<LambderTestVisitorOptions<TContract, TProvidedGuards>, TProvidedGuards>): LambderTestVisitor<TContract, TSessionData, TProvidedGuards>;
+    /**
+     * A new visitor, already signed in: `visitor()` followed by its
+     * `signIn()`. The session is minted by the app's own session model, so
+     * 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 });
+     * ```
+     */
+    signIn<TProvidedGuards extends string = never>(sessionKey: string, data: TSessionData, ...[options]: LambderTestVisitorArgs<LambderTestVisitorOptions<TContract, TProvidedGuards> & {
+        ttlSeconds?: number;
+    }, TProvidedGuards>): Promise<LambderTestVisitor<TContract, TSessionData, TProvidedGuards>>;
+    /**
+     * Ends every session of the subject, the way "log out everywhere" does.
+     * A visitor signed in as that subject keeps its cookies, as a browser
+     * would, so its next call is what a real one's would be: answered
+     * sessionExpired, with the stale cookies evicted.
+     */
+    signOut(sessionKey: string): Promise<void>;
+    /** Marks the subject's session data stale, so the next read renews it through the app's dataRefresh. */
+    expireSessionData(sessionKey: string): Promise<void>;
+    /**
+     * Hands the handler an event that is not an HTTP request (a schedule, an
+     * SNS or SQS delivery), which is how an addAction handler runs, with a
+     * Lambda context filled in. Resolves to whatever the action returned.
+     *
+     * ```typescript
+     * await app.event({ source: "aws.events", "detail-type": "Scheduled Event" });
+     * ```
+     */
+    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 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.
+     */
+    reset(): void;
+}
+/**
+ * Puts a built Lambder instance under test. See LambderTestApp.
+ *
+ * ```typescript
+ * import { lambderTestApp } from "lambder/testing";
+ * import { lambder } from "../src/index.js";
+ *
+ * const app = lambderTestApp(lambder);
+ * beforeEach(() => app.reset());
+ * ```
+ */
+export declare const lambderTestApp: <TSessionData = any, TContract extends LambderApiContractShape = any>(lambder: LambderTestedInstance<TSessionData, TContract>, options?: LambderTestAppOptions) => LambderTestApp<TContract, TSessionData>;