@geekmidas/constructs 10.0.0-alpha.4 → 10.0.0-alpha.40

package/dist/adaptors/testing.mjs

@@ -1,25 +1,32 @@
-import "../Construct-BD5neF7w.mjs";
-import "../construct-interface-Z4CpS8tK.mjs";
-import { FunctionBuilder } from "../functions-Ck21Uyq0.mjs";
-import "../clone-DblgEZZa.mjs";
-import { Endpoint, ResponseBuilder } from "../Endpoint-Dij_wOcc.mjs";
-import { createCookieHeaderAccessor, createObjectHeaders, publishConstructEvents, publishEvents } from "../lazyAccessors-BoJN3SMd.mjs";
-import { executeWithAuditTransaction } from "../processAudits-Dmts9H_b.mjs";
-import { HonoEndpoint } from "../HonoEndpointAdaptor-BM2jbWht.mjs";
+import { BetterAuth } from "../auth.mjs";
+import { a as publishEvents, i as publishConstructEvents, t as FunctionBuilder } from "../functions-DCIfCRR-.mjs";
+import { n as ResponseBuilder, t as Endpoint } from "../Endpoint-CQAeh1Rh.mjs";
+import { t as Queue } from "../Queue-C1uDgjxt.mjs";
+import { Email } from "../email.mjs";
+import { KyselyDatabase } from "../database/kysely.mjs";
+import { c as createObjectHeaders, r as createCookieHeaderAccessor } from "../lazyAccessors-CFanua0O.mjs";
+import { t as Topic } from "../Topic-hPffOsot.mjs";
+import { t as HonoEndpoint } from "../HonoEndpointAdaptor-Aui-x9Lg.mjs";
+import { n as executeWithAuditTransaction } from "../processAudits-BpRlPQMW.mjs";
+import { provideKey } from "@geekmidas/manifest";
 import { ForbiddenError } from "@geekmidas/errors";
 import { EnvironmentParser } from "@geekmidas/envkit";
-import { ServiceDiscovery, runWithRequestContext } from "@geekmidas/services";
-import { DefaultAuditor } from "@geekmidas/audit";
+import { ServiceDiscovery, runWithRequestContext, serviceContext } from "@geekmidas/services";
 import { Hono } from "hono";
+import { DefaultAuditor } from "@geekmidas/audit";
+import { TEST_CONTEXT_HEADER, currentTestContext, installContextFetch, runAsServer, runInTestContext, testContextOf } from "@geekmidas/testkit/context";
 import { http } from "msw";
-
+import { randomUUID } from "node:crypto";
+import { Browser } from "@geekmidas/testkit/browser";
+import { faker } from "@geekmidas/testkit/faker";
+import { createMailbox } from "@geekmidas/testkit/mailbox";
+import { TransactionRegistry } from "@geekmidas/testkit/transactions";
+import { setupServer } from "msw/node";
+import { afterAll, beforeAll, test } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import tls from "node:tls";
+import { fileURLToPath } from "node:url";
 //#region src/endpoints/MswEndpointAdaptor.ts
-/**
-* Header used to identify which test context a request belongs to.
-* Each concurrent test registers its own context (services, db transaction, etc.)
-* and the MSW handler looks it up by this header value.
-*/
-const TEST_CONTEXT_HEADER = "x-test-context-id";
 const MSW_HTTP_METHODS = [
 	"get",
 	"post",
@@ -67,7 +74,6 @@ function createMswHandlers(endpoints, options) {
 				break;
 			}
 		}
-		if (ctxOptions.publisher) serviceDefs.push(ctxOptions.publisher);
 		if (ctxOptions.auditorStorage !== void 0) {
 			for (const endpoint of endpoints) if (endpoint.auditorStorageService) {
 				serviceDefs.push({
@@ -111,7 +117,6 @@ function createMswHandlers(endpoints, options) {
 		registerContext
 	};
 }
-
 //#endregion
 //#region src/endpoints/TestEndpointAdaptor.ts
 /**
@@ -131,6 +136,8 @@ function serializeCookie(name, value, options) {
 	return cookieString;
 }
 var TestEndpointAdaptor = class TestEndpointAdaptor {
+	endpoint;
+	serviceDiscovery;
 	static getDefaultServiceDiscover(_endpoint) {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -165,7 +172,7 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				cookie,
 				...rawDb !== void 0 && { db: rawDb }
 			});
-			const isAuthorized = await this.endpoint.authorize({
+			if (!await this.endpoint.authorize({
 				header,
 				cookie,
 				services: ctx.services,
@@ -175,8 +182,7 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				body,
 				query,
 				params
-			});
-			if (!isAuthorized) {
+			})) {
 				logger.warn("Forbidden access attempt");
 				throw new ForbiddenError("Forbidden access to the endpoint", "You do not have permission to access this resource.");
 			}
@@ -198,24 +204,22 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 				} catch (error) {
 					logger.error(error, "Failed to extract actor for audits");
 				}
-				const auditor = new DefaultAuditor({
-					actor,
-					storage: auditorStorage,
-					metadata: {
-						endpoint: this.endpoint.route,
-						method: this.endpoint.method
-					}
-				});
 				auditContext = {
-					auditor,
+					auditor: new DefaultAuditor({
+						actor,
+						storage: auditorStorage,
+						metadata: {
+							endpoint: this.endpoint.route,
+							method: this.endpoint.method
+						}
+					}),
 					storage: auditorStorage
 				};
 			}
 			const audits = this.endpoint.audits;
 			if (!auditContext && audits?.length) logger.warn("No auditor storage service available");
-			const result = await executeWithAuditTransaction(auditContext, async (auditor) => {
-				const trx = auditor?.getTransaction?.();
-				const db = trx ?? rawDb;
+			const { output, metadata } = await executeWithAuditTransaction(auditContext, async (auditor) => {
+				const db = auditor?.getTransaction?.() ?? rawDb;
 				const responseBuilder = new ResponseBuilder();
 				const response = await this.endpoint.handler({
 					body,
@@ -230,36 +234,33 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 					db
 				}, responseBuilder);
 				let data = response;
-				let metadata$1 = responseBuilder.getMetadata();
+				let metadata = responseBuilder.getMetadata();
 				if (Endpoint.hasMetadata(response)) {
 					data = response.data;
-					metadata$1 = response.metadata;
+					metadata = response.metadata;
 				}
-				const output$1 = await this.endpoint.parseOutput(data);
 				return {
-					output: output$1,
-					metadata: metadata$1,
+					output: await this.endpoint.parseOutput(data),
+					metadata,
 					responseBuilder
 				};
-			}, async (result$1, auditor) => {
+			}, async (result, auditor) => {
 				if (!audits?.length) return;
 				for (const audit of audits) {
-					if (audit.when && !audit.when(result$1.output)) continue;
-					const payload = audit.payload(result$1.output);
-					const entityId = audit.entityId?.(result$1.output);
+					if (audit.when && !audit.when(result.output)) continue;
+					const payload = audit.payload(result.output);
+					const entityId = audit.entityId?.(result.output);
 					auditor.audit(audit.type, payload, {
 						table: audit.table,
 						entityId
 					});
 				}
 			}, { db: rawDb });
-			const { output, metadata } = result;
-			ctx.publisher && await this.serviceDiscovery.register([ctx.publisher]);
-			await publishConstructEvents(this.endpoint, output, this.serviceDiscovery);
+			await publishConstructEvents(this.endpoint, output, this.serviceDiscovery, this.endpoint.logger, ctx.services);
 			const headers = { ...metadata.headers || {} };
 			if (metadata.cookies && metadata.cookies.size > 0) {
 				const setCookieValues = [];
-				for (const [name, cookie$1] of metadata.cookies.entries()) setCookieValues.push(serializeCookie(name, cookie$1.value, cookie$1.options));
+				for (const [name, cookie] of metadata.cookies.entries()) setCookieValues.push(serializeCookie(name, cookie.value, cookie.options));
 				headers["set-cookie"] = setCookieValues;
 			}
 			return {
@@ -270,14 +271,14 @@ var TestEndpointAdaptor = class TestEndpointAdaptor {
 		});
 	}
 	async request(ctx) {
-		const response = await this.fullRequest(ctx);
-		return response.body;
+		return (await this.fullRequest(ctx)).body;
 	}
 };
-
 //#endregion
 //#region src/functions/TestFunctionAdaptor.ts
 var TestFunctionAdaptor = class TestFunctionAdaptor {
+	fn;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery(_fn) {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -293,15 +294,11 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 		else services = await this.serviceDiscovery.register(this.fn.services);
 		let db;
 		if ("db" in ctx && ctx.db !== void 0) db = ctx.db;
-		else if (this.fn.databaseService) {
-			const dbServices = await this.serviceDiscovery.register([this.fn.databaseService]);
-			db = dbServices[this.fn.databaseService.serviceName];
-		}
+		else if (this.fn.databaseService) db = (await this.serviceDiscovery.register([this.fn.databaseService]))[this.fn.databaseService.serviceName];
 		let auditor;
 		if ("auditor" in ctx && ctx.auditor !== void 0) auditor = ctx.auditor;
 		else if (this.fn.auditorStorageService) {
-			const auditServices = await this.serviceDiscovery.register([this.fn.auditorStorageService]);
-			const storage = auditServices[this.fn.auditorStorageService.serviceName];
+			const storage = (await this.serviceDiscovery.register([this.fn.auditorStorageService]))[this.fn.auditorStorageService.serviceName];
 			auditor = new DefaultAuditor({
 				actor: {
 					id: "system",
@@ -315,11 +312,10 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 			});
 		}
 		const requestId = `test-${Date.now()}`;
-		const startTime = Date.now();
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime: Date.now()
 		}, async () => {
 			const response = await this.fn.fn({
 				input: parsedInput,
@@ -336,12 +332,11 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 					await auditor.flush();
 				}
 			}
-			await publishEvents(logger, this.serviceDiscovery, this.fn.events, output, this.fn.publisherService);
+			await publishEvents(logger, this.serviceDiscovery, this.fn.events, output, services);
 			return output;
 		});
 	}
 };
-
 //#endregion
 //#region src/queue/TestQueueAdaptor.ts
 /**
@@ -354,6 +349,8 @@ var TestFunctionAdaptor = class TestFunctionAdaptor {
 * await adapter.invoke({ messages: [{ orderId: '123' }] });
 */
 var TestQueueAdaptor = class TestQueueAdaptor {
+	queue;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery() {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -365,11 +362,10 @@ var TestQueueAdaptor = class TestQueueAdaptor {
 		const logger = this.queue.logger.child({ test: true });
 		const services = request.services ?? await this.serviceDiscovery.register(this.queue.services);
 		const requestId = `test-${Date.now()}`;
-		const startTime = Date.now();
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime: Date.now()
 		}, () => this.queue.handler({
 			messages: request.messages,
 			services,
@@ -377,10 +373,11 @@ var TestQueueAdaptor = class TestQueueAdaptor {
 		}));
 	}
 };
-
 //#endregion
 //#region src/subscribers/TestSubscriberAdaptor.ts
 var TestSubscriberAdaptor = class TestSubscriberAdaptor {
+	subscriber;
+	serviceDiscovery;
 	static getDefaultServiceDiscovery() {
 		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
 	}
@@ -396,11 +393,10 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 		const filteredEvents = this.filterEvents(request.events);
 		if (filteredEvents.length === 0) return { batchItemFailures: [] };
 		const requestId = `test-${Date.now()}`;
-		const startTime = Date.now();
 		return runWithRequestContext({
 			logger,
 			requestId,
-			startTime
+			startTime: Date.now()
 		}, async () => {
 			const result = await this.subscriber.handler({
 				events: filteredEvents,
@@ -413,7 +409,6 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 				if (validationResult.issues) throw new Error("Subscriber output validation failed");
 				output = validationResult.value;
 			}
-			await publishEvents(logger, this.serviceDiscovery, this.subscriber.events, output, this.subscriber.publisherService);
 			return output;
 		});
 	}
@@ -422,7 +417,428 @@ var TestSubscriberAdaptor = class TestSubscriberAdaptor {
 		return events.filter((event) => this.subscriber.subscribedEvents.includes(event.type));
 	}
 };
-
 //#endregion
-export { TEST_CONTEXT_HEADER, TestEndpointAdaptor, TestFunctionAdaptor, TestQueueAdaptor, TestSubscriberAdaptor, createMswHandlers };
+//#region src/testing/manifest.ts
+/**
+* The test manifest: what `gkm test` knows about an app, written down for the
+* suite it starts.
+*
+* `gkm test` discovers the constructs, reconciles the test stage and resolves
+* its environment — then, until this existed, threw all of it away and left a
+* test to declare it again by hand. The manifest keeps it: which construct and
+* endpoint is exported where, and the environment the test stage resolved,
+* under the keys the constructs themselves derive. A feature test is built from
+* it, so nothing a test says can drift from what the app declares.
+*/
+/** The environment variable `gkm test` names the manifest in. */
+const TEST_MANIFEST_ENV = "GKM_TEST_MANIFEST";
+/**
+* Read a test manifest: from a path, a `file:` URL, or — given nothing — the
+* one `gkm test` named in `GKM_TEST_MANIFEST`.
+*/
+function loadTestManifest(from) {
+	const location = from ?? process.env["GKM_TEST_MANIFEST"];
+	if (!location) throw new NoTestManifest();
+	trustLocalEdge();
+	const path = location instanceof URL || location.startsWith("file:") ? fileURLToPath(location) : location;
+	return JSON.parse(readFileSync(path, "utf-8"));
+}
+let trusted = false;
+/**
+* Trust the local edge's certificate authority in this thread.
+*
+* `NODE_EXTRA_CA_CERTS` does it for a process started with it — which a
+* suite started by `gkm test` is, and one started by plain `vitest` or an
+* editor is not: its setup only learns the path once Vitest is running, and a
+* worker *thread* shares that process and keeps a TLS store of its own. Every
+* feature test loads the manifest, so this is the one place each worker passes
+* through.
+*/
+function trustLocalEdge() {
+	const certificate = process.env.NODE_EXTRA_CA_CERTS;
+	if (trusted || !certificate || !existsSync(certificate)) return;
+	trusted = true;
+	tls.setDefaultCACertificates([...tls.getCACertificates("default"), readFileSync(certificate, "utf-8")]);
+}
+/** A feature test ran without a manifest to build itself from. */
+var NoTestManifest = class extends Error {
+	constructor() {
+		super(`No test manifest: run the suite with \`gkm test\`, or add \`globalSetup: ['@geekmidas/cli/vitest']\` to the root vitest config — either writes one and names it in ${TEST_MANIFEST_ENV}.`);
+		this.name = "NoTestManifest";
+	}
+};
+//#endregion
+//#region src/testing/featureTest.ts
+/**
+* `featureTest`: an app, driven the way it runs deployed.
+*
+* A browser signs in and calls the API; the API calls the auth server; each
+* over its URL, each database in its own transaction. Nothing runs as a server:
+* every URL an app's constructs answer on is served in-process through MSW,
+* from the real handler, for the test that made the request. Everything else
+* with a real local equivalent — Postgres, Mailpit, MinIO — is used directly.
+*
+* It is built from the test manifest `gkm test` writes — the constructs and
+* endpoints the app exports, and the environment the test stage resolved — so
+* a test declares none of it. `gkm test` also generates the configured `it`
+* and a `Browser` with a typed client per surface:
+*
+* ```ts
+* import { it } from '#test';
+*
+* it('shows the signed-in user their profile', async ({ browser, mailbox }) => {
+*   await browser.auth.signIn.magicLink({ email: 'ada@shop.test' });
+*   await browser.visit((await mailbox('ada@shop.test').last()).link!);
+*   expect(await browser.api.get('/profile')).toMatchObject({ email: 'ada@shop.test' });
+* });
+* ```
+*/
+/** Every test in flight in this process, by id. */
+const contexts = /* @__PURE__ */ new Map();
+/** Databases already resolving to test transactions — patched once each. */
+const bound = /* @__PURE__ */ new WeakSet();
+function featureTest(options = {}) {
+	const manifest = options.manifest ?? loadTestManifest();
+	const BrowserClass = options.browser ?? Browser;
+	let app;
+	let factoryDatabases = [];
+	let owned = [];
+	let network;
+	let restoreFetch = () => {};
+	beforeAll(async () => {
+		app = await load(manifest, options.modules ?? {});
+		owned = ownDatabases(app, manifest);
+		factoryDatabases = databasesFor(options.factories ?? {}, owned);
+		for (const database of app.databases) bindToTests(database);
+		network = setupServer(...surfaceHandlers(app.endpoints, manifest.env), ...app.auths.map((auth) => authHandler(auth, manifest.env, app.envParser)), ...Object.entries(options.fakes ?? {}).flatMap(([id, fake]) => fakeHandler(id, fake, manifest.env)));
+		network.listen({ onUnhandledRequest(request, print) {
+			if (isLocal(new URL(request.url))) return;
+			print.error();
+		} });
+		restoreFetch = installContextFetch();
+	});
+	afterAll(() => {
+		restoreFetch();
+		network?.close();
+	});
+	const run = (name, fn) => async () => {
+		const id = randomUUID();
+		faker.seed(seedOf(name));
+		const state = {
+			transactions: new TransactionRegistry(),
+			discovery: new ServiceDiscovery(app.envParser),
+			surfaces: /* @__PURE__ */ new Map(),
+			auth: /* @__PURE__ */ new Map(),
+			addresses: /* @__PURE__ */ new Set(),
+			published: /* @__PURE__ */ new Map()
+		};
+		const readMail = app.readMail;
+		if (readMail) state.mailbox = (address) => {
+			state.addresses.add(address);
+			return readMail(address);
+		};
+		contexts.set(id, state);
+		await state.discovery.register(recorders(app.channels, state));
+		try {
+			await runInTestContext(id, async () => {
+				const browser = new BrowserClass();
+				const restore = browser.install();
+				try {
+					const transaction = (database) => state.transactions.get(database.id, urlOf(database, app.envParser), database.clientConfig);
+					const db = { get: (name) => {
+						const database = owned.find((candidate) => candidate.service.serviceName === name);
+						if (!database) throw new UnknownDatabase(name, owned.map((candidate) => candidate.service.serviceName));
+						return transaction(database);
+					} };
+					const built = /* @__PURE__ */ new Map();
+					await fn({
+						browser,
+						db,
+						factories: { get: (name) => {
+							const database = factoryDatabases.find(([candidate]) => candidate === name)?.[1];
+							if (!database) throw new UnknownFactory(name, factoryDatabases.map(([candidate]) => candidate));
+							let factory = built.get(name);
+							if (!factory) {
+								factory = transaction(database).then(options.factories[name]);
+								built.set(name, factory);
+							}
+							return factory;
+						} },
+						faker,
+						mailbox: (address) => {
+							if (!state.mailbox) throw new NoInbox();
+							return state.mailbox(address);
+						},
+						published: (channel) => [...state.published.get(channel.id) ?? []],
+						subscriber: (subscriber) => new TestSubscriberAdaptor(subscriber, state.discovery),
+						queue: (queue) => new TestQueueAdaptor(queue, state.discovery)
+					});
+				} finally {
+					restore();
+				}
+			});
+		} finally {
+			contexts.delete(id);
+			await Promise.all([state.transactions.rollbackAll(), ...[...state.addresses].map((address) => app.readMail?.(address).clear())]);
+		}
+	};
+	const it = ((name, fn, timeout) => test(name, run(name, fn), timeout));
+	it.only = (name, fn, timeout) => test.only(name, run(name, fn), timeout);
+	it.skip = (name, fn, timeout) => test.skip(name, run(name, fn), timeout);
+	return it;
+}
+/**
+* A test's faker seed, from its name: the same test draws the same data on
+* every run, and two tests draw different data.
+*/
+function seedOf(name) {
+	let hash = 0;
+	for (const char of name) hash = Math.imul(hash, 31) + char.charCodeAt(0) | 0;
+	return hash >>> 0;
+}
+/**
+* Import what the manifest points at.
+*
+* The same modules the app runs, so a construct here *is* the app's construct —
+* the one its endpoints were built from — never a copy declared again.
+*/
+async function load(manifest, modules) {
+	const envParser = new EnvironmentParser({ ...manifest.env });
+	const imported = async ({ file, export: name }) => (modules[file] ?? await import(file))[name];
+	const constructs = await Promise.all(Object.values(manifest.constructs).map(({ source }) => imported(source)));
+	const endpoints = (await Promise.all(manifest.endpoints.map(({ source }) => imported(source)))).filter((value) => Endpoint.isEndpoint(value));
+	const unique = (values) => [...new Set(values)];
+	const databases = unique(constructs.filter((value) => value instanceof KyselyDatabase));
+	const auths = unique(constructs.filter((value) => value instanceof BetterAuth));
+	const emails = unique(constructs.filter((value) => value instanceof Email));
+	const channels = unique(constructs.filter((value) => value instanceof Topic || value instanceof Queue));
+	const inbox = emails.map((email) => manifest.env[provideKey(email.id, "inboxUrl")]).find(Boolean);
+	return {
+		envParser,
+		endpoints,
+		databases,
+		auths,
+		emails,
+		channels,
+		...inbox ? { readMail: createMailbox({ inbox }) } : {}
+	};
+}
+/**
+* A publisher that records rather than sends, under the name a topic or queue
+* is injected by — `services.users` — which is also the one `.event(users, …)`
+* publishes through.
+*/
+function recorders(channels, state) {
+	return channels.map((channel) => {
+		const publisher = { async publish(messages) {
+			state.published.set(channel.id, [...state.published.get(channel.id) ?? [], ...messages.map(({ type, payload }) => ({
+				type,
+				payload
+			}))]);
+		} };
+		return {
+			serviceName: channel.service.serviceName,
+			register: () => publisher
+		};
+	});
+}
+/**
+* The databases a test is handed: the app's own. A schema tenant an auth server
+* owns is reached through that server, as the app reaches it, and a reader is
+* the same database through a read-only role — neither is another database to
+* test against.
+*/
+function ownDatabases(app, manifest) {
+	const owners = new Set(app.auths.map((auth) => auth.databaseId));
+	return app.databases.filter((database) => !owners.has(database.id) && manifest.constructs[database.id]?.kind !== "database-reader");
+}
+/** Each factory's database, found by the service name it is keyed by. */
+function databasesFor(factories, databases) {
+	return Object.keys(factories).map((name) => {
+		const database = databases.find((candidate) => candidate.service.serviceName === name);
+		if (!database) throw new UnknownFactory(name, databases.map((candidate) => candidate.service.serviceName));
+		return [name, database];
+	});
+}
+/**
+* Make a database resolve, inside a test, to that test's transaction.
+*
+* Everything reaches a database through its service — an endpoint through
+* service discovery, the auth server through its tenant directly — so this is
+* the one place a test's connection can be handed over. Outside a test it is
+* the database it always was.
+*/
+function bindToTests(database) {
+	if (bound.has(database)) return;
+	bound.add(database);
+	const service = database.service;
+	const register = service.register;
+	service.register = (options) => {
+		const context = currentTestContext();
+		const state = context && contexts.get(context.id);
+		if (!state) return register(options);
+		return state.transactions.get(database.id, urlOf(database, options.envParser), database.clientConfig);
+	};
+}
+function urlOf(database, envParser) {
+	return envParser.create((get) => ({ url: get(provideKey(database.id, "url")).string() })).parse().url;
+}
+/** Each surface's endpoints, served at its URL for the test that asked. */
+function surfaceHandlers(endpoints, env) {
+	const bySurface = /* @__PURE__ */ new Map();
+	for (const endpoint of endpoints) {
+		const surface = endpoint.surface?.id;
+		if (!surface) continue;
+		bySurface.set(surface, [...bySurface.get(surface) ?? [], endpoint]);
+	}
+	return [...bySurface].flatMap(([surface, served]) => {
+		const base = env[provideKey(surface, "url")];
+		if (!base) return [];
+		return http.all(`${trim(base)}/*`, ({ request }) => serve(request, async (state) => {
+			let app = state.surfaces.get(surface);
+			if (!app) {
+				app = Promise.resolve().then(() => {
+					const hono = new Hono();
+					HonoEndpoint.addRoutes(served, state.discovery, hono);
+					return hono;
+				});
+				state.surfaces.set(surface, app);
+			}
+			return (await app).fetch(request);
+		}));
+	});
+}
+/**
+* An external API's app fake, answering at the URL the test stage resolved for
+* it — so a handler that calls Polar calls the fake, and the test sets up
+* nothing.
+*
+* Not per test, unlike a surface: a fake stands in for somebody else's server,
+* which no test's transaction reaches. An image fake has no handler here — its
+* container answers on localhost, which is let through.
+*/
+function fakeHandler(id, fake, env) {
+	const base = env[provideKey(id, "url")];
+	if (fake.kind !== "app" || !base) return [];
+	return [http.all(`${trim(base)}/*`, ({ request }) => fake.handler.fetch(request))];
+}
+/** An auth server, served at its URL, on the transaction of the test that asked. */
+function authHandler(auth, env, envParser) {
+	const base = trim(env[provideKey(auth.id, "url")] ?? "");
+	return http.all(`${base}/*`, ({ request }) => serve(request, async (state) => {
+		let app = state.auth.get(auth);
+		if (!app) {
+			app = auth.server({
+				envParser,
+				context: serviceContext
+			}).then(({ app }) => app);
+			state.auth.set(auth, app);
+		}
+		return (await app).fetch(request);
+	}));
+}
+/** Handle a request as the server side of the test it was made for. */
+async function serve(request, handle) {
+	const id = testContextOf(request);
+	const state = id ? contexts.get(id) : void 0;
+	if (!id || !state) throw new UnknownTestContext(request.url, id);
+	return runAsServer(id, () => handle(state));
+}
+function trim(url) {
+	return url.replace(/\/$/, "");
+}
+function isLocal(url) {
+	return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname.endsWith(".localhost");
+}
+/**
+* Sign a test's browser in the way a person does: ask the auth server for a
+* magic link, open the email it sent, follow the link.
+*
+* What the generated `browser.signIn(email)` calls. The address's mail is
+* cleared first — so the link is this request's, not one an earlier test left
+* — and cleared again after the test, like any address a test reads. Returns
+* the session the auth server then reports, as better-auth hands it back.
+*/
+async function signInWithMagicLink(browser, auth, email = freshAddress()) {
+	const context = currentTestContext();
+	const state = context && contexts.get(context.id);
+	if (!state) throw new UnknownTestContext("signIn", context?.id);
+	if (!state.mailbox) throw new NoInbox();
+	const inbox = state.mailbox(email);
+	await inbox.clear();
+	const requested = await auth.signIn.magicLink({ email });
+	if (requested.error) throw new SignInFailed(email, `the auth server refused the magic link: ${requested.error.message ?? "no reason given"}`);
+	const mail = await inbox.last();
+	if (!mail.link) throw new SignInFailed(email, "its email held no link");
+	await browser.visit(mail.link);
+	const { data } = await auth.getSession();
+	if (!data) throw new SignInFailed(email, "the auth server reported no session after the link was opened");
+	return data;
+}
+/**
+* An address nobody else signs in as — what `browser.signIn()` uses when the
+* test does not care who it is.
+*
+* Unique rather than only seeded: tests in other files run at the same time,
+* against the same Mailpit and the same unique columns, and a seeded address
+* repeats wherever two tests share a name. The readable half is the seeded
+* faker's, so a failure still names somebody.
+*/
+function freshAddress() {
+	return `${faker.internet.username().toLowerCase().replace(/[^a-z0-9]/g, "")}.${randomUUID().slice(0, 8)}@example.test`;
+}
+/** `browser.signIn` finished without a session. */
+var SignInFailed = class extends Error {
+	email;
+	reason;
+	constructor(email, reason) {
+		super(`Signing ${email} in failed: ${reason}.`);
+		this.email = email;
+		this.reason = reason;
+		this.name = "SignInFailed";
+	}
+};
+/** A request reached an in-process server without a test to belong to. */
+var UnknownTestContext = class extends Error {
+	url;
+	id;
+	constructor(url, id) {
+		super(id ? `${url} was requested for test ${id}, which is not running. A request that outlives its test — an un-awaited call — lands here.` : `${url} was requested outside any test. Make the request inside a featureTest, so it reaches that test's transactions.`);
+		this.url = url;
+		this.id = id;
+		this.name = "UnknownTestContext";
+	}
+};
+/** `mailbox` was used in an app that declares no Email construct. */
+var NoInbox = class extends Error {
+	constructor() {
+		super("mailbox() reads the inbox of the app's Email construct, and none was found in featureTest's modules — or `gkm test` did not inject its <ID>_INBOX_URL.");
+		this.name = "NoInbox";
+	}
+};
+/** `db.get(name)` named no database the test is handed. */
+var UnknownDatabase = class extends Error {
+	database;
+	known;
+	constructor(database, known) {
+		super(`db.get('${database}') names no database of this app's. ` + (known.length > 0 ? `Its databases: ${known.join(", ")}. ` : "It declares no database of its own. ") + "A tenant an auth server owns is reached through that server, and a reader through the database it reads.");
+		this.database = database;
+		this.known = known;
+		this.name = "UnknownDatabase";
+	}
+};
+/** A factory keyed by a service name no database the app declares has. */
+var UnknownFactory = class extends Error {
+	factory;
+	known;
+	constructor(factory, known) {
+		super(`There is a test factory for '${factory}', and no database this app declares is called that. ` + (known.length > 0 ? `Its databases: ${known.join(", ")}. ` : "It declares no database. ") + `Name the file after the database construct: test/factories/<construct>.ts.`);
+		this.factory = factory;
+		this.known = known;
+		this.name = "UnknownFactory";
+	}
+};
+//#endregion
+export { NoInbox, NoTestManifest, SignInFailed, TEST_CONTEXT_HEADER, TEST_MANIFEST_ENV, TestEndpointAdaptor, TestFunctionAdaptor, TestQueueAdaptor, TestSubscriberAdaptor, UnknownDatabase, UnknownFactory, UnknownTestContext, createMswHandlers, featureTest, loadTestManifest, signInWithMagicLink };
+
 //# sourceMappingURL=testing.mjs.map