lambder 7.2.4 → 7.3.1

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>;

package/dist/testing/LambderTestApp.js

@@ -0,0 +1,206 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { createContext } from "../core/LambderContext.js";
+import { localLambdaContext, synthesizeLambdaHttpEvent } from "../invoke/LambderLambdaEvent.js";
+import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
+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 { LambderTestVisitor } from "./LambderTestVisitor.js";
+/**
+ * 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 class LambderTestApp {
+    /** The instance's handler: what `event()` and every visitor call. */
+    handler;
+    /** The host visitors browse unless they name their own. */
+    host;
+    /** The session store now under the instance, for assertions; null when the app has no sessions. A LambderMemorySessionStore unless one was given. */
+    sessionStore;
+    /** The rate limiter now under the instance; null when the app declares no rate limits. */
+    rateLimiter;
+    /** The idempotency store now under the instance; null when the app has no idempotency. */
+    idempotencyStore;
+    lambder;
+    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 = [];
+    visitorCount = 0;
+    resetCount = 0;
+    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.
+     */
+    crashScope = new AsyncLocalStorage();
+    constructor(lambder, options = {}) {
+        // Only a Lambder instance of this same package copy answers to the
+        // key, so the failure is said here rather than as "is not a function".
+        if (typeof lambder?.[LAMBDER_BACKEND_SWAP] !== "function") {
+            throw new Error("lambderTestApp: expected a Lambder instance (what initLambder().create() returns), from the same installed copy of lambder as lambder/testing.");
+        }
+        const own = (store) => { this.ownStores.push(store); return store; };
+        const sessionStore = options.session?.store ?? own(new LambderMemorySessionStore());
+        const rateLimiter = options.rateLimits?.limiter ?? own(new LambderMemoryRateLimiter());
+        const idempotencyStore = options.idempotency?.store ?? own(new LambderMemoryIdempotencyStore());
+        const swap = lambder[LAMBDER_BACKEND_SWAP]({ sessionStore, rateLimiter, idempotencyStore, fileSource: options.files });
+        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.");
+        }
+        lambder[LAMBDER_CRASH_WATCH]((error) => {
+            this.crashList.push(error);
+            const scope = this.crashScope.getStore();
+            if (scope)
+                scope.crash = error;
+        });
+        this.lambder = lambder;
+        this.handler = lambder.getHandler();
+        this.host = options.host ?? "localhost";
+        this.sessionStore = swap.sessions ? sessionStore : null;
+        this.rateLimiter = swap.rateLimits ? rateLimiter : null;
+        this.idempotencyStore = swap.idempotency ? idempotencyStore : null;
+        this.wiring = {
+            handler: this.handler,
+            apiPath: lambder.apiPath,
+            eventFormat: options.eventFormat ?? "v2",
+            sessionCookieNames: swap.sessions,
+            resetCount: () => this.resetCount,
+            watchCrash: async (run) => {
+                const scope = { crash: null };
+                return { result: await this.crashScope.run(scope, run), crash: scope.crash };
+            },
+            issueSession: async (host, sessionKey, data, ttlSeconds) => {
+                // Through a session controller on a request context, the way a
+                // login handler does it, so the cookies are the ones the app's
+                // own cookie options produce for that host.
+                const event = synthesizeLambdaHttpEvent({ method: "GET", path: "/", host }, { invoke: false });
+                const ctx = createContext(event, localLambdaContext("lambder-test"), lambder.apiPath);
+                const created = await lambder.getSessionController(ctx).issueSession(sessionKey, data, ttlSeconds);
+                const headers = {};
+                ctx.responseHeaders.applyInto(headers);
+                return { created, setCookies: getAnswerHeader(headers, "Set-Cookie") ?? [] };
+            },
+        };
+    }
+    /**
+     * 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() {
+        return this.crashList;
+    }
+    /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */
+    get sessionManager() {
+        return this.lambder.getSessionManager();
+    }
+    /**
+     * 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(...[options]) {
+        this.visitorCount += 1;
+        return new LambderTestVisitor(this.wiring, {
+            ...options,
+            host: options?.host ?? this.host,
+            // One private address per visitor, counted up and never handed out
+            // twice, so no two visitors share a per-ip counter by accident.
+            clientIp: options?.clientIp ?? `10.${(this.visitorCount >> 16) & 255}.${(this.visitorCount >> 8) & 255}.${this.visitorCount & 255}`,
+        });
+    }
+    /**
+     * 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 });
+     * ```
+     */
+    async signIn(sessionKey, data, ...[options]) {
+        const { ttlSeconds, ...visitorOptions } = (options ?? {});
+        const visitor = this.visitor(...[visitorOptions]);
+        await visitor.signIn(sessionKey, data, { ttlSeconds });
+        return visitor;
+    }
+    /**
+     * 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.
+     */
+    async signOut(sessionKey) {
+        await this.sessionManager.deleteSessionAllByKey(sessionKey);
+    }
+    /** Marks the subject's session data stale, so the next read renews it through the app's dataRefresh. */
+    async expireSessionData(sessionKey) {
+        await this.sessionManager.expireSessionDataAllByKey(sessionKey);
+    }
+    /**
+     * 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" });
+     * ```
+     */
+    async event(event, context = {}) {
+        return await this.handler(event, localLambdaContext("lambder-test", context));
+    }
+    /**
+     * 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() {
+        for (const store of this.ownStores)
+            store.reset();
+        this.crashList.length = 0;
+        this.resetCount += 1;
+    }
+}
+/**
+ * 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 const lambderTestApp = (lambder, options = {}) => new LambderTestApp(lambder, options);

package/dist/testing/LambderTestVisitor.d.ts

@@ -0,0 +1,155 @@
+import LambderCaller from "../client/LambderCaller.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 { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { 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.
+ */
+export type LambderTestVisitorOptions<TContract, TProvidedGuards extends string = never> = {
+    /** The host this visitor browses (ctx.host), and the host its cookies are scoped to. Default: the test app's. */
+    host?: string;
+    /**
+     * The address the gateway observed (ctx.ip). Default: one no other
+     * visitor of this test app has, so a `per: "ip"` rate limit counts each
+     * visitor apart, as it does for two people in production. Give two
+     * visitors the same one to test what a shared address does.
+     */
+    clientIp?: string;
+    /** Headers every request of this visitor carries, under those a single call or request adds: what a CDN in front of the app writes (a country header), or a user agent. */
+    headers?: Record<string, string>;
+    /** Sent with every API call as `version`. Default: none, and a call naming no version is not judged by minApiVersion. */
+    apiVersion?: string;
+    /** Sent per API call as `signature`. Default: none, and a call carrying no signature is never gated; pass a map to test the gate itself. */
+    apiSignatures?: LambderApiSignatureMap;
+} & LambderGuardInputsProviderOption<TContract, TProvidedGuards>;
+/** What `request()` sends beside the method and the path. */
+export type LambderTestRequestInit = {
+    /** Query parameters, merged over any the path itself carries. */
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Sent as is: a string is JSON unless a content-type header says otherwise, a Buffer is binary. */
+    body?: string | Buffer;
+};
+/**
+ * What a test app hands each of its visitors: the handler they call, and the
+ * one thing a visitor cannot do alone, which is start a session without a
+ * login endpoint. The session model is the instance's, so the test app mints
+ * and the visitor keeps the cookies.
+ */
+export type LambderTestVisitorWiring<TSessionData> = {
+    handler: LambderHandler;
+    apiPath: string;
+    /** The gateway shape every event is synthesized in; the test app's, since a deployment sits behind one gateway. */
+    eventFormat: LambderHttpEventFormat;
+    /** The app's session cookie names, or null when it has no sessions. */
+    sessionCookieNames: {
+        tokenCookieKey: string;
+        csrfCookieKey: string;
+    } | null;
+    issueSession: (host: string, sessionKey: string, data: TSessionData, ttlSeconds?: number) => Promise<{
+        created: LambderCreatedSession<TSessionData>;
+        setCookies: string[];
+    }>;
+    /** How many times the test app was reset. A visitor compares it with the count it last saw, so the test app keeps no list of the visitors it made. */
+    resetCount: () => number;
+    /** Runs one call, and hands back beside its result the error the app threw while answering it, if it crashed. */
+    watchCrash: <TResult>(run: () => Promise<TResult>) => Promise<{
+        result: TResult;
+        crash: Error | null;
+    }>;
+};
+/**
+ * The options argument of `visitor()` and `signIn()`: optional, until the
+ * call names provided guards. Then the provider that supplies them is
+ * required, as it is on LambderCaller, since naming guards without one would
+ * send nothing for them.
+ */
+export type LambderTestVisitorArgs<TOptions, TProvidedGuards extends string> = [
+    TProvidedGuards
+] extends [never] ? [options?: TOptions] : [options: TOptions];
+/**
+ * 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:
+ * pages, redirects, session routes, file requests. Both carry the same jar,
+ * so a session started through one is the session the other presents.
+ *
+ * Created by `LambderTestApp.visitor()` and `signIn()`, not constructed.
+ */
+export declare class LambderTestVisitor<TContract extends LambderApiContractShape = any, TSessionData = any, TProvidedGuards extends string = never> {
+    readonly host: string;
+    readonly clientIp: string;
+    /**
+     * The typed caller `api` and `apiOutcome` run on, for code under test
+     * that takes a LambderCaller itself (a frontend store, a shared client
+     * module): handed this one, it talks to the real server in this process.
+     * 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: LambderCaller<TContract, TProvidedGuards>["api"];
+    /**
+     * The full outcome, never throwing: LambderCaller.apiOutcome, through
+     * this visitor. Pair it with assertApiSuccess / assertApiFailure.
+     *
+     * One thing is added to what the caller hands back. When the app crashed
+     * answering the call, the outcome is the `server` failure any client
+     * would get, whose error says "Request failed: 500" and nothing else;
+     * here that error's `cause` is what the app actually threw, stack
+     * included, so a failing test points at the line in the handler.
+     */
+    readonly apiOutcome: LambderCaller<TContract, TProvidedGuards>["apiOutcome"];
+    private readonly wiring;
+    private readonly headers;
+    private readonly cookieJar;
+    private seenResetCount;
+    constructor(wiring: LambderTestVisitorWiring<TSessionData>, options: LambderTestVisitorOptions<TContract, TProvidedGuards> & {
+        host: string;
+        clientIp: string;
+    });
+    /**
+     * This visitor's cookies, to inspect or clear; every call and request
+     * reads and fills them. Emptied by the test app's reset(), which a
+     * visitor notices here, the next time anything asks for its cookies: a
+     * jar still holding the token of an emptied store would read as signed
+     * in until an answer said otherwise.
+     */
+    get jar(): LambderCookieJar;
+    /**
+     * One HTTP request to the app that is not an API call, answered by
+     * whatever answers it in production: a route, a session route, the public
+     * files, the index page, a fallback. The answer comes back decoded
+     * (decompressed, headers lowercased), redirects are not followed, and
+     * its Set-Cookie headers land in this visitor's jar.
+     *
+     * ```typescript
+     * const page = await visitor.request("GET", "/orders?page=2");
+     * expect(page.statusCode).toBe(200);
+     * expect(page.text()).toContain("Your orders");
+     * ```
+     */
+    request(method: string, path: string, init?: LambderTestRequestInit): Promise<LambderLambdaHttpResult>;
+    /**
+     * Starts a session for this visitor without a login endpoint: minted by
+     * the app's own session model, under its own cookie options, and planted
+     * in this visitor's jar, so its next call is signed in. Returns the raw
+     * tokens too, as LambderMockApp.signIn does.
+     *
+     * Throws when the cookies do not stick. An app that scopes its session
+     * cookie to a domain (`cookie: { domain: ".example.com" }`) writes one
+     * this visitor's host is not under, a browser on that host would drop it,
+     * and so does the jar; left silent, every session call after it answers
+     * sessionExpired with nothing to say why.
+     */
+    signIn(sessionKey: string, data: TSessionData, options?: {
+        ttlSeconds?: number;
+    }): Promise<LambderCreatedSession<TSessionData>>;
+}