@warp-drive/holodeck 0.1.0-alpha.85 → 0.1.0-alpha.88

package/README.md

@@ -8,13 +8,11 @@
     />
 </p>
 
-![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
-![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![NPM Stable Version](https://img.shields.io/npm/v/%40warp-drive%2Fholodeck/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/%40warp-drive%2Fholodeck.svg?style=flat&color=fdb155)
 ![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
-[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
-)
-[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
-)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS)
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S)
 
 <p align="center">
   <br>

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ScaffoldGenerator } from "./mock.js";
+import { LazyScaffold, ScaffoldGenerator } from "./mock.js";
 import { Handler, NextFn } from "@warp-drive/core/request";
 import { RequestContext, StructuredDataDocument } from "@warp-drive/core/types/request";
 import { Store } from "@warp-drive/legacy/store";
@@ -50,6 +50,6 @@ export declare function installAdapterFor(owner: object, store: Store): void;
  *
  * @public
  */
-export declare function mock(owner: object, generate: ScaffoldGenerator, isRecording?: boolean): Promise<void>;
+export declare function mock(owner: object, generate: ScaffoldGenerator | LazyScaffold, isRecording?: boolean): Promise<void>;
 //#endregion
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;wBAuIgB,YAAY;EAAU;;;;;wBAQtB,UAAU,iBAAiB;;;;wBA2C3B,eAAe;;;;wBAOf;;;;;;;;;;;;qBAeH,6BAA6B;EACxC;EACA,YAAY;EAGZ,QAAc,GAAG,SAAS,gBAAgB,MAAM,OAAO,KAAK,QAAQ,uBAAuB;;;;;;;;;wBAkG7E,kBAAkB,eAAe,OAAO;;;;;;wBAuClC,KAAK,eAAe,UAAU,mBAAmB,wBAAwB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;wBA6IgB,YAAY;EAAU;;;;;wBAQtB,UAAU,iBAAiB;;;;wBAoG3B,eAAe;;;;wBAOf;;;;;;;;;;;;qBAeH,6BAA6B;EACxC;EACA,YAAY;EAGZ,QAAc,GAAG,SAAS,gBAAgB,MAAM,OAAO,KAAK,QAAQ,uBAAuB;;;;;;;;;wBAwI7E,kBAAkB,eAAe,OAAO;;;;;;wBAuClC,KACpB,eACA,UAAU,oBAAoB,cAC9B,wBACC"}

package/dist/index.js

@@ -6,6 +6,10 @@ import { getGlobalConfig, macroCondition } from "@embroider/macros";
 * @mergeModuleWith <project>
 */
 const TEST_IDS = /* @__PURE__ */ new WeakMap();
+/**
+* The shape `setTestId` stores per test context, named so the report below can
+* take one as an argument.
+*/
 let HOST = "/";
 /**
 * @public
@@ -45,7 +49,49 @@ function setTestId(context, str) {
 			TRACE: {}
 		}
 	});
-	else TEST_IDS.delete(context);
+	else {
+		const test = TEST_IDS.get(context);
+		TEST_IDS.delete(context);
+		if (test) reportUnrequestedMocks(test);
+	}
+}
+/**
+* A mock is declared relative to the mock server (`users/1`) while the request
+* carries the absolute url the code under test built
+* (`https://localhost:7358/users/1`). The mock server reconciles the two by
+* keying a fixture on the request's path, so compare them the same way.
+*/
+function normalizeUrlKey(url) {
+	const withoutOrigin = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "");
+	return withoutOrigin.startsWith("/") ? withoutOrigin.slice(1) : withoutOrigin;
+}
+/**
+* A mock the test never requested proves nothing: the test passes whether or
+* not the code under test would have made that request. Nothing compared the
+* two counters holodeck already keeps, so report the difference here, from the
+* `afterEach` every suite runs, which fails the test that leaked.
+*
+* The original assertions are not masked by this: a framework reports an
+* `afterEach` throw alongside the results the test body already recorded
+* rather than in place of them.
+*/
+function reportUnrequestedMocks(test) {
+	const unrequested = [];
+	for (const method of Object.keys(test.mock)) {
+		const mocked = test.mock[method];
+		const requested = test.request[method] ?? {};
+		const requestCounts = /* @__PURE__ */ new Map();
+		for (const url of Object.keys(requested)) {
+			const key = normalizeUrlKey(url);
+			requestCounts.set(key, (requestCounts.get(key) ?? 0) + requested[url]);
+		}
+		for (const url of Object.keys(mocked)) {
+			const mockCount = mocked[url];
+			const requestCount = requestCounts.get(normalizeUrlKey(url)) ?? 0;
+			if (mockCount > requestCount) unrequested.push(`\t${method} ${url} (mocked ${mockCount}, requested ${requestCount})`);
+		}
+	}
+	if (unrequested.length) throw new Error(`Holodeck: this test declared mocks it never requested.\n\n${unrequested.join("\n")}\n\nA mock that is never requested proves nothing. Remove it, or make the request it describes.`);
 }
 const shouldRecord = macroCondition(getGlobalConfig().WarpDrive.env.SHOULD_RECORD) ? true : false;
 let IS_RECORDING = null;
@@ -83,11 +129,34 @@ var MockServerHandler = class {
 			context.setStream(future.getStream());
 			return await future;
 		} catch (e) {
-			if (e instanceof Error && !(e instanceof DOMException)) e.message = e.message.replace(queryForTest, "");
+			if (e instanceof Error && !(e instanceof DOMException)) {
+				const explanation = getHolodeckExplanation(e);
+				if (explanation) e.message = `${e.message}\n\n${explanation}`;
+				e.message = e.message.split(queryForTest).join("");
+			}
 			throw e;
 		}
 	}
 };
+const HOLODECK_ERROR_CODES = /* @__PURE__ */ new Set([
+	"MOCK_NOT_FOUND",
+	"MISSING_X_TEST_ID_HEADER",
+	"MISSING_X_TEST_REQUEST_NUMBER_HEADER"
+]);
+/**
+* The mock server explains itself in the response body, which the thrown
+* error only carries as data. Lift that explanation into the message so it
+* reaches a terminal and a CI log.
+*/
+function getHolodeckExplanation(e) {
+	const { content } = e;
+	if (!content || typeof content !== "object") return null;
+	const { errors } = content;
+	if (!Array.isArray(errors)) return null;
+	return errors.filter((error) => {
+		return !!error && typeof error === "object" && HOLODECK_ERROR_CODES.has(error.code);
+	}).map((error) => error.detail).filter((detail) => typeof detail === "string").join("\n\n") || null;
+}
 function setupHolodeckFetch(owner, request) {
 	const test = TEST_IDS.get(owner);
 	if (!test) throw new Error(`MockServerHandler is not configured with a testId. Use setTestId to set the testId for each test`);
@@ -152,27 +221,49 @@ function installAdapterFor(owner, store) {
 * @public
 */
 async function mock(owner, generate, isRecording) {
-	if (getIsRecording() || isRecording) {
-		const test = TEST_IDS.get(owner);
-		if (!test) throw new Error(`Cannot call "mock" before configuring a testId. Use setTestId to set the testId for each test`);
-		const requestToMock = generate();
-		const { url: mockUrl, method } = requestToMock;
-		if (!mockUrl || !method) throw new Error(`MockError: Cannot mock a request without providing a URL and Method`);
-		const mockMethod = method?.toUpperCase() ?? "GET";
-		if (!test.mock[mockMethod]) {
-			console.log(`⚠️ Using custom HTTP method ${mockMethod} for response to request ${mockUrl}`);
-			test.mock[mockMethod] = {};
-		}
-		if (!(mockUrl in test.mock[mockMethod])) test.mock[mockMethod][mockUrl] = 0;
-		const testMockNum = test.mock[mockMethod][mockUrl]++;
-		const url = `${HOST}__record?__xTestId=${test.id}&__xTestRequestNumber=${testMockNum}`;
-		await fetch(url, {
-			method: "POST",
-			body: JSON.stringify(requestToMock),
-			mode: "cors",
-			credentials: "omit",
-			referrerPolicy: ""
-		});
+	const test = TEST_IDS.get(owner);
+	if (!test) throw new Error(`Cannot call "mock" before configuring a testId. Use setTestId to set the testId for each test`);
+	let method;
+	let mockUrl;
+	let buildScaffold;
+	if (typeof generate === "function") {
+		const scaffold = generate();
+		({method, url: mockUrl} = scaffold);
+		buildScaffold = () => scaffold;
+	} else {
+		({method, url: mockUrl} = generate);
+		buildScaffold = generate.scaffold;
+	}
+	if (!mockUrl || !method) throw new Error(`MockError: Cannot mock a request without providing a URL and Method`);
+	const mockMethod = method.toUpperCase() ?? "GET";
+	if (!test.mock[mockMethod]) {
+		console.log(`⚠️ Using custom HTTP method ${mockMethod} for response to request ${mockUrl}`);
+		test.mock[mockMethod] = {};
+	}
+	if (!(mockUrl in test.mock[mockMethod])) test.mock[mockMethod][mockUrl] = 0;
+	const testMockNum = test.mock[mockMethod][mockUrl]++;
+	if (!getIsRecording() && !isRecording) return;
+	const requestToMock = buildScaffold();
+	const url = `${HOST}__record?__xTestId=${test.id}&__xTestRequestNumber=${testMockNum}`;
+	const response = await fetch(url, {
+		method: "POST",
+		body: JSON.stringify(requestToMock),
+		mode: "cors",
+		credentials: "omit",
+		referrerPolicy: ""
+	});
+	if (!response.ok) throw new Error(`MockError: Holodeck failed to record ${mockMethod} ${mockUrl} (${response.status} ${response.statusText}). ${await getRecordFailureDetail(response)}`);
+}
+/**
+* A failed recording is otherwise invisible until the next replay run fails
+* with a missing fixture, so report what the server said at the point of
+* failure.
+*/
+async function getRecordFailureDetail(response) {
+	try {
+		return (await response.json()).errors?.[0]?.detail ?? "The mock server gave no explanation.";
+	} catch {
+		return "The mock server gave no explanation.";
 	}
 }
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["getGlobalConfig","macroCondition","TEST_IDS","WeakMap","HOST","setConfig","host","endsWith","setTestId","context","str","has","Error","set","id","mock","GET","PUT","PATCH","DELETE","POST","QUERY","OPTIONS","HEAD","CONNECT","TRACE","request","delete","shouldRecord","WarpDrive","env","SHOULD_RECORD","IS_RECORDING","setIsRecording","value","Boolean","getIsRecording","MockServerHandler","constructor","owner","next","queryForTest","setupHolodeckFetch","Object","assign","future","setStream","getStream","e","DOMException","message","replace","test","get","url","firstChar","includes","method","toUpperCase","console","log","mode","credentials","referrerPolicy","headers","Headers","upgradeAdapter","adapter","upgradeStore","store","adapterFor","installAdapterFor","fn","holodeckAdapterFor","modelName","_allowMissing","call","hasOverriddenFetch","useFetch","originalFetch","_fetchRequest","bind","options","String","generate","isRecording","requestToMock","mockUrl","mockMethod","testMockNum","fetch","body","JSON","stringify"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\nimport { SHOULD_RECORD } from '@warp-drive/core/build-config/env';\nimport type { Handler, NextFn } from '@warp-drive/core/request';\nimport type { HTTPMethod, RequestContext, RequestInfo, StructuredDataDocument } from '@warp-drive/core/types/request';\nimport type { MinimumAdapterInterface } from '@warp-drive/legacy/compat';\nimport type { Store } from '@warp-drive/legacy/store';\n\nimport type { ScaffoldGenerator } from './mock';\n\nconst TEST_IDS = new WeakMap<\n  object,\n  {\n    id: string;\n    /**\n     * keeps track of the count of calls to record a mock\n     */\n    mock: {\n      /**\n       * For each GET, we keep track of the count\n       * for a specific URL\n       */\n      GET: Record<string, number>;\n      /**\n       * For each PUT, we keep track of the count\n       * for a specific URL\n       */\n      PUT: Record<string, number>;\n      /**\n       * For each PATCH, we keep track of the count\n       * for a specific URL\n       */\n      PATCH: Record<string, number>;\n      /**\n       * For each DELETE, we keep track of the count\n       * for a specific URL\n       */\n      DELETE: Record<string, number>;\n      /**\n       * For each POST, we keep track of the count\n       * for a specific URL\n       */\n      POST: Record<string, number>;\n      /**\n       * For each OPTIONS, we keep track of the count\n       * for a specific URL\n       */\n      OPTIONS: Record<string, number>;\n      /**\n       * For each QUERY, we keep track of the count\n       * for a specific URL\n       */\n      QUERY: Record<string, number>;\n      /**\n       * for each HEAD, we keep track of the count\n       * for a specific URL\n       */\n      HEAD: Record<string, number>;\n      /**\n       * for each CONNECT, we keep track of the count\n       * for a specific URL\n       */\n      CONNECT: Record<string, number>;\n      /**\n       * for each TRACE, we keep track of the count\n       * for a specific URL\n       */\n      TRACE: Record<string, number>;\n    };\n    /**\n     * keeps track of the count of calls to make a request\n     */\n    request: {\n      /**\n       * For each GET, we keep track of the count\n       * for a specific URL\n       */\n      GET: Record<string, number>;\n      /**\n       * For each PUT, we keep track of the count\n       * for a specific URL\n       */\n      PUT: Record<string, number>;\n      /**\n       * For each PATCH, we keep track of the count\n       * for a specific URL\n       */\n      PATCH: Record<string, number>;\n      /**\n       * For each DELETE, we keep track of the count\n       * for a specific URL\n       */\n      DELETE: Record<string, number>;\n      /**\n       * For each POST, we keep track of the count\n       * for a specific URL\n       */\n      POST: Record<string, number>;\n      /**\n       * For each OPTIONS, we keep track of the count\n       * for a specific URL\n       */\n      OPTIONS: Record<string, number>;\n      /**\n       * For each QUERY, we keep track of the count\n       * for a specific URL\n       */\n      QUERY: Record<string, number>;\n      /**\n       * for each HEAD, we keep track of the count\n       * for a specific URL\n       */\n      HEAD: Record<string, number>;\n      /**\n       * for each CONNECT, we keep track of the count\n       * for a specific URL\n       */\n      CONNECT: Record<string, number>;\n      /**\n       * for each TRACE, we keep track of the count\n       * for a specific URL\n       */\n      TRACE: Record<string, number>;\n    };\n  }\n>();\n\nlet HOST = '/';\n\n/**\n * @public\n */\n\nexport function setConfig({ host }: { host: string }): void {\n  HOST = host.endsWith('/') ? host : `${host}/`;\n}\n\n/**\n * @public\n */\n\nexport function setTestId(context: object, str: string | null): void {\n  if (str && TEST_IDS.has(context)) {\n    throw new Error(`MockServerHandler is already configured with a testId.`);\n  }\n  if (str) {\n    TEST_IDS.set(context, {\n      id: str,\n      mock: {\n        GET: {},\n        PUT: {},\n        PATCH: {},\n        DELETE: {},\n        POST: {},\n        QUERY: {},\n        OPTIONS: {},\n        HEAD: {},\n        CONNECT: {},\n        TRACE: {},\n      },\n      request: {\n        GET: {},\n        PUT: {},\n        PATCH: {},\n        DELETE: {},\n        POST: {},\n        QUERY: {},\n        OPTIONS: {},\n        HEAD: {},\n        CONNECT: {},\n        TRACE: {},\n      },\n    });\n  } else {\n    TEST_IDS.delete(context);\n  }\n}\n\nconst shouldRecord = SHOULD_RECORD ? true : false;\nlet IS_RECORDING: boolean | null = null;\n\n/**\n * @public\n */\nexport function setIsRecording(value: boolean): void {\n  IS_RECORDING = value === null ? value : Boolean(value);\n}\n\n/**\n * @public\n */\nexport function getIsRecording(): boolean {\n  return IS_RECORDING === null ? shouldRecord : IS_RECORDING;\n}\n\n/**\n * A request handler that intercepts requests and routes them through\n * the Holodeck mock server.\n *\n * This handler modifies the request URL to include test identifiers\n * and manages request counts for accurate mocking.\n *\n * Requires that the test context be configured with a testId using `setTestId`.\n *\n * @param owner - the test context object used to retrieve the test ID.\n */\nexport class MockServerHandler implements Handler {\n  declare owner: object;\n  constructor(owner: object) {\n    this.owner = owner;\n  }\n  async request<T>(context: RequestContext, next: NextFn<T>): Promise<StructuredDataDocument<T>> {\n    const { request, queryForTest } = setupHolodeckFetch(this.owner, Object.assign({}, context.request));\n\n    try {\n      const future = next(request);\n      context.setStream(future.getStream());\n      return await future;\n    } catch (e) {\n      if (e instanceof Error && !(e instanceof DOMException)) {\n        e.message = e.message.replace(queryForTest, '');\n      }\n      throw e;\n    }\n  }\n}\n\nfunction setupHolodeckFetch(owner: object, request: RequestInfo): { request: RequestInfo; queryForTest: string } {\n  const test = TEST_IDS.get(owner);\n  if (!test) {\n    throw new Error(`MockServerHandler is not configured with a testId. Use setTestId to set the testId for each test`);\n  }\n\n  const url = request.url!;\n  const firstChar = url.includes('?') ? '&' : '?';\n  const method = (request.method?.toUpperCase() ?? 'GET') as HTTPMethod;\n\n  // enable custom methods\n  if (!test.request[method]) {\n    // oxlint-disable-next-line no-console\n    console.log(`⚠️ Using custom HTTP method ${method} for response to request ${url}`);\n\n    test.request[method] = {};\n  }\n  if (!(url in test.request[method])) {\n    test.request[method][url] = 0;\n  }\n\n  const queryForTest = `${firstChar}__xTestId=${test.id}&__xTestRequestNumber=${test.request[method][url]++}`;\n  request.url = url + queryForTest;\n  request.method = method;\n\n  request.mode = 'cors';\n  request.credentials = 'omit';\n  request.referrerPolicy = '';\n\n  // since holodeck currently runs on a separate port\n  // and we don't want to trigger cors pre-flight\n  // we convert PUT to POST to keep the request in the\n  // \"simple\" cors category.\n  // if (request.method === 'PUT') {\n  //   request.method = 'POST';\n  // }\n\n  const headers = new Headers(request.headers);\n  if (headers.has('Content-Type')) {\n    // under the rules of simple-cors, content-type can only be\n    // one of three things, none of which are what folks typically\n    // set this to. Since holodeck always expects body to be JSON\n    // this \"just works\".\n    headers.set('Content-Type', 'text/plain');\n    request.headers = headers;\n  }\n\n  return { request, queryForTest };\n}\n\ninterface HasAdapterForFn {\n  adapterFor(this: Store, modelName: string): MinimumAdapterInterface;\n  adapterFor(this: Store, modelName: string, _allowMissing?: true): MinimumAdapterInterface | undefined;\n}\n\n/*\n  _fetchRequest(options: FetchRequestInit): Promise<Response> {\n    const fetchFunction = fetch();\n\n    return fetchFunction(options.url, options);\n  }\n*/\ninterface PrivateAdapter {\n  _fetchRequest(options: RequestInfo): Promise<Response>;\n  hasOverriddenFetch: boolean;\n  useFetch: boolean;\n}\n\nfunction upgradeAdapter(adapter: unknown): asserts adapter is PrivateAdapter {}\nfunction upgradeStore(store: Store): asserts store is Store & { adapterFor: HasAdapterForFn['adapterFor'] } {\n  if (typeof store.adapterFor !== 'function') {\n    throw new Error('Store is not compatible with Holodeck. Missing adapterFor method.');\n  }\n}\n\n/**\n * Creates an adapterFor function that wraps the provided adapterFor function\n * to override the adapter's _fetchRequest method to route requests through\n * the Holodeck mock server.\n *\n * @param owner - The test context object used to retrieve the test ID.\n */\nexport function installAdapterFor(owner: object, store: Store): void {\n  upgradeStore(store);\n  const fn = store.adapterFor;\n  function holodeckAdapterFor(\n    this: Store,\n    modelName: string,\n    _allowMissing?: true\n  ): MinimumAdapterInterface | undefined {\n    const adapter = fn.call(this, modelName, _allowMissing);\n\n    if (adapter) {\n      upgradeAdapter(adapter);\n\n      if (!adapter.hasOverriddenFetch) {\n        adapter.hasOverriddenFetch = true;\n        adapter.useFetch = true;\n        const originalFetch = adapter._fetchRequest?.bind(adapter);\n\n        adapter._fetchRequest = function (options: RequestInfo) {\n          if (!originalFetch) {\n            throw new Error(`Adapter ${String(modelName)} does not implement _fetchRequest`);\n          }\n          const { request } = setupHolodeckFetch(owner, options);\n\n          return originalFetch(request);\n        };\n      }\n    }\n\n    return adapter;\n  }\n  store.adapterFor = holodeckAdapterFor as HasAdapterForFn['adapterFor'];\n}\n\n/**\n * Mock a request by sending the scaffold to the mock server.\n *\n * @public\n */\nexport async function mock(owner: object, generate: ScaffoldGenerator, isRecording?: boolean): Promise<void> {\n  if (getIsRecording() || isRecording) {\n    const test = TEST_IDS.get(owner);\n    if (!test) {\n      throw new Error(`Cannot call \"mock\" before configuring a testId. Use setTestId to set the testId for each test`);\n    }\n    const requestToMock = generate();\n    const { url: mockUrl, method } = requestToMock;\n    if (!mockUrl || !method) {\n      throw new Error(`MockError: Cannot mock a request without providing a URL and Method`);\n    }\n    const mockMethod = (method?.toUpperCase() ?? 'GET') as HTTPMethod;\n\n    // enable custom methods\n    if (!test.mock[mockMethod]) {\n      // oxlint-disable-next-line no-console\n      console.log(`⚠️ Using custom HTTP method ${mockMethod} for response to request ${mockUrl}`);\n      test.mock[mockMethod] = {};\n    }\n    if (!(mockUrl in test.mock[mockMethod])) {\n      test.mock[mockMethod][mockUrl] = 0;\n    }\n    const testMockNum = test.mock[mockMethod][mockUrl]++;\n    const url = `${HOST}__record?__xTestId=${test.id}&__xTestRequestNumber=${testMockNum}`;\n    await fetch(url, {\n      method: 'POST',\n      body: JSON.stringify(requestToMock),\n      mode: 'cors',\n      credentials: 'omit',\n      referrerPolicy: '',\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["getGlobalConfig","macroCondition","TEST_IDS","WeakMap","HOST","setConfig","host","endsWith","setTestId","context","str","has","Error","set","id","mock","GET","PUT","PATCH","DELETE","POST","QUERY","OPTIONS","HEAD","CONNECT","TRACE","request","test","get","delete","reportUnrequestedMocks","normalizeUrlKey","url","withoutOrigin","replace","startsWith","slice","unrequested","method","Object","keys","mocked","requested","requestCounts","Map","key","mockCount","requestCount","push","length","join","shouldRecord","WarpDrive","env","SHOULD_RECORD","IS_RECORDING","setIsRecording","value","Boolean","getIsRecording","MockServerHandler","constructor","owner","next","queryForTest","setupHolodeckFetch","assign","future","setStream","getStream","e","DOMException","explanation","getHolodeckExplanation","message","split","HOLODECK_ERROR_CODES","Set","content","errors","Array","isArray","filter","error","code","map","detail","firstChar","includes","toUpperCase","console","log","mode","credentials","referrerPolicy","headers","Headers","upgradeAdapter","adapter","upgradeStore","store","adapterFor","installAdapterFor","fn","holodeckAdapterFor","modelName","_allowMissing","call","hasOverriddenFetch","useFetch","originalFetch","_fetchRequest","bind","options","String","generate","isRecording","mockUrl","buildScaffold","scaffold","mockMethod","testMockNum","requestToMock","response","fetch","body","JSON","stringify","ok","status","statusText","getRecordFailureDetail","json"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @module\n * @mergeModuleWith <project>\n */\nimport { SHOULD_RECORD } from '@warp-drive/core/build-config/env';\nimport type { Handler, NextFn } from '@warp-drive/core/request';\nimport type { HTTPMethod, RequestContext, RequestInfo, StructuredDataDocument } from '@warp-drive/core/types/request';\nimport type { MinimumAdapterInterface } from '@warp-drive/legacy/compat';\nimport type { Store } from '@warp-drive/legacy/store';\n\nimport type { LazyScaffold, Scaffold, ScaffoldGenerator } from './mock';\n\nconst TEST_IDS = new WeakMap<\n  object,\n  {\n    id: string;\n    /**\n     * keeps track of the count of calls to record a mock\n     */\n    mock: {\n      /**\n       * For each GET, we keep track of the count\n       * for a specific URL\n       */\n      GET: Record<string, number>;\n      /**\n       * For each PUT, we keep track of the count\n       * for a specific URL\n       */\n      PUT: Record<string, number>;\n      /**\n       * For each PATCH, we keep track of the count\n       * for a specific URL\n       */\n      PATCH: Record<string, number>;\n      /**\n       * For each DELETE, we keep track of the count\n       * for a specific URL\n       */\n      DELETE: Record<string, number>;\n      /**\n       * For each POST, we keep track of the count\n       * for a specific URL\n       */\n      POST: Record<string, number>;\n      /**\n       * For each OPTIONS, we keep track of the count\n       * for a specific URL\n       */\n      OPTIONS: Record<string, number>;\n      /**\n       * For each QUERY, we keep track of the count\n       * for a specific URL\n       */\n      QUERY: Record<string, number>;\n      /**\n       * for each HEAD, we keep track of the count\n       * for a specific URL\n       */\n      HEAD: Record<string, number>;\n      /**\n       * for each CONNECT, we keep track of the count\n       * for a specific URL\n       */\n      CONNECT: Record<string, number>;\n      /**\n       * for each TRACE, we keep track of the count\n       * for a specific URL\n       */\n      TRACE: Record<string, number>;\n    };\n    /**\n     * keeps track of the count of calls to make a request\n     */\n    request: {\n      /**\n       * For each GET, we keep track of the count\n       * for a specific URL\n       */\n      GET: Record<string, number>;\n      /**\n       * For each PUT, we keep track of the count\n       * for a specific URL\n       */\n      PUT: Record<string, number>;\n      /**\n       * For each PATCH, we keep track of the count\n       * for a specific URL\n       */\n      PATCH: Record<string, number>;\n      /**\n       * For each DELETE, we keep track of the count\n       * for a specific URL\n       */\n      DELETE: Record<string, number>;\n      /**\n       * For each POST, we keep track of the count\n       * for a specific URL\n       */\n      POST: Record<string, number>;\n      /**\n       * For each OPTIONS, we keep track of the count\n       * for a specific URL\n       */\n      OPTIONS: Record<string, number>;\n      /**\n       * For each QUERY, we keep track of the count\n       * for a specific URL\n       */\n      QUERY: Record<string, number>;\n      /**\n       * for each HEAD, we keep track of the count\n       * for a specific URL\n       */\n      HEAD: Record<string, number>;\n      /**\n       * for each CONNECT, we keep track of the count\n       * for a specific URL\n       */\n      CONNECT: Record<string, number>;\n      /**\n       * for each TRACE, we keep track of the count\n       * for a specific URL\n       */\n      TRACE: Record<string, number>;\n    };\n  }\n>();\n\n/**\n * The shape `setTestId` stores per test context, named so the report below can\n * take one as an argument.\n */\ntype TestEntry = NonNullable<ReturnType<(typeof TEST_IDS)['get']>>;\n\nlet HOST = '/';\n\n/**\n * @public\n */\n\nexport function setConfig({ host }: { host: string }): void {\n  HOST = host.endsWith('/') ? host : `${host}/`;\n}\n\n/**\n * @public\n */\n\nexport function setTestId(context: object, str: string | null): void {\n  if (str && TEST_IDS.has(context)) {\n    throw new Error(`MockServerHandler is already configured with a testId.`);\n  }\n  if (str) {\n    TEST_IDS.set(context, {\n      id: str,\n      mock: {\n        GET: {},\n        PUT: {},\n        PATCH: {},\n        DELETE: {},\n        POST: {},\n        QUERY: {},\n        OPTIONS: {},\n        HEAD: {},\n        CONNECT: {},\n        TRACE: {},\n      },\n      request: {\n        GET: {},\n        PUT: {},\n        PATCH: {},\n        DELETE: {},\n        POST: {},\n        QUERY: {},\n        OPTIONS: {},\n        HEAD: {},\n        CONNECT: {},\n        TRACE: {},\n      },\n    });\n  } else {\n    const test = TEST_IDS.get(context);\n    TEST_IDS.delete(context);\n\n    if (test) {\n      reportUnrequestedMocks(test);\n    }\n  }\n}\n\n/**\n * A mock is declared relative to the mock server (`users/1`) while the request\n * carries the absolute url the code under test built\n * (`https://localhost:7358/users/1`). The mock server reconciles the two by\n * keying a fixture on the request's path, so compare them the same way.\n */\nfunction normalizeUrlKey(url: string): string {\n  const withoutOrigin = url.replace(/^[a-z][a-z0-9+.-]*:\\/\\/[^/]+/i, '');\n  return withoutOrigin.startsWith('/') ? withoutOrigin.slice(1) : withoutOrigin;\n}\n\n/**\n * A mock the test never requested proves nothing: the test passes whether or\n * not the code under test would have made that request. Nothing compared the\n * two counters holodeck already keeps, so report the difference here, from the\n * `afterEach` every suite runs, which fails the test that leaked.\n *\n * The original assertions are not masked by this: a framework reports an\n * `afterEach` throw alongside the results the test body already recorded\n * rather than in place of them.\n */\nfunction reportUnrequestedMocks(test: TestEntry): void {\n  const unrequested: string[] = [];\n\n  for (const method of Object.keys(test.mock) as HTTPMethod[]) {\n    const mocked = test.mock[method];\n    const requested = test.request[method] ?? {};\n    const requestCounts = new Map<string, number>();\n\n    for (const url of Object.keys(requested)) {\n      const key = normalizeUrlKey(url);\n      requestCounts.set(key, (requestCounts.get(key) ?? 0) + requested[url]);\n    }\n\n    for (const url of Object.keys(mocked)) {\n      const mockCount = mocked[url];\n      const requestCount = requestCounts.get(normalizeUrlKey(url)) ?? 0;\n\n      if (mockCount > requestCount) {\n        unrequested.push(`\\t${method} ${url} (mocked ${mockCount}, requested ${requestCount})`);\n      }\n    }\n  }\n\n  if (unrequested.length) {\n    throw new Error(\n      `Holodeck: this test declared mocks it never requested.\\n\\n${unrequested.join('\\n')}\\n\\n` +\n        `A mock that is never requested proves nothing. Remove it, or make the request it describes.`\n    );\n  }\n}\n\nconst shouldRecord = SHOULD_RECORD ? true : false;\nlet IS_RECORDING: boolean | null = null;\n\n/**\n * @public\n */\nexport function setIsRecording(value: boolean): void {\n  IS_RECORDING = value === null ? value : Boolean(value);\n}\n\n/**\n * @public\n */\nexport function getIsRecording(): boolean {\n  return IS_RECORDING === null ? shouldRecord : IS_RECORDING;\n}\n\n/**\n * A request handler that intercepts requests and routes them through\n * the Holodeck mock server.\n *\n * This handler modifies the request URL to include test identifiers\n * and manages request counts for accurate mocking.\n *\n * Requires that the test context be configured with a testId using `setTestId`.\n *\n * @param owner - the test context object used to retrieve the test ID.\n */\nexport class MockServerHandler implements Handler {\n  declare owner: object;\n  constructor(owner: object) {\n    this.owner = owner;\n  }\n  async request<T>(context: RequestContext, next: NextFn<T>): Promise<StructuredDataDocument<T>> {\n    const { request, queryForTest } = setupHolodeckFetch(this.owner, Object.assign({}, context.request));\n\n    try {\n      const future = next(request);\n      context.setStream(future.getStream());\n      return await future;\n    } catch (e) {\n      if (e instanceof Error && !(e instanceof DOMException)) {\n        const explanation = getHolodeckExplanation(e);\n        if (explanation) {\n          e.message = `${e.message}\\n\\n${explanation}`;\n        }\n        e.message = e.message.split(queryForTest).join('');\n      }\n      throw e;\n    }\n  }\n}\n\nconst HOLODECK_ERROR_CODES = new Set([\n  'MOCK_NOT_FOUND',\n  'MISSING_X_TEST_ID_HEADER',\n  'MISSING_X_TEST_REQUEST_NUMBER_HEADER',\n]);\n\n/**\n * The mock server explains itself in the response body, which the thrown\n * error only carries as data. Lift that explanation into the message so it\n * reaches a terminal and a CI log.\n */\nfunction getHolodeckExplanation(e: Error): string | null {\n  const { content } = e as Error & { content?: unknown };\n  if (!content || typeof content !== 'object') {\n    return null;\n  }\n  const { errors } = content as { errors?: unknown };\n  if (!Array.isArray(errors)) {\n    return null;\n  }\n\n  return (\n    errors\n      .filter((error): error is { code: string; detail?: string } => {\n        return (\n          !!error && typeof error === 'object' && HOLODECK_ERROR_CODES.has((error as { code?: unknown }).code as string)\n        );\n      })\n      .map((error) => error.detail)\n      .filter((detail): detail is string => typeof detail === 'string')\n      .join('\\n\\n') || null\n  );\n}\n\nfunction setupHolodeckFetch(owner: object, request: RequestInfo): { request: RequestInfo; queryForTest: string } {\n  const test = TEST_IDS.get(owner);\n  if (!test) {\n    throw new Error(`MockServerHandler is not configured with a testId. Use setTestId to set the testId for each test`);\n  }\n\n  const url = request.url!;\n  const firstChar = url.includes('?') ? '&' : '?';\n  const method = (request.method?.toUpperCase() ?? 'GET') as HTTPMethod;\n\n  // enable custom methods\n  if (!test.request[method]) {\n    // oxlint-disable-next-line no-console\n    console.log(`⚠️ Using custom HTTP method ${method} for response to request ${url}`);\n\n    test.request[method] = {};\n  }\n  if (!(url in test.request[method])) {\n    test.request[method][url] = 0;\n  }\n\n  const queryForTest = `${firstChar}__xTestId=${test.id}&__xTestRequestNumber=${test.request[method][url]++}`;\n  request.url = url + queryForTest;\n  request.method = method;\n\n  request.mode = 'cors';\n  request.credentials = 'omit';\n  request.referrerPolicy = '';\n\n  // since holodeck currently runs on a separate port\n  // and we don't want to trigger cors pre-flight\n  // we convert PUT to POST to keep the request in the\n  // \"simple\" cors category.\n  // if (request.method === 'PUT') {\n  //   request.method = 'POST';\n  // }\n\n  const headers = new Headers(request.headers);\n  if (headers.has('Content-Type')) {\n    // under the rules of simple-cors, content-type can only be\n    // one of three things, none of which are what folks typically\n    // set this to. Since holodeck always expects body to be JSON\n    // this \"just works\".\n    headers.set('Content-Type', 'text/plain');\n    request.headers = headers;\n  }\n\n  return { request, queryForTest };\n}\n\ninterface HasAdapterForFn {\n  adapterFor(this: Store, modelName: string): MinimumAdapterInterface;\n  adapterFor(this: Store, modelName: string, _allowMissing?: true): MinimumAdapterInterface | undefined;\n}\n\n/*\n  _fetchRequest(options: FetchRequestInit): Promise<Response> {\n    const fetchFunction = fetch();\n\n    return fetchFunction(options.url, options);\n  }\n*/\ninterface PrivateAdapter {\n  _fetchRequest(options: RequestInfo): Promise<Response>;\n  hasOverriddenFetch: boolean;\n  useFetch: boolean;\n}\n\nfunction upgradeAdapter(adapter: unknown): asserts adapter is PrivateAdapter {}\nfunction upgradeStore(store: Store): asserts store is Store & { adapterFor: HasAdapterForFn['adapterFor'] } {\n  if (typeof store.adapterFor !== 'function') {\n    throw new Error('Store is not compatible with Holodeck. Missing adapterFor method.');\n  }\n}\n\n/**\n * Creates an adapterFor function that wraps the provided adapterFor function\n * to override the adapter's _fetchRequest method to route requests through\n * the Holodeck mock server.\n *\n * @param owner - The test context object used to retrieve the test ID.\n */\nexport function installAdapterFor(owner: object, store: Store): void {\n  upgradeStore(store);\n  const fn = store.adapterFor;\n  function holodeckAdapterFor(\n    this: Store,\n    modelName: string,\n    _allowMissing?: true\n  ): MinimumAdapterInterface | undefined {\n    const adapter = fn.call(this, modelName, _allowMissing);\n\n    if (adapter) {\n      upgradeAdapter(adapter);\n\n      if (!adapter.hasOverriddenFetch) {\n        adapter.hasOverriddenFetch = true;\n        adapter.useFetch = true;\n        const originalFetch = adapter._fetchRequest?.bind(adapter);\n\n        adapter._fetchRequest = function (options: RequestInfo) {\n          if (!originalFetch) {\n            throw new Error(`Adapter ${String(modelName)} does not implement _fetchRequest`);\n          }\n          const { request } = setupHolodeckFetch(owner, options);\n\n          return originalFetch(request);\n        };\n      }\n    }\n\n    return adapter;\n  }\n  store.adapterFor = holodeckAdapterFor as HasAdapterForFn['adapterFor'];\n}\n\n/**\n * Mock a request by sending the scaffold to the mock server.\n *\n * @public\n */\nexport async function mock(\n  owner: object,\n  generate: ScaffoldGenerator | LazyScaffold,\n  isRecording?: boolean\n): Promise<void> {\n  const test = TEST_IDS.get(owner);\n  if (!test) {\n    throw new Error(`Cannot call \"mock\" before configuring a testId. Use setTestId to set the testId for each test`);\n  }\n\n  // A LazyScaffold carries its identity, so its body is built only when\n  // recording. A bare generator is the only source of its own identity, so it\n  // has to run either way; the helpers in ./mock never pass one.\n  let method: string;\n  let mockUrl: string;\n  let buildScaffold: () => Scaffold;\n  if (typeof generate === 'function') {\n    const scaffold = generate();\n    ({ method, url: mockUrl } = scaffold);\n    buildScaffold = () => scaffold;\n  } else {\n    ({ method, url: mockUrl } = generate);\n    buildScaffold = generate.scaffold;\n  }\n  if (!mockUrl || !method) {\n    throw new Error(`MockError: Cannot mock a request without providing a URL and Method`);\n  }\n  const mockMethod = (method.toUpperCase() ?? 'GET') as HTTPMethod;\n\n  // enable custom methods\n  if (!test.mock[mockMethod]) {\n    // oxlint-disable-next-line no-console\n    console.log(`⚠️ Using custom HTTP method ${mockMethod} for response to request ${mockUrl}`);\n    test.mock[mockMethod] = {};\n  }\n  if (!(mockUrl in test.mock[mockMethod])) {\n    test.mock[mockMethod][mockUrl] = 0;\n  }\n  // counted whether or not we are recording, so that a mock the test never\n  // requests is reported in replay runs too, not only while recording.\n  const testMockNum = test.mock[mockMethod][mockUrl]++;\n\n  // `isRecording` is the per-request RECORD override, which records even when\n  // the suite as a whole is replaying.\n  if (!getIsRecording() && !isRecording) {\n    return;\n  }\n\n  const requestToMock = buildScaffold();\n  const url = `${HOST}__record?__xTestId=${test.id}&__xTestRequestNumber=${testMockNum}`;\n  const response = await fetch(url, {\n    method: 'POST',\n    body: JSON.stringify(requestToMock),\n    mode: 'cors',\n    credentials: 'omit',\n    referrerPolicy: '',\n  });\n\n  if (!response.ok) {\n    throw new Error(\n      `MockError: Holodeck failed to record ${mockMethod} ${mockUrl} (${response.status} ${response.statusText}). ${await getRecordFailureDetail(response)}`\n    );\n  }\n}\n\n/**\n * A failed recording is otherwise invisible until the next replay run fails\n * with a missing fixture, so report what the server said at the point of\n * failure.\n */\nasync function getRecordFailureDetail(response: Response): Promise<string> {\n  try {\n    const body = (await response.json()) as { errors?: { detail?: string }[] };\n    const detail = body.errors?.[0]?.detail;\n    return detail ?? 'The mock server gave no explanation.';\n  } catch {\n    return 'The mock server gave no explanation.';\n  }\n}\n"],"mappings":"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"}

package/dist/mock.d.ts

@@ -15,6 +15,19 @@ export interface Scaffold {
  * @public
  */
 export type ScaffoldGenerator = () => Scaffold;
+/**
+ * A mock whose method and url are known up front, with the rest of the
+ * scaffold built only when holodeck is recording. This is what the mock
+ * helpers pass, so that in replay mode a test's response generators never
+ * run.
+ *
+ * @public
+ */
+export interface LazyScaffold {
+  method: string;
+  url: string;
+  scaffold: () => Scaffold;
+}
 /**
  * @public
  */
@@ -29,11 +42,13 @@ export type ResponseGenerator = () => Record<string, unknown>;
  * - status: the status code to return (default: 200)
  * - headers: the headers to return (default: {})
  * - body: the body to match against for the request (default: null)
- * - RECORD: whether to record the request (default: false)
+ * - RECORD: record this request even when the suite is replaying, such as under CI (default: false).
+ *   A local override for re-recording one request. Do not commit it; a committed RECORD means
+ *   that request is never replayed against its fixture.
  *
  * @param url the url to mock, relative to the mock server host (e.g. `users/1`)
  * @param response a function which generates the response to return
- * @param options status, headers for the response, body to match against for the request, and whether to record the request
+ * @param options status, headers for the response, body to match against for the request, and whether to force recording
  * @return
  */
 export declare function GET(owner: object, url: string, response: ResponseGenerator, options?: Partial<Omit<Scaffold, "response" | "url" | "method">> & {
@@ -74,11 +89,13 @@ export declare function DELETE(owner: object, url: string, response: ResponseGen
  * - status: the status code to return (default: 200)
  * - headers: the headers to return (default: {})
  * - body: the body to match against for the request (default: null)
- * - RECORD: whether to record the request (default: false)
+ * - RECORD: record this request even when the suite is replaying, such as under CI (default: false).
+ *   A local override for re-recording one request. Do not commit it; a committed RECORD means
+ *   that request is never replayed against its fixture.
  *
  * @param url the url to mock, relative to the mock server host (e.g. `users/1`)
  * @param response a function which generates the response to return
- * @param options status, headers for the response, body to match against for the request, and whether to record the request
+ * @param options status, headers for the response, body to match against for the request, and whether to force recording
  * @return
  */
 export declare function HEAD(owner: object, url: string, response: ResponseGenerator, options?: Partial<Omit<Scaffold, "response" | "url" | "method">> & {

package/dist/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","names":[],"sources":["../src/mock.ts"],"mappings":";;;;iBAKiB;EACf;EACA;EACA,SAAS;EACT,MAAM;EACN;EACA;EACA,UAAU;;;;;YAMA,0BAA0B;;;;YAK1B,0BAA0B;;;;;;;;;;;;;;;;;;wBAmBtB,IACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;wBAmFa,KACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;wBAwBa,IACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;;wBAwBa,MACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;wBAuBa,OACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;;;;;;;;;;;;;;;wBAsCa,KACd,eACA,aACA,UAAU,mBAIV,UAAU,QAAQ,KAAK;EAA8C;IACpE"}
+{"version":3,"file":"mock.d.ts","names":[],"sources":["../src/mock.ts"],"mappings":";;;;iBAKiB;EACf;EACA;EACA,SAAS;EACT,MAAM;EACN;EACA;EACA,UAAU;;;;;YAMA,0BAA0B;;;;;;;;;iBAUrB;EACf;EACA;EACA,gBAAgB;;;;;YAMN,0BAA0B;;;;;;;;;;;;;;;;;;;;wBAqBtB,IACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;wBAuFa,KACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;wBA4Ba,IACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;;wBA4Ba,MACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;wBA2Ba,OACd,eACA,aACA,UAAU,mBACV,UAAU,QAAQ,KAAK;EAA8C;IACpE;;;;;;;;;;;;;;;;;;;;wBA4Ca,KACd,eACA,aACA,UAAU,mBAIV,UAAU,QAAQ,KAAK;EAA8C;IACpE"}

package/dist/mock.js

@@ -1,4 +1,4 @@
-import { getIsRecording, mock } from "./index.js";
+import { mock } from "./index.js";
 
 //#region src/mock.ts
 /**
@@ -11,23 +11,29 @@ import { getIsRecording, mock } from "./index.js";
 * - status: the status code to return (default: 200)
 * - headers: the headers to return (default: {})
 * - body: the body to match against for the request (default: null)
-* - RECORD: whether to record the request (default: false)
+* - RECORD: record this request even when the suite is replaying, such as under CI (default: false).
+*   A local override for re-recording one request. Do not commit it; a committed RECORD means
+*   that request is never replayed against its fixture.
 *
 * @param url the url to mock, relative to the mock server host (e.g. `users/1`)
 * @param response a function which generates the response to return
-* @param options status, headers for the response, body to match against for the request, and whether to record the request
+* @param options status, headers for the response, body to match against for the request, and whether to force recording
 * @return
 */
 function GET(owner, url, response, options) {
-	return mock(owner, () => ({
-		status: options?.status ?? 200,
-		statusText: options?.statusText ?? "OK",
-		headers: options?.headers ?? {},
-		body: options?.body ?? null,
+	return mock(owner, {
 		method: "GET",
 		url,
-		response: response()
-	}), getIsRecording() || (options?.RECORD ?? false));
+		scaffold: () => ({
+			status: options?.status ?? 200,
+			statusText: options?.statusText ?? "OK",
+			headers: options?.headers ?? {},
+			body: options?.body ?? null,
+			method: "GET",
+			url,
+			response: response()
+		})
+	}, options?.RECORD);
 }
 const STATUS_TEXT_FOR = /* @__PURE__ */ new Map([
 	[200, "OK"],
@@ -96,74 +102,90 @@ const STATUS_TEXT_FOR = /* @__PURE__ */ new Map([
 * Mock a POST request
 */
 function POST(owner, url, response, options) {
-	return mock(owner, () => {
-		const body = response();
-		const status = options?.status ?? (body ? 201 : 204);
-		return {
-			status,
-			statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
-			headers: options?.headers ?? {},
-			body: options?.body ?? null,
-			method: "POST",
-			url,
-			response: body
-		};
-	}, getIsRecording() || (options?.RECORD ?? false));
+	return mock(owner, {
+		method: "POST",
+		url,
+		scaffold: () => {
+			const body = response();
+			const status = options?.status ?? (body ? 201 : 204);
+			return {
+				status,
+				statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
+				headers: options?.headers ?? {},
+				body: options?.body ?? null,
+				method: "POST",
+				url,
+				response: body
+			};
+		}
+	}, options?.RECORD);
 }
 /**
 * mock a PUT request
 */
 function PUT(owner, url, response, options) {
-	return mock(owner, () => {
-		const body = response();
-		const status = options?.status ?? (body ? 200 : 204);
-		return {
-			status,
-			statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
-			headers: options?.headers ?? {},
-			body: options?.body ?? null,
-			method: "PUT",
-			url,
-			response: body
-		};
-	}, getIsRecording() || (options?.RECORD ?? false));
+	return mock(owner, {
+		method: "PUT",
+		url,
+		scaffold: () => {
+			const body = response();
+			const status = options?.status ?? (body ? 200 : 204);
+			return {
+				status,
+				statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
+				headers: options?.headers ?? {},
+				body: options?.body ?? null,
+				method: "PUT",
+				url,
+				response: body
+			};
+		}
+	}, options?.RECORD);
 }
 /**
 * mock a PATCH request
 *
 */
 function PATCH(owner, url, response, options) {
-	return mock(owner, () => {
-		const body = response();
-		const status = options?.status ?? (body ? 200 : 204);
-		return {
-			status,
-			statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
-			headers: options?.headers ?? {},
-			body: options?.body ?? null,
-			method: "PATCH",
-			url,
-			response: body
-		};
-	}, getIsRecording() || (options?.RECORD ?? false));
+	return mock(owner, {
+		method: "PATCH",
+		url,
+		scaffold: () => {
+			const body = response();
+			const status = options?.status ?? (body ? 200 : 204);
+			return {
+				status,
+				statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
+				headers: options?.headers ?? {},
+				body: options?.body ?? null,
+				method: "PATCH",
+				url,
+				response: body
+			};
+		}
+	}, options?.RECORD);
 }
 /**
 * mock a DELETE request
 */
 function DELETE(owner, url, response, options) {
-	return mock(owner, () => {
-		const body = response();
-		const status = options?.status ?? (body ? 200 : 204);
-		return {
-			status,
-			statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
-			headers: options?.headers ?? {},
-			body: options?.body ?? null,
-			method: "DELETE",
-			url,
-			response: body
-		};
-	}, getIsRecording() || (options?.RECORD ?? false));
+	return mock(owner, {
+		method: "DELETE",
+		url,
+		scaffold: () => {
+			const body = response();
+			const status = options?.status ?? (body ? 200 : 204);
+			return {
+				status,
+				statusText: options?.statusText ?? STATUS_TEXT_FOR.get(status) ?? "",
+				headers: options?.headers ?? {},
+				body: options?.body ?? null,
+				method: "DELETE",
+				url,
+				response: body
+			};
+		}
+	}, options?.RECORD);
 }
 /**
 * Sets up Mocking for a HEAD request on the mock server
@@ -175,23 +197,29 @@ function DELETE(owner, url, response, options) {
 * - status: the status code to return (default: 200)
 * - headers: the headers to return (default: {})
 * - body: the body to match against for the request (default: null)
-* - RECORD: whether to record the request (default: false)
+* - RECORD: record this request even when the suite is replaying, such as under CI (default: false).
+*   A local override for re-recording one request. Do not commit it; a committed RECORD means
+*   that request is never replayed against its fixture.
 *
 * @param url the url to mock, relative to the mock server host (e.g. `users/1`)
 * @param response a function which generates the response to return
-* @param options status, headers for the response, body to match against for the request, and whether to record the request
+* @param options status, headers for the response, body to match against for the request, and whether to force recording
 * @return
 */
 function HEAD(owner, url, response, options) {
-	return mock(owner, () => ({
-		status: options?.status ?? 200,
-		statusText: options?.statusText ?? "OK",
-		headers: options?.headers ?? {},
-		body: options?.body ?? null,
+	return mock(owner, {
 		method: "HEAD",
 		url,
-		response: response()
-	}), getIsRecording() || (options?.RECORD ?? false));
+		scaffold: () => ({
+			status: options?.status ?? 200,
+			statusText: options?.statusText ?? "OK",
+			headers: options?.headers ?? {},
+			body: options?.body ?? null,
+			method: "HEAD",
+			url,
+			response: response()
+		})
+	}, options?.RECORD);
 }
 
 //#endregion