@databricks/appkit 0.75.1 → 0.76.1

package/dist/testing/create-test-app.js

@@ -0,0 +1,187 @@
+import { ServiceContext } from "../context/service-context.js";
+import { InMemoryStorage } from "../cache/storage/memory.js";
+import { AppKit, disposeApp } from "../core/appkit.js";
+import { createMockWorkspaceClient } from "./mock-workspace-client.js";
+import { fakeUserContext, oboHeaders, setupDatabricksEnv } from "./fixtures.js";
+import { dropCoreSingletons } from "./reset-singletons.js";
+import { vi } from "vitest";
+
+//#region src/testing/create-test-app.ts
+/**
+* The env snapshot to restore on close, and whether an app currently holds it.
+*
+* One live app at a time (see the guard in `createTestApp`), so a flag suffices.
+*/
+let envBaseline;
+let harnessAppLive = false;
+/** Take the baseline on boot. */
+function acquireEnvBaseline() {
+	envBaseline = { ...process.env };
+	harnessAppLive = true;
+}
+/** Restore the baseline on close. */
+function releaseEnvBaseline() {
+	harnessAppLive = false;
+	if (!envBaseline) return;
+	const baseline = envBaseline;
+	envBaseline = void 0;
+	for (const key of Object.keys(process.env)) if (!(key in baseline)) delete process.env[key];
+	Object.assign(process.env, baseline);
+}
+/**
+* Point `ServiceContext.createUserContext` at the harness's mock so an `obo`
+* request does not construct a real SDK client from `DATABRICKS_HOST`.
+*
+* Mirrors the `createUserContextSpy` in `fixtures.ts`; returns its restore.
+*/
+function stubUserContext(client) {
+	const spy = vi.spyOn(ServiceContext, "createUserContext").mockImplementation((token, userId, userName, userEmail) => fakeUserContext(client, ServiceContext.get())(token, userId, userName, userEmail));
+	return () => spy.mockRestore();
+}
+/**
+* Wait for a server to finish binding and return the port it landed on.
+*
+* Needed with `port: 0`: `start()` returns once `listen()` is invoked, before
+* the bind completes, so `address()` is null until the `listening` event fires.
+* `createTestApp` does this for you — reach for it when hand-rolling a server.
+*/
+async function getListeningPort(server) {
+	const addr = server.address();
+	if (addr && typeof addr === "object" && typeof addr.port === "number") return addr.port;
+	await new Promise((resolve, reject) => {
+		server.once("listening", () => resolve());
+		server.once("error", (err) => reject(err));
+	});
+	const ready = server.address();
+	if (!ready || typeof ready !== "object") throw new Error("Server is listening but address() returned null");
+	return ready.port;
+}
+/**
+* Boot a real app — real Express wiring, routes, and resource validation — with
+* no workspace, credentials, or network. `createTestPluginContext` is cheaper
+* when you only need to unit-test wiring.
+*
+* Does **not** validate config values against `manifest.config.schema`; no
+* runtime validator exists for that.
+*
+* @example
+* ```ts
+* const app = await createTestApp({ plugins: [myPlugin()] });
+* try {
+*   const res = await app.post("/api/my-plugin/thing", { body: { q: 1 }, obo: true });
+*   await expectStream(res).toEmit("status", "result");
+* } finally {
+*   await app.close();
+* }
+* ```
+*/
+async function createTestApp(options = {}) {
+	const { plugins = [], responses, strict, client: suppliedClient, env = {}, server: serverOption, nodeEnv = "test", cache } = options;
+	if (nodeEnv === "development") throw new Error("createTestApp: nodeEnv \"development\" is not supported. Dev mode routes the harness's ephemeral `port: 0` through get-port, which throws a RangeError, and it also boots a real Vite dev server, downgrades resource validation to a warning, and stops filtering dev-only plugins. Pin a port explicitly with your own server plugin if you need dev behaviour.");
+	if (harnessAppLive) throw new Error("createTestApp: a harness app is already open. AppKit's workspace client, cache, and on-behalf-of fake are process-wide, so a second app would not receive its own `client`/`responses`, and closing either would un-fake the other's on-behalf-of path. Close the first app before booting another — `await using`, or try/finally.");
+	acquireEnvBaseline();
+	let app;
+	let restoreUserContext;
+	const disposeBooted = (a) => a[disposeApp]();
+	try {
+		process.env.NODE_ENV = nodeEnv;
+		process.env.APPKIT_STRICT_VALIDATION = "true";
+		setupDatabricksEnv({
+			DATABRICKS_WORKSPACE_ID: "test-workspace-id",
+			...env
+		});
+		dropCoreSingletons();
+		if (suppliedClient && (responses !== void 0 || strict !== void 0)) throw new Error("createTestApp: `responses` and `strict` configure the built-in mock client, so they do nothing when you also pass `client`. Drop them and configure your own client instead.");
+		const client = suppliedClient ?? createMockWorkspaceClient({
+			responses,
+			strict
+		});
+		restoreUserContext = stubUserContext(client);
+		const hasServer = plugins.some((p) => p?.name === "server");
+		if (serverOption === false && hasServer) throw new Error("createTestApp: `server: false` conflicts with the server plugin in `plugins`. Drop one — omit `server: false` to use your plugin, or remove the plugin to boot without a socket.");
+		const bootPlugins = [...plugins];
+		if (serverOption !== false && !hasServer) {
+			const { server: serverPlugin } = await import("../plugins/server/index.js");
+			bootPlugins.push(serverPlugin({
+				port: 0,
+				host: "127.0.0.1"
+			}));
+		}
+		app = await AppKit._createApp({
+			plugins: bootPlugins,
+			client,
+			cache: cache ?? { storage: new InMemoryStorage({ enabled: true }) },
+			disableInternalTelemetry: true,
+			installSignalHandlers: false
+		});
+		const serverExports = app.server;
+		const httpServer = serverOption === false ? void 0 : serverExports?.getServer?.();
+		const port = httpServer ? await getListeningPort(httpServer) : void 0;
+		const baseUrl = port === void 0 ? void 0 : `http://127.0.0.1:${port}`;
+		const bootedApp = app;
+		let closed;
+		/** Memoized, so repeated calls are safe in nested `finally`s. */
+		const close = () => {
+			closed ??= (async () => {
+				try {
+					await disposeBooted(bootedApp);
+				} finally {
+					dropCoreSingletons();
+					restoreUserContext?.();
+					releaseEnvBaseline();
+				}
+			})();
+			return closed;
+		};
+		const request = async (method, path, reqOptions = {}) => {
+			if (baseUrl === void 0) throw new Error(`createTestApp: no HTTP server was started (server: false), so ${method} ${path} cannot be issued.`);
+			const headers = {};
+			if (reqOptions.obo) Object.assign(headers, oboHeaders(reqOptions.obo));
+			let body;
+			if (reqOptions.body !== void 0) if (typeof reqOptions.body === "string") body = reqOptions.body;
+			else {
+				body = JSON.stringify(reqOptions.body);
+				headers["content-type"] = "application/json";
+			}
+			for (const [name, value] of Object.entries(reqOptions.headers ?? {})) headers[name.toLowerCase()] = value;
+			return fetch(new URL(path, baseUrl), {
+				method,
+				headers,
+				body,
+				signal: reqOptions.signal
+			});
+		};
+		return {
+			plugins: bootedApp,
+			client,
+			get baseUrl() {
+				if (baseUrl === void 0) throw new Error("createTestApp: no HTTP server was started (server: false).");
+				return baseUrl;
+			},
+			get port() {
+				if (port === void 0) throw new Error("createTestApp: no HTTP server was started (server: false).");
+				return port;
+			},
+			server: httpServer,
+			close,
+			[Symbol.asyncDispose]: close,
+			get: (path, o) => request("GET", path, o),
+			post: (path, o) => request("POST", path, o),
+			put: (path, o) => request("PUT", path, o),
+			patch: (path, o) => request("PATCH", path, o),
+			delete: (path, o) => request("DELETE", path, o)
+		};
+	} catch (err) {
+		if (app) try {
+			await disposeBooted(app);
+		} catch {}
+		dropCoreSingletons();
+		restoreUserContext?.();
+		releaseEnvBaseline();
+		throw err;
+	}
+}
+
+//#endregion
+export { createTestApp, getListeningPort };
+//# sourceMappingURL=create-test-app.js.map

package/dist/testing/create-test-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-test-app.js","names":[],"sources":["../../src/testing/create-test-app.ts"],"sourcesContent":["/**\n * Boot a real AppKit app with no workspace, credentials, or network, then call it\n * over real HTTP.\n */\n\nimport type { Server } from \"node:http\";\n\nimport type {\n  CacheConfig,\n  PluginConstructor,\n  PluginData,\n  PluginMap,\n} from \"shared\";\nimport { vi } from \"vitest\";\n\nimport { InMemoryStorage } from \"../cache/storage/memory\";\nimport { ServiceContext } from \"../context/service-context\";\nimport { AppKit, disposeApp } from \"../core/appkit\";\nimport type { WorkspaceClient } from \"../workspace-client\";\nimport type { OboOption } from \"./fixtures\";\nimport { fakeUserContext, oboHeaders, setupDatabricksEnv } from \"./fixtures\";\nimport type { CreateMockWorkspaceClientOptions } from \"./mock-workspace-client\";\nimport { createMockWorkspaceClient } from \"./mock-workspace-client\";\nimport { dropCoreSingletons } from \"./reset-singletons\";\n\n// Loose shapes are intentional here; `noExplicitAny` is off repo-wide (see\n// .oxlintrc.json), so a local alias keeps the intent readable.\ntype Any = any;\n\n/**\n * The env snapshot to restore on close, and whether an app currently holds it.\n *\n * One live app at a time (see the guard in `createTestApp`), so a flag suffices.\n */\nlet envBaseline: NodeJS.ProcessEnv | undefined;\nlet harnessAppLive = false;\n\n/** Take the baseline on boot. */\nfunction acquireEnvBaseline(): void {\n  envBaseline = { ...process.env };\n  harnessAppLive = true;\n}\n\n/** Restore the baseline on close. */\nfunction releaseEnvBaseline(): void {\n  harnessAppLive = false;\n  if (!envBaseline) return;\n\n  const baseline = envBaseline;\n  envBaseline = undefined;\n  for (const key of Object.keys(process.env)) {\n    if (!(key in baseline)) delete process.env[key];\n  }\n  Object.assign(process.env, baseline);\n}\n\n/** Plugin descriptors, exactly as `createApp` takes them. */\ntype Plugins = PluginData<PluginConstructor, unknown, string>[];\n\n/** Options for {@link createTestApp}. */\nexport interface CreateTestAppOptions<T extends Plugins> {\n  /** The plugins under test, as `createApp` takes them. */\n  plugins?: T;\n\n  /** Dotted-path responses for the built-in mock. Refused when `client` is set. */\n  responses?: CreateMockWorkspaceClientOptions[\"responses\"];\n\n  /**\n   * Make the built-in mock throw when a path with no declared response is\n   * called, rather than resolving `undefined`. Refused when `client` is set —\n   * configure it on your own client instead.\n   */\n  strict?: CreateMockWorkspaceClientOptions[\"strict\"];\n\n  /**\n   * Replaces the built-in mock. You then own `currentUser.me()` — boot reads\n   * `currentUser.id` and fails without it.\n   */\n  client?: WorkspaceClient;\n\n  /** Extra env for the boot, restored on `close()`; satisfies declared resources. */\n  env?: Record<string, string>;\n\n  /** No socket; setup, validation, and teardown still run, request methods throw. */\n  server?: false;\n\n  /**\n   * Defaults to `\"test\"`. `\"development\"` is refused — it throws a `RangeError`\n   * in `get-port` on `port: 0`, boots Vite, and relaxes validation.\n   *\n   * Beyond refusing `development`, this decides error-response redaction:\n   * `errorHandlerMiddleware` returns the real message unless `NODE_ENV` is\n   * `production`, where a 5xx becomes `\"Server error\"`. Pass `\"production\"` to\n   * assert what a deployed app actually returns to a client.\n   */\n  nodeEnv?: string;\n\n  /** Defaults to in-memory, which is what keeps boot offline. */\n  cache?: CacheConfig;\n}\n\n/** Per-request options for the {@link TestApp} HTTP methods. */\nexport interface TestRequestOptions {\n  /** A non-string value is JSON-encoded with `content-type: application/json`. */\n  body?: unknown;\n  /** Merged last, so they win over anything the harness sets. */\n  headers?: Record<string, string>;\n  /** Same convention as `createMockRequest({ obo })`. */\n  obo?: OboOption;\n  /** Forwarded to `fetch`. */\n  signal?: AbortSignal;\n}\n\n/** A booted test app. */\nexport interface TestApp<T extends Plugins> {\n  /**\n   * Plugin exports by manifest name. Nested rather than spread because `get` and\n   * `delete` are plausible plugin names and would collide with the request methods.\n   */\n  plugins: PluginMap<T>;\n  /** The same object a handler resolves at runtime. */\n  client: WorkspaceClient;\n  /** e.g. `http://127.0.0.1:54321`. Throws when `server: false`. */\n  baseUrl: string;\n  /** The bound ephemeral port. Throws when `server: false`. */\n  port: number;\n  /** The underlying HTTP server, or `undefined` with `server: false`. */\n  server?: Server;\n\n  /** Release the app and restore env. Idempotent. */\n  close(): Promise<void>;\n  [Symbol.asyncDispose](): Promise<void>;\n\n  get(path: string, options?: TestRequestOptions): Promise<Response>;\n  post(path: string, options?: TestRequestOptions): Promise<Response>;\n  put(path: string, options?: TestRequestOptions): Promise<Response>;\n  patch(path: string, options?: TestRequestOptions): Promise<Response>;\n  delete(path: string, options?: TestRequestOptions): Promise<Response>;\n}\n\n/**\n * Point `ServiceContext.createUserContext` at the harness's mock so an `obo`\n * request does not construct a real SDK client from `DATABRICKS_HOST`.\n *\n * Mirrors the `createUserContextSpy` in `fixtures.ts`; returns its restore.\n */\nfunction stubUserContext(client: WorkspaceClient): () => void {\n  const spy = vi\n    .spyOn(ServiceContext, \"createUserContext\")\n    .mockImplementation((token, userId, userName, userEmail) =>\n      fakeUserContext(client, ServiceContext.get())(\n        token,\n        userId,\n        userName,\n        userEmail,\n      ),\n    );\n  return () => spy.mockRestore();\n}\n\n/**\n * Wait for a server to finish binding and return the port it landed on.\n *\n * Needed with `port: 0`: `start()` returns once `listen()` is invoked, before\n * the bind completes, so `address()` is null until the `listening` event fires.\n * `createTestApp` does this for you — reach for it when hand-rolling a server.\n */\nexport async function getListeningPort(server: Server): Promise<number> {\n  const addr = server.address();\n  if (addr && typeof addr === \"object\" && typeof addr.port === \"number\") {\n    return addr.port;\n  }\n  await new Promise<void>((resolve, reject) => {\n    server.once(\"listening\", () => resolve());\n    server.once(\"error\", (err) => reject(err));\n  });\n  const ready = server.address();\n  if (!ready || typeof ready !== \"object\") {\n    throw new Error(\"Server is listening but address() returned null\");\n  }\n  return ready.port;\n}\n\n/**\n * Boot a real app — real Express wiring, routes, and resource validation — with\n * no workspace, credentials, or network. `createTestPluginContext` is cheaper\n * when you only need to unit-test wiring.\n *\n * Does **not** validate config values against `manifest.config.schema`; no\n * runtime validator exists for that.\n *\n * @example\n * ```ts\n * const app = await createTestApp({ plugins: [myPlugin()] });\n * try {\n *   const res = await app.post(\"/api/my-plugin/thing\", { body: { q: 1 }, obo: true });\n *   await expectStream(res).toEmit(\"status\", \"result\");\n * } finally {\n *   await app.close();\n * }\n * ```\n */\nexport async function createTestApp<T extends Plugins>(\n  options: CreateTestAppOptions<T> = {},\n): Promise<TestApp<T>> {\n  const {\n    plugins = [] as unknown as T,\n    responses,\n    strict,\n    client: suppliedClient,\n    env = {},\n    server: serverOption,\n    nodeEnv = \"test\",\n    cache,\n  } = options;\n\n  if (nodeEnv === \"development\") {\n    throw new Error(\n      'createTestApp: nodeEnv \"development\" is not supported. Dev mode routes ' +\n        \"the harness's ephemeral `port: 0` through get-port, which throws a \" +\n        \"RangeError, and it also boots a real Vite dev server, downgrades \" +\n        \"resource validation to a warning, and stops filtering dev-only \" +\n        \"plugins. Pin a port explicitly with your own server plugin if you \" +\n        \"need dev behaviour.\",\n    );\n  }\n\n  // Refused rather than half-supported: AppKit's workspace client, cache and\n  // on-behalf-of fake are process-wide, so a second live app cannot own its\n  // own. Checked before any mutation, so a refused boot leaves the live app\n  // untouched.\n  if (harnessAppLive) {\n    throw new Error(\n      \"createTestApp: a harness app is already open. AppKit's workspace \" +\n        \"client, cache, and on-behalf-of fake are process-wide, so a second \" +\n        \"app would not receive its own `client`/`responses`, and closing \" +\n        \"either would un-fake the other's on-behalf-of path. Close the first \" +\n        \"app before booting another — `await using`, or try/finally.\",\n    );\n  }\n\n  // Wholesale rather than a whitelist: plugins read vars we cannot enumerate.\n  acquireEnvBaseline();\n\n  let app: Awaited<ReturnType<typeof AppKit._createApp>> | undefined;\n  let restoreUserContext: (() => void) | undefined;\n\n  // Runs the booted plugins' shutdown() hooks and closes the server it started;\n  // the harness owns dropping the singletons and restoring env. The `as Any` is\n  // the one escape hatch the symbol-keyed teardown forces on the harness.\n  const disposeBooted = (a: unknown): Promise<void> => (a as Any)[disposeApp]();\n\n  try {\n    process.env.NODE_ENV = nodeEnv;\n\n    // Redundant while NODE_ENV is pinned, but keeps the throw-on-missing-resource\n    // contract if that pin ever changes. No opt-out: the warning path is\n    // dev-only, and dev is refused.\n    process.env.APPKIT_STRICT_VALIDATION = \"true\";\n\n    // The workspace ID short-circuits getWorkspaceId's SCIM probe, which would\n    // otherwise show up as an apiClient.request call.\n    setupDatabricksEnv({\n      DATABRICKS_WORKSPACE_ID: \"test-workspace-id\",\n      ...env,\n    });\n\n    dropCoreSingletons();\n\n    // `responses` only seeds the built-in mock, so alongside a caller-supplied\n    // client it would silently do nothing. Refuse instead, matching the\n    // `server: false` conflict below.\n    if (suppliedClient && (responses !== undefined || strict !== undefined)) {\n      throw new Error(\n        \"createTestApp: `responses` and `strict` configure the built-in mock \" +\n          \"client, so they do nothing when you also pass `client`. Drop them \" +\n          \"and configure your own client instead.\",\n      );\n    }\n\n    // Boot runs ServiceContext.createContext for real, which reads\n    // currentUser.id — the mock's built-in default is what lets it through.\n    const client =\n      suppliedClient ?? createMockWorkspaceClient({ responses, strict });\n\n    // createApp({ client }) installs only the service-principal client. An `obo`\n    // request reaches ServiceContext.createUserContext, which builds a *real*\n    // client from process.env.DATABRICKS_HOST — so the user-scoped path is faked\n    // here too, or \"no network\" is false the moment a handler calls asUser.\n    restoreUserContext = stubUserContext(client);\n\n    // createApp never auto-adds a server, so without this there is nothing to\n    // fetch. Lazily imported: the plugin runs dotenv.config() at module load, so\n    // a static import would mutate a consumer's env on import of this kit.\n    const hasServer = plugins.some((p) => p?.name === \"server\");\n    if (serverOption === false && hasServer) {\n      // The plugin would still bind a socket while the handle denied one existed.\n      throw new Error(\n        \"createTestApp: `server: false` conflicts with the server plugin in \" +\n          \"`plugins`. Drop one — omit `server: false` to use your plugin, or \" +\n          \"remove the plugin to boot without a socket.\",\n      );\n    }\n    const bootPlugins = [...plugins] as Plugins;\n    if (serverOption !== false && !hasServer) {\n      const { server: serverPlugin } = await import(\"../plugins/server\");\n      bootPlugins.push(serverPlugin({ port: 0, host: \"127.0.0.1\" }));\n    }\n\n    // Both extras are required to stay offline: without explicit storage the\n    // cache builds its own client and probes Lakebase, and without the opt-out\n    // TelemetryReporter fires an apiClient.request on boot.\n    app = await AppKit._createApp({\n      plugins: bootPlugins as Any,\n      client,\n      cache: cache ?? {\n        storage: new InMemoryStorage({ enabled: true } as Any),\n      },\n      disableInternalTelemetry: true,\n      // The harness boots repeatedly in one process and runs its own teardown,\n      // so it must not accumulate SIGTERM/SIGINT handlers across boots.\n      installSignalHandlers: false,\n    });\n\n    const serverExports = (app as Any).server;\n    const httpServer: Server | undefined =\n      serverOption === false ? undefined : serverExports?.getServer?.();\n    const port = httpServer ? await getListeningPort(httpServer) : undefined;\n    const baseUrl = port === undefined ? undefined : `http://127.0.0.1:${port}`;\n\n    const bootedApp = app;\n    let closed: Promise<void> | undefined;\n\n    /** Memoized, so repeated calls are safe in nested `finally`s. */\n    const close = () => {\n      closed ??= (async () => {\n        try {\n          await disposeBooted(bootedApp);\n        } finally {\n          dropCoreSingletons();\n          restoreUserContext?.();\n          releaseEnvBaseline();\n        }\n      })();\n      return closed;\n    };\n\n    const request = async (\n      method: string,\n      path: string,\n      reqOptions: TestRequestOptions = {},\n    ): Promise<Response> => {\n      if (baseUrl === undefined) {\n        throw new Error(\n          \"createTestApp: no HTTP server was started (server: false), so \" +\n            `${method} ${path} cannot be issued.`,\n        );\n      }\n\n      const headers: Record<string, string> = {};\n      if (reqOptions.obo) {\n        Object.assign(headers, oboHeaders(reqOptions.obo));\n      }\n\n      let body: string | undefined;\n      if (reqOptions.body !== undefined) {\n        if (typeof reqOptions.body === \"string\") {\n          body = reqOptions.body;\n        } else {\n          body = JSON.stringify(reqOptions.body);\n          headers[\"content-type\"] = \"application/json\";\n        }\n      }\n\n      // Caller headers last, so an explicit content-type or identity wins.\n      // Lowercased first: `Headers` comma-joins case variants instead of\n      // replacing, so a mixed-case override would corrupt the value into\n      // \"alice, bob\" rather than win.\n      for (const [name, value] of Object.entries(reqOptions.headers ?? {})) {\n        headers[name.toLowerCase()] = value;\n      }\n\n      return fetch(new URL(path, baseUrl), {\n        method,\n        headers,\n        body,\n        signal: reqOptions.signal,\n      });\n    };\n\n    return {\n      plugins: bootedApp as unknown as PluginMap<T>,\n      client,\n      get baseUrl() {\n        if (baseUrl === undefined) {\n          throw new Error(\n            \"createTestApp: no HTTP server was started (server: false).\",\n          );\n        }\n        return baseUrl;\n      },\n      get port() {\n        if (port === undefined) {\n          throw new Error(\n            \"createTestApp: no HTTP server was started (server: false).\",\n          );\n        }\n        return port;\n      },\n      server: httpServer,\n      close,\n      [Symbol.asyncDispose]: close,\n      get: (path, o) => request(\"GET\", path, o),\n      post: (path, o) => request(\"POST\", path, o),\n      put: (path, o) => request(\"PUT\", path, o),\n      patch: (path, o) => request(\"PATCH\", path, o),\n      delete: (path, o) => request(\"DELETE\", path, o),\n    };\n  } catch (err) {\n    // Teardown must run from the failure path too, or the boot leaks env\n    // mutations and singletons into every later test in the file.\n    if (app) {\n      try {\n        await disposeBooted(app);\n      } catch {\n        // The boot error is the interesting one; don't let teardown mask it.\n      }\n    }\n    // dispose() no longer drops the singletons, and a failure before boot may\n    // have left a partial init — drop unconditionally either way.\n    dropCoreSingletons();\n    restoreUserContext?.();\n    releaseEnvBaseline();\n    throw err;\n  }\n}\n"],"mappings":"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"}

package/dist/testing/create-test-plugin.d.ts

@@ -0,0 +1,17 @@
+import { PluginConstructor, PluginData } from "../shared/src/plugin.js";
+import "../shared/src/index.js";
+
+//#region src/testing/create-test-plugin.d.ts
+/**
+ * Instantiate a plugin from its `toPlugin()` factory for use with
+ * `createTestPluginContext`.
+ *
+ * Merge order mirrors `AppKit.createAndRegisterPlugin` — `DEFAULT_CONFIG`, then
+ * the factory's config, then the manifest `name` — so the instance matches what
+ * production builds. Reaching through the descriptor by hand
+ * (`new (genie({}).plugin)({})`) skips both.
+ */
+declare function createTestPlugin<TClass extends PluginConstructor, TConfig, TName extends string>(factory: (config?: TConfig) => PluginData<TClass, TConfig, TName>, config?: TConfig): InstanceType<TClass>;
+//#endregion
+export { createTestPlugin };
+//# sourceMappingURL=create-test-plugin.d.ts.map

package/dist/testing/create-test-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-test-plugin.d.ts","names":[],"sources":["../../src/testing/create-test-plugin.ts"],"mappings":";;;;;;;AAWA;;;;;;iBAAgB,gBAAA,gBACC,iBAAA,gCAAA,CAIf,OAAA,GAAU,MAAA,GAAS,OAAA,KAAY,UAAA,CAAW,MAAA,EAAQ,OAAA,EAAS,KAAA,GAC3D,MAAA,GAAS,OAAA,GACR,YAAA,CAAa,MAAA"}

package/dist/testing/create-test-plugin.js

@@ -0,0 +1,22 @@
+//#region src/testing/create-test-plugin.ts
+/**
+* Instantiate a plugin from its `toPlugin()` factory for use with
+* `createTestPluginContext`.
+*
+* Merge order mirrors `AppKit.createAndRegisterPlugin` — `DEFAULT_CONFIG`, then
+* the factory's config, then the manifest `name` — so the instance matches what
+* production builds. Reaching through the descriptor by hand
+* (`new (genie({}).plugin)({})`) skips both.
+*/
+function createTestPlugin(factory, config) {
+	const { plugin: PluginClass, config: factoryConfig, name } = factory(config);
+	return new PluginClass({
+		...PluginClass.DEFAULT_CONFIG ?? {},
+		...factoryConfig ?? {},
+		name
+	});
+}
+
+//#endregion
+export { createTestPlugin };
+//# sourceMappingURL=create-test-plugin.js.map

package/dist/testing/create-test-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-test-plugin.js","names":[],"sources":["../../src/testing/create-test-plugin.ts"],"sourcesContent":["import type { PluginConstructor, PluginData } from \"shared\";\n\n/**\n * Instantiate a plugin from its `toPlugin()` factory for use with\n * `createTestPluginContext`.\n *\n * Merge order mirrors `AppKit.createAndRegisterPlugin` — `DEFAULT_CONFIG`, then\n * the factory's config, then the manifest `name` — so the instance matches what\n * production builds. Reaching through the descriptor by hand\n * (`new (genie({}).plugin)({})`) skips both.\n */\nexport function createTestPlugin<\n  TClass extends PluginConstructor,\n  TConfig,\n  TName extends string,\n>(\n  factory: (config?: TConfig) => PluginData<TClass, TConfig, TName>,\n  config?: TConfig,\n): InstanceType<TClass> {\n  const { plugin: PluginClass, config: factoryConfig, name } = factory(config);\n\n  return new PluginClass({\n    ...(PluginClass.DEFAULT_CONFIG ?? {}),\n    ...(factoryConfig ?? {}),\n    name,\n  }) as InstanceType<TClass>;\n}\n"],"mappings":";;;;;;;;;;AAWA,SAAgB,iBAKd,SACA,QACsB;CACtB,MAAM,EAAE,QAAQ,aAAa,QAAQ,eAAe,SAAS,QAAQ,OAAO;AAE5E,QAAO,IAAI,YAAY;EACrB,GAAI,YAAY,kBAAkB,EAAE;EACpC,GAAI,iBAAiB,EAAE;EACvB;EACD,CAAC"}

package/dist/testing/fixtures.d.ts

@@ -1,5 +1,7 @@
 import { IAppRouter } from "../shared/src/plugin.js";
+import { ApiError } from "../shared/src/workspace-client/errors.js";
 import "../shared/src/index.js";
+import "../workspace-client/index.js";
 import { ServiceContext, ServiceContextState } from "../context/service-context.js";
 import { ITelemetry } from "../telemetry/types.js";
 import * as vitest from "vitest";
@@ -93,6 +95,32 @@ declare function createMockResponse(): {
  * reads `DATABRICKS_HOST` / `DATABRICKS_WAREHOUSE_ID` finds test values.
  */
 declare function setupDatabricksEnv(overrides?: Record<string, string>): void;
+/**
+ * Sets environment variables for the duration of `fn`, then restores them to
+ * their prior state. Each key's prior value (or "was absent") is captured on
+ * entry; on exit, the prior value is restored, or the key is deleted only if
+ * it was previously unset.
+ *
+ * Supports both sync and async `fn`. If `fn` returns a thenable, `withEnv`
+ * returns that promise and restores in `.finally()`. Otherwise, it restores
+ * in a synchronous `finally` and returns the callback's return value.
+ * Restoration runs even if `fn` throws. Nested calls restore in LIFO order.
+ *
+ * @example
+ * ```ts
+ * // Sync: restores synchronously after fn
+ * withEnv({ MY_VAR: "test" }, () => {
+ *   console.log(process.env.MY_VAR); // "test"
+ * });
+ * console.log(process.env.MY_VAR); // prior value (or undefined)
+ *
+ * // Async: restores after promise settles
+ * await withEnv({ MY_VAR: "test" }, async () => {
+ *   await fetch(...);
+ * });
+ * ```
+ */
+declare function withEnv<T>(vars: Record<string, string>, fn: () => T | Promise<T>): T | Promise<T>;
 /**
  * Clears AppKit's process-wide cache singleton so cached values don't leak
  * between tests in the same file.
@@ -130,19 +158,6 @@ interface TestContextOptions {
   /** Workspace ID */
   workspaceId?: string;
 }
-/**
- * Creates a default mock WorkspaceClient for testing (SQL succeeds, warehouse
- * RUNNING).
- */
-declare function createMockWorkspaceClient(): {
-  statementExecution: {
-    executeStatement: vitest.Mock<(...args: any[]) => any>;
-  };
-  warehouses: {
-    get: vitest.Mock<(...args: any[]) => any>;
-    start: vitest.Mock<(...args: any[]) => any>;
-  };
-};
 /**
  * Mocks the `ServiceContext` singleton for testing — spies `get`,
  * `initialize`, `isInitialized`, and `createUserContext` so code that resolves
@@ -230,28 +245,29 @@ declare function createFailedSQLResponse(errorMessage: string): {
   statement_id: string;
 };
 /**
- * A WorkspaceClient whose `executeStatement`/`getStatement` are bare `vi.fn()`s
- * (no default resolution) so a test can script exactly what SQL returns.
- * `warehouses.get` defaults to RUNNING.
+ * Creates a genuine `ApiError` instance for testing error paths. Returns a real
+ * instance (where `error instanceof ApiError` holds), suitable for testing
+ * `instanceof` checks and `.statusCode` / `.errorCode` / `.message` accessors.
+ *
+ * @param options Error details: `statusCode`, `message`, and `errorCode`. All required.
+ * @returns A genuine `ApiError` instance.
+ *
+ * @example
+ * ```ts
+ * const error = createApiError({
+ *   statusCode: 404,
+ *   message: "File not found",
+ *   errorCode: "NOT_FOUND",
+ * });
+ * expect(error).toBeInstanceOf(ApiError);
+ * expect(error.statusCode).toBe(404);
+ * ```
  */
-declare function createConfigurableMockWorkspaceClient(): {
-  client: {
-    statementExecution: {
-      executeStatement: vitest.Mock<(...args: any[]) => any>;
-      getStatement: vitest.Mock<(...args: any[]) => any>;
-    };
-    warehouses: {
-      get: vitest.Mock<(...args: any[]) => any>;
-      start: vitest.Mock<(...args: any[]) => any>;
-    };
-  };
-  mocks: {
-    executeStatement: vitest.Mock<(...args: any[]) => any>;
-    getStatement: vitest.Mock<(...args: any[]) => any>;
-    warehousesGet: vitest.Mock<(...args: any[]) => any>;
-    warehousesStart: vitest.Mock<(...args: any[]) => any>;
-  };
-};
+declare function createApiError(options: {
+  statusCode: number;
+  message: string;
+  errorCode: string;
+}): ApiError;
 //#endregion
-export { OboOption, ServiceContextMock, TestContextOptions, createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock };
+export { OboOption, ServiceContextMock, TestContextOptions, createApiError, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock, withEnv };
 //# sourceMappingURL=fixtures.d.ts.map

package/dist/testing/fixtures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixtures.d.ts","names":[],"sources":["../../src/testing/fixtures.ts"],"mappings":";;;;;;;KAWK,GAAA;;;AAJkE;;;;iBAYvD,mBAAA,CAAA,GAAuB,UAAA;AAAvC;;;;AAAA,iBAqDgB,gBAAA,CAAA;EACd,MAAA,EAAQ,UAAA;EACR,QAAA,EAAU,MAAA,SAAe,GAAA;EACzB,UAAA,GAAa,MAAA,UAAgB,IAAA,aAAiB,GAAA;AAAA;;;;;;;;KAqCpC,SAAA;EAtCA,sDA0CN,MAAA,WAzCJ;EA2CI,KAAA,WA3CyB;EA6CzB,KAAA;AAAA;;AARN;;;;;;;;;AAqCA;;;;;iBAAgB,iBAAA,CAAkB,SAAA,GAAW,GAAA;;;;;;;;;;;;;;;;;iBA+C7B,kBAAA,CAAA;;UAAkB,MAAA,CAAA,IAAA;;QAWC,MAAA,CAAA,IAAA,QAAH,GAAA;;OAKE,MAAA,CAAA,IAAA,QAAH,GAAA,EAAG,KAAA;SAcE,MAAA,CAAA,IAAA,QAAH,GAAA,EAAG,KAAA;aAOI,MAAA,CAAA,IAAA,QAAH,GAAA;;;MAST,MAAA,CAAA,IAAA,QAFhB,GAAA,EAAG,KAAA,UACI,OAAA,MACA,IAAA,EAAM,GAAA;OAWG,MAAA,CAAA,IAAA,QAFhB,GAAA,EAAG,KAAA,UACI,OAAA,MACA,IAAA,EAAM,GAAA;;;;;;;;iBAgBN,QAAA;AAAA;;;;;iBAWH,kBAAA,CAAmB,SAAA,GAAW,MAAA;;;;;;;;;;;;;;;;;;;;iBAyBxB,cAAA,CAAA,GAAkB,OAAA;;;;UAcvB,kBAAA;;EAEf,uBAAA,GAA0B,GAAA;;EAE1B,oBAAA,GAAuB,GAAA;EAtEN;EAwEjB,MAAA;EAzEiB;EA2EjB,aAAA;;EAEA,WAAA;EA5DyB;EA8DzB,WAAA;AAAA;;;;;iBAOc,yBAAA,CAAA;;sBAAyB,MAAA,CAAA,IAAA;;;;;;;;;;;;;;;iBA2CzB,kBAAA,CAAmB,OAAA,GAAS,kBAAA;;;;;;;;;KA6ChC,kBAAA,GAAqB,UAAA,QAAkB,kBAAA;;;;;;;;;;;;;;AA7CnD;;;;;;;;;;;;;iBAyEgB,qBAAA,CAAsB,OAAA,GAAS,kBAAA;EAAA,SACpC,OAAA,EAAS,kBAAA;AAAA;;;;;iBA+BE,qBAAA,GAAA,CACpB,EAAA,QAAU,CAAA,GAAI,OAAA,CAAQ,CAAA,GACtB,OAAA,GAAU,kBAAA,GACT,OAAA,CAAQ,CAAA;;;;;iBAcK,2BAAA,CACd,IAAA,EAAM,GAAA,MACN,OAAA,EAAS,KAAA;EAAQ,IAAA;EAAc,SAAA;AAAA;;;;;;;;;;;;;;;;;;iBAoBjB,uBAAA,CAAwB,YAAA;;;;;;;;;;;;;;iBAiBxB,qCAAA,CAAA;;;wBAAqC,MAAA,CAAA,IAAA"}
+{"version":3,"file":"fixtures.d.ts","names":[],"sources":["../../src/testing/fixtures.ts"],"mappings":";;;;;;;;;KAgBK,GAAA;;;;AAL0C;;;iBAa/B,mBAAA,CAAA,GAAuB,UAAA;;AAAvC;;;iBAqDgB,gBAAA,CAAA;EACd,MAAA,EAAQ,UAAA;EACR,QAAA,EAAU,MAAA,SAAe,GAAA;EACzB,UAAA,GAAa,MAAA,UAAgB,IAAA,aAAiB,GAAA;AAAA;;;;;;;;KAqCpC,SAAA;EAtCV,sDA0CI,MAAA,WA1CqB;EA4CrB,KAAA,WA3CS;EA6CT,KAAA;AAAA;;;;;;;;;;;;;;;;iBAiFU,iBAAA,CAAkB,SAAA,GAAW,GAAA;;;;;;;;;;;;;;;;;iBA+C7B,kBAAA,CAAA;;UAAkB,MAAA,CAAA,IAAA;;QAWC,MAAA,CAAA,IAAA,QAAH,GAAA;;OAKE,MAAA,CAAA,IAAA,QAAH,GAAA,EAAG,KAAA;SAcE,MAAA,CAAA,IAAA,QAAH,GAAA,EAAG,KAAA;aAOI,MAAA,CAAA,IAAA,QAAH,GAAA;;;MAST,MAAA,CAAA,IAAA,QAFhB,GAAA,EAAG,KAAA,UACI,OAAA,MACA,IAAA,EAAM,GAAA;OAWG,MAAA,CAAA,IAAA,QAFhB,GAAA,EAAG,KAAA,UACI,OAAA,MACA,IAAA,EAAM,GAAA;;;;;;;;iBAgBN,QAAA;AAAA;;;;;iBAWH,kBAAA,CAAmB,SAAA,GAAW,MAAA;;;;;;AAA9C;;;;;AAmEA;;;;;;;;;;;;;;;iBAAgB,OAAA,GAAA,CACd,IAAA,EAAM,MAAA,kBACN,EAAA,QAAU,CAAA,GAAI,OAAA,CAAQ,CAAA,IACrB,CAAA,GAAI,OAAA,CAAQ,CAAA;;;;;;;;;AAmDf;;;;;AAcA;;;;;;iBAdsB,cAAA,CAAA,GAAkB,OAAA;;;;UAcvB,kBAAA;EAYf;EAVA,uBAAA,GAA0B,GAAA;EAUf;EARX,oBAAA,GAAuB,GAAA;EAoCS;EAlChC,MAAA;EAkC0C;EAhC1C,aAAA;;EAEA,WAAA;;EAEA,WAAA;AAAA;;;;;;;;;iBA4Bc,kBAAA,CAAmB,OAAA,GAAS,kBAAA;;;;;;;;;KAwChC,kBAAA,GAAqB,UAAA,QAAkB,kBAAA;;;;;;;;;;;AAAnD;;;;;AA4BA;;;;;;;;;;AAgCA;iBAhCgB,qBAAA,CAAsB,OAAA,GAAS,kBAAA;EAAA,SACpC,OAAA,EAAS,kBAAA;AAAA;;;;;iBA+BE,qBAAA,GAAA,CACpB,EAAA,QAAU,CAAA,GAAI,OAAA,CAAQ,CAAA,GACtB,OAAA,GAAU,kBAAA,GACT,OAAA,CAAQ,CAAA;;;;;iBAcK,2BAAA,CACd,IAAA,EAAM,GAAA,MACN,OAAA,EAAS,KAAA;EAAQ,IAAA;EAAc,SAAA;AAAA;;;;;;;;;;;;;;;;;;iBAoBjB,uBAAA,CAAwB,YAAA;;;;;;;;;;AAAxC;;;;;;;;;;;;AA+BA;;;;;;iBAAgB,cAAA,CAAe,OAAA;EAC7B,UAAA;EACA,OAAA;EACA,SAAA;AAAA,IACE,QAAA"}

package/dist/testing/fixtures.js

@@ -1,5 +1,10 @@
+import { ApiError } from "../shared/src/workspace-client/errors.js";
+import { AuthenticationError } from "../errors/authentication.js";
+import "../errors/index.js";
 import { ServiceContext } from "../context/service-context.js";
 import { CacheManager } from "../cache/index.js";
+import { createMockWorkspaceClient } from "./mock-workspace-client.js";
+import { createHash } from "node:crypto";
 import { afterEach, beforeEach, vi } from "vitest";
 
 //#region src/testing/fixtures.ts
@@ -68,7 +73,41 @@ function createMockRouter() {
 		getHandler: (method, path) => handlers[`${method.toUpperCase()}:${path}`]
 	};
 }
-/** Build the forwarded identity headers an `obo` option implies. */
+/**
+* The one fake of `ServiceContext.createUserContext` this kit uses, shared by
+* `mockServiceContext` and `createTestApp`.
+*
+* Shared rather than duplicated because the two used to disagree, and neither
+* matched production: a missing token went unrejected and `tokenFingerprint`
+* was absent, which silently disables Lakebase pool rotation — `pool-manager`
+* treats a missing fingerprint as "not stale", so the drain-and-recreate branch
+* could never run under a fake.
+*
+* @internal
+*/
+function fakeUserContext(client, ids) {
+	return (token, userId, userName, userEmail) => {
+		if (!token) throw AuthenticationError.missingToken("user token");
+		return {
+			client,
+			userId,
+			userName,
+			userEmail,
+			tokenFingerprint: createHash("sha256").update(token).digest("hex").slice(0, 16),
+			warehouseId: ids.warehouseId,
+			workspaceId: ids.workspaceId,
+			isUserContext: true
+		};
+	};
+}
+/**
+* Build the forwarded identity headers an `obo` option implies.
+*
+* Exported so `createTestApp`'s request methods use the same convention as
+* `createMockRequest` rather than a second one.
+*
+* @internal
+*/
 function oboHeaders(obo) {
 	const opts = obo === true ? {} : obo;
 	const headers = {
@@ -180,6 +219,74 @@ function setupDatabricksEnv(overrides = {}) {
 	Object.assign(process.env, overrides);
 }
 /**
+* Set environment variables and return a function that restores each key to its
+* prior state — the prior value, or a delete when the key was previously unset.
+* Shared capture/restore behind {@link withEnv} and the
+* {@link createTestPluginContext} options path; not part of the public surface.
+*/
+function applyEnv(vars) {
+	const prior = /* @__PURE__ */ new Map();
+	for (const key of Object.keys(vars)) prior.set(key, process.env[key]);
+	Object.assign(process.env, vars);
+	return () => {
+		for (const [key, value] of prior) if (value === void 0) delete process.env[key];
+		else process.env[key] = value;
+	};
+}
+/**
+* Run a restore on an error path, suppressing any failure it throws so it
+* cannot replace the caller's original error.
+*/
+function restoreQuietly(restore) {
+	try {
+		restore();
+	} catch (restoreError) {}
+}
+/**
+* Sets environment variables for the duration of `fn`, then restores them to
+* their prior state. Each key's prior value (or "was absent") is captured on
+* entry; on exit, the prior value is restored, or the key is deleted only if
+* it was previously unset.
+*
+* Supports both sync and async `fn`. If `fn` returns a thenable, `withEnv`
+* returns that promise and restores in `.finally()`. Otherwise, it restores
+* in a synchronous `finally` and returns the callback's return value.
+* Restoration runs even if `fn` throws. Nested calls restore in LIFO order.
+*
+* @example
+* ```ts
+* // Sync: restores synchronously after fn
+* withEnv({ MY_VAR: "test" }, () => {
+*   console.log(process.env.MY_VAR); // "test"
+* });
+* console.log(process.env.MY_VAR); // prior value (or undefined)
+*
+* // Async: restores after promise settles
+* await withEnv({ MY_VAR: "test" }, async () => {
+*   await fetch(...);
+* });
+* ```
+*/
+function withEnv(vars, fn) {
+	const restore = applyEnv(vars);
+	let result;
+	try {
+		result = fn();
+	} catch (err) {
+		restoreQuietly(restore);
+		throw err;
+	}
+	if (result != null && typeof result.then === "function") return result.then((value) => {
+		restore();
+		return value;
+	}, (err) => {
+		restoreQuietly(restore);
+		throw err;
+	});
+	restore();
+	return result;
+}
+/**
 * Clears AppKit's process-wide cache singleton so cached values don't leak
 * between tests in the same file.
 *
@@ -208,22 +315,6 @@ async function resetTestCache() {
 	await cache.clear();
 }
 /**
-* Creates a default mock WorkspaceClient for testing (SQL succeeds, warehouse
-* RUNNING).
-*/
-function createMockWorkspaceClient() {
-	return {
-		statementExecution: { executeStatement: vi.fn().mockResolvedValue({
-			status: { state: "SUCCEEDED" },
-			result: { data: [] }
-		}) },
-		warehouses: {
-			get: vi.fn().mockResolvedValue({ state: "RUNNING" }),
-			start: vi.fn().mockResolvedValue(void 0)
-		}
-	};
-}
-/**
 * Builds a {@link ServiceContextState} value for testing without touching the
 * singleton. Internal building block for {@link mockServiceContext}, which
 * installs the state as spies — that installer is the public entry point.
@@ -249,16 +340,7 @@ function mockServiceContext(options = {}) {
 	const getSpy = vi.spyOn(ServiceContext, "get").mockReturnValue(serviceContext);
 	const initSpy = vi.spyOn(ServiceContext, "initialize").mockResolvedValue(serviceContext);
 	const isInitializedSpy = vi.spyOn(ServiceContext, "isInitialized").mockReturnValue(true);
-	const createUserContextSpy = vi.spyOn(ServiceContext, "createUserContext").mockImplementation((_token, userId, userName) => {
-		return {
-			client: options.userDatabricksClient || createMockWorkspaceClient(),
-			userId,
-			userName,
-			warehouseId: serviceContext.warehouseId,
-			workspaceId: serviceContext.workspaceId,
-			isUserContext: true
-		};
-	});
+	const createUserContextSpy = vi.spyOn(ServiceContext, "createUserContext").mockImplementation(fakeUserContext(options.userDatabricksClient || createMockWorkspaceClient(), serviceContext));
 	return {
 		serviceContext,
 		getSpy,
@@ -351,35 +433,28 @@ function createFailedSQLResponse(errorMessage) {
 	};
 }
 /**
-* A WorkspaceClient whose `executeStatement`/`getStatement` are bare `vi.fn()`s
-* (no default resolution) so a test can script exactly what SQL returns.
-* `warehouses.get` defaults to RUNNING.
+* Creates a genuine `ApiError` instance for testing error paths. Returns a real
+* instance (where `error instanceof ApiError` holds), suitable for testing
+* `instanceof` checks and `.statusCode` / `.errorCode` / `.message` accessors.
+*
+* @param options Error details: `statusCode`, `message`, and `errorCode`. All required.
+* @returns A genuine `ApiError` instance.
+*
+* @example
+* ```ts
+* const error = createApiError({
+*   statusCode: 404,
+*   message: "File not found",
+*   errorCode: "NOT_FOUND",
+* });
+* expect(error).toBeInstanceOf(ApiError);
+* expect(error.statusCode).toBe(404);
+* ```
 */
-function createConfigurableMockWorkspaceClient() {
-	const executeStatement = vi.fn();
-	const getStatement = vi.fn();
-	const warehousesGet = vi.fn().mockResolvedValue({ state: "RUNNING" });
-	const warehousesStart = vi.fn().mockResolvedValue(void 0);
-	return {
-		client: {
-			statementExecution: {
-				executeStatement,
-				getStatement
-			},
-			warehouses: {
-				get: warehousesGet,
-				start: warehousesStart
-			}
-		},
-		mocks: {
-			executeStatement,
-			getStatement,
-			warehousesGet,
-			warehousesStart
-		}
-	};
+function createApiError(options) {
+	return new ApiError(options.message, options.errorCode, options.statusCode, void 0, []);
 }
 
 //#endregion
-export { createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock };
+export { applyEnv, createApiError, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createSuccessfulSQLResponse, fakeUserContext, mockServiceContext, oboHeaders, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock, withEnv };
 //# sourceMappingURL=fixtures.js.map