@databricks/appkit 0.61.1 → 0.62.0

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,257 @@
+import { IAppRouter } from "../shared/src/plugin.js";
+import "../shared/src/index.js";
+import { ITelemetry } from "../telemetry/types.js";
+import { ServiceContext, ServiceContextState } from "../context/service-context.js";
+import * as vitest from "vitest";
+
+//#region src/testing/fixtures.d.ts
+type Any = any;
+/**
+ * Creates a mock telemetry provider for testing. Every span/meter/logger is a
+ * `vi.fn()` no-op, so plugins that trace, count, or log run without a live
+ * OpenTelemetry pipeline. Passed into {@link createTestPluginContext} as the one
+ * injectable production seam.
+ */
+declare function createMockTelemetry(): ITelemetry;
+/**
+ * Creates a mock Express router that captures registered handlers so a test
+ * can pull a handler back out by method + path and invoke it directly.
+ */
+declare function createMockRouter(): {
+  router: IAppRouter;
+  handlers: Record<string, Any>;
+  getHandler: (method: string, path: string) => Any;
+};
+/**
+ * On-behalf-of shorthand for {@link createMockRequest}. `true` uses the default
+ * test user; an object picks the identity. Sets the forwarded headers the real
+ * `Plugin.asUser` reads (`x-forwarded-access-token`, `x-forwarded-user`, and —
+ * when given — `x-forwarded-email`), so an OBO test is one flag instead of
+ * hand-rolled headers.
+ */
+type OboOption = boolean | {
+  /** `x-forwarded-user` — defaults to `"test-user"`. */userId?: string; /** `x-forwarded-access-token` — defaults to `"test-user-token"`. */
+  token?: string; /** `x-forwarded-email` — omitted unless provided. */
+  email?: string;
+};
+/**
+ * Creates a mock Express request. Pass `overrides` to set `params`, `query`,
+ * `body`, `headers`, etc.
+ *
+ * For on-behalf-of tests, pass `obo` instead of hand-adding forwarded headers —
+ * `createMockRequest({ obo: true })` sets the identity headers the real
+ * `asUser` requires. Any explicit `headers` you also pass win over the ones
+ * `obo` generates, so you can override a single field.
+ *
+ * @example
+ * ```ts
+ * createMockRequest({ obo: true });                 // default test user + token
+ * createMockRequest({ obo: { userId: "alice" } });  // pick the user
+ * ```
+ */
+declare function createMockRequest(overrides?: Any): any;
+/**
+ * Creates a mock Express response object. `write`/`send`/`setHeader` flip
+ * `headersSent`, `end` flips `writableEnded` and fires any `close` listener —
+ * enough for streaming handlers that branch on those flags.
+ *
+ * Every chunk passed to `write` (and a final chunk to `end`) is captured, so a
+ * streaming route's real SSE output can be replayed: pass the response straight
+ * to {@link expectStream}, or call `sseResponse()` for a real `Response`.
+ *
+ * @example Assert what a streaming route emitted
+ * ```ts
+ * const res = createMockResponse();
+ * await plugin._handleStream(req, res);
+ * await expectStream(res).toEmit("status", "result");
+ * ```
+ */
+declare function createMockResponse(): {
+  headersSent: boolean;
+  status: vitest.Mock<(...args: any[]) => any>;
+  json: vitest.Mock<(...args: any[]) => any>;
+  send: vitest.Mock<(this: Any) => any>;
+  sendStatus: vitest.Mock<(...args: any[]) => any>;
+  end: vitest.Mock<(this: Any, chunk?: unknown) => any>;
+  write: vitest.Mock<(this: Any, chunk?: unknown) => any>;
+  setHeader: vitest.Mock<(this: Any) => any>;
+  flushHeaders: vitest.Mock<(...args: any[]) => any>;
+  destroy: vitest.Mock<(...args: any[]) => any>;
+  on: vitest.Mock<(this: Any, event: string, handler: (...args: Any[]) => void) => any>;
+  off: vitest.Mock<(this: Any, event: string, handler: (...args: Any[]) => void) => any>;
+  writableEnded: boolean;
+  /**
+   * The SSE body captured so far, as a real `Response` — the bridge from a
+   * `res.write`-based handler into {@link expectStream}. `expectStream`
+   * detects this method and calls it for you, so `expectStream(res)` and
+   * `expectStream(res.sseResponse())` are equivalent.
+   */
+  sseResponse(): Response;
+};
+/**
+ * Sets up common environment variables for Databricks testing so code that
+ * reads `DATABRICKS_HOST` / `DATABRICKS_WAREHOUSE_ID` finds test values.
+ */
+declare function setupDatabricksEnv(overrides?: Record<string, string>): void;
+/**
+ * Clears AppKit's process-wide cache singleton so cached values don't leak
+ * between tests in the same file.
+ *
+ * The cache `attach()` seeds is shared by every test in a file (Vitest isolates
+ * files, not tests within a file). Call this in `beforeEach` when one test's
+ * cached value must not be seen by the next, or mid-test to force a cache miss
+ * before asserting a subsequent hit.
+ *
+ * No-ops when the cache has not been initialized yet, so it is safe to call
+ * before any `attach()`.
+ *
+ * @example
+ * ```ts
+ * beforeEach(async () => {
+ *   await resetTestCache();
+ * });
+ * ```
+ */
+declare function resetTestCache(): Promise<void>;
+/**
+ * Context options for running tests with mocked service/user context
+ */
+interface TestContextOptions {
+  /** Mock WorkspaceClient for service principal operations */
+  serviceDatabricksClient?: Any;
+  /** Mock WorkspaceClient for user operations */
+  userDatabricksClient?: Any;
+  /** User ID for user context */
+  userId?: string;
+  /** Service user ID */
+  serviceUserId?: string;
+  /** Warehouse ID */
+  warehouseId?: string;
+  /** 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
+ * the service principal or an on-behalf-of user context gets test doubles.
+ * Call in `beforeEach`; call the returned `restore()` in `afterEach`.
+ *
+ * @returns The mock context plus the spies and a `restore()` helper.
+ */
+declare function mockServiceContext(options?: TestContextOptions): {
+  serviceContext: ServiceContextState;
+  getSpy: vitest.MockInstance<typeof ServiceContext.get>;
+  initSpy: vitest.MockInstance<typeof ServiceContext.initialize>;
+  isInitializedSpy: vitest.MockInstance<typeof ServiceContext.isInitialized>;
+  createUserContextSpy: vitest.MockInstance<typeof ServiceContext.createUserContext>;
+  restore: () => void;
+};
+/** The handle {@link mockServiceContext} returns (spies + `restore`). */
+type ServiceContextMock = ReturnType<typeof mockServiceContext>;
+/**
+ * Registers a fresh {@link mockServiceContext} before each test and restores it
+ * after — the whole `beforeEach`/`afterEach` dance in one line.
+ *
+ * Call it at the top of a `describe` block (or module top-level), NOT inside a
+ * test: Vitest's `beforeEach`/`afterEach` only register during collection, so a
+ * call from within a test body registers nothing for that test.
+ *
+ * Returns a **live** accessor, not the handle: each `beforeEach` builds fresh
+ * spies, so reading `.current` inside a test always sees that test's mock. A
+ * handle captured once would go stale after the first hook runs.
+ *
+ * @example
+ * ```ts
+ * describe("my plugin", () => {
+ *   const ctx = useServiceContextMock({ warehouseId: "wh-1" });
+ *
+ *   test("resolves the warehouse", async () => {
+ *     await myHandler(req, res);
+ *     expect(ctx.current.getSpy).toHaveBeenCalled();
+ *   });
+ * });
+ * ```
+ *
+ * @returns `{ current }` — the active {@link ServiceContextMock} for the test.
+ */
+declare function useServiceContextMock(options?: TestContextOptions): {
+  readonly current: ServiceContextMock;
+};
+/**
+ * Runs a test function within a mocked service context: installs the mock,
+ * runs `fn`, and restores the singleton afterward.
+ */
+declare function runWithRequestContext<T>(fn: () => T | Promise<T>, context?: TestContextOptions): Promise<T>;
+/**
+ * Builds a SUCCEEDED SQL statement response with a synthetic statement id,
+ * `data_array` rows, and a manifest schema derived from `columns`.
+ */
+declare function createSuccessfulSQLResponse(data: Any[][], columns: Array<{
+  name: string;
+  type_name?: string;
+}>): {
+  status: {
+    state: string;
+  };
+  statement_id: string;
+  result: {
+    data_array: any[][];
+  };
+  manifest: {
+    schema: {
+      columns: {
+        name: string;
+        type_name: string;
+      }[];
+    };
+  };
+};
+/** Builds a FAILED SQL statement response carrying `errorMessage`. */
+declare function createFailedSQLResponse(errorMessage: string): {
+  status: {
+    state: string;
+    error: {
+      message: 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.
+ */
+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>;
+  };
+};
+//#endregion
+export { OboOption, ServiceContextMock, TestContextOptions, createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock };
+//# sourceMappingURL=fixtures.d.ts.map

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

@@ -0,0 +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"}

package/dist/testing/fixtures.js

@@ -0,0 +1,385 @@
+import { ServiceContext } from "../context/service-context.js";
+import { CacheManager } from "../cache/index.js";
+import { afterEach, beforeEach, vi } from "vitest";
+
+//#region src/testing/fixtures.ts
+/**
+* Creates a mock telemetry provider for testing. Every span/meter/logger is a
+* `vi.fn()` no-op, so plugins that trace, count, or log run without a live
+* OpenTelemetry pipeline. Passed into {@link createTestPluginContext} as the one
+* injectable production seam.
+*/
+function createMockTelemetry() {
+	const mockSpan = {
+		addLink: vi.fn(),
+		addLinks: vi.fn(),
+		end: vi.fn(),
+		setAttribute: vi.fn(),
+		setAttributes: vi.fn(),
+		setStatus: vi.fn(),
+		recordException: vi.fn(),
+		updateName: vi.fn(),
+		addEvent: vi.fn(),
+		isRecording: vi.fn().mockReturnValue(false),
+		spanContext: vi.fn()
+	};
+	return {
+		getTracer: vi.fn().mockReturnValue({ startActiveSpan: vi.fn().mockImplementation((...args) => {
+			const fn = args[args.length - 1];
+			if (typeof fn === "function") return fn(mockSpan);
+		}) }),
+		getMeter: vi.fn().mockReturnValue({
+			createCounter: vi.fn().mockReturnValue({ add: vi.fn() }),
+			createHistogram: vi.fn().mockReturnValue({ record: vi.fn() })
+		}),
+		getLogger: vi.fn().mockReturnValue({ emit: vi.fn() }),
+		emit: vi.fn(),
+		startActiveSpan: vi.fn().mockImplementation(async (_name, _options, fn, _tracerOptions) => {
+			return await fn(mockSpan);
+		}),
+		registerInstrumentations: vi.fn()
+	};
+}
+/**
+* Creates a mock Express router that captures registered handlers so a test
+* can pull a handler back out by method + path and invoke it directly.
+*/
+function createMockRouter() {
+	const handlers = {};
+	return {
+		router: {
+			get: vi.fn((path, handler) => {
+				handlers[`GET:${path}`] = handler;
+			}),
+			post: vi.fn((path, handler) => {
+				handlers[`POST:${path}`] = handler;
+			}),
+			put: vi.fn((path, handler) => {
+				handlers[`PUT:${path}`] = handler;
+			}),
+			delete: vi.fn((path, handler) => {
+				handlers[`DELETE:${path}`] = handler;
+			}),
+			patch: vi.fn((path, handler) => {
+				handlers[`PATCH:${path}`] = handler;
+			})
+		},
+		handlers,
+		getHandler: (method, path) => handlers[`${method.toUpperCase()}:${path}`]
+	};
+}
+/** Build the forwarded identity headers an `obo` option implies. */
+function oboHeaders(obo) {
+	const opts = obo === true ? {} : obo;
+	const headers = {
+		"x-forwarded-access-token": opts.token ?? "test-user-token",
+		"x-forwarded-user": opts.userId ?? "test-user"
+	};
+	if (opts.email) headers["x-forwarded-email"] = opts.email;
+	return headers;
+}
+/**
+* Creates a mock Express request. Pass `overrides` to set `params`, `query`,
+* `body`, `headers`, etc.
+*
+* For on-behalf-of tests, pass `obo` instead of hand-adding forwarded headers —
+* `createMockRequest({ obo: true })` sets the identity headers the real
+* `asUser` requires. Any explicit `headers` you also pass win over the ones
+* `obo` generates, so you can override a single field.
+*
+* @example
+* ```ts
+* createMockRequest({ obo: true });                 // default test user + token
+* createMockRequest({ obo: { userId: "alice" } });  // pick the user
+* ```
+*/
+function createMockRequest(overrides = {}) {
+	const { obo, headers: headerOverrides, ...rest } = overrides;
+	const headers = Object.fromEntries(Object.entries({
+		...obo ? oboHeaders(obo) : {},
+		...headerOverrides
+	}).map(([name, value]) => [name.toLowerCase(), value]));
+	return {
+		params: {},
+		query: {},
+		body: {},
+		header: function(name) {
+			return this.headers[name.toLowerCase()];
+		},
+		...rest,
+		headers
+	};
+}
+/**
+* Creates a mock Express response object. `write`/`send`/`setHeader` flip
+* `headersSent`, `end` flips `writableEnded` and fires any `close` listener —
+* enough for streaming handlers that branch on those flags.
+*
+* Every chunk passed to `write` (and a final chunk to `end`) is captured, so a
+* streaming route's real SSE output can be replayed: pass the response straight
+* to {@link expectStream}, or call `sseResponse()` for a real `Response`.
+*
+* @example Assert what a streaming route emitted
+* ```ts
+* const res = createMockResponse();
+* await plugin._handleStream(req, res);
+* await expectStream(res).toEmit("status", "result");
+* ```
+*/
+function createMockResponse() {
+	const eventListeners = {};
+	const chunks = [];
+	return {
+		headersSent: false,
+		status: vi.fn().mockReturnThis(),
+		json: vi.fn().mockReturnThis(),
+		send: vi.fn(function() {
+			this.headersSent = true;
+			return this;
+		}),
+		sendStatus: vi.fn().mockReturnThis(),
+		end: vi.fn(function(chunk) {
+			if (chunk != null && typeof chunk !== "function") chunks.push(String(chunk));
+			this.writableEnded = true;
+			if (eventListeners.close) for (const handler of eventListeners.close) handler();
+			return this;
+		}),
+		write: vi.fn(function(chunk) {
+			this.headersSent = true;
+			if (chunk != null) chunks.push(String(chunk));
+			return this;
+		}),
+		setHeader: vi.fn(function() {
+			this.headersSent = true;
+			return this;
+		}),
+		flushHeaders: vi.fn().mockReturnThis(),
+		destroy: vi.fn().mockReturnThis(),
+		on: vi.fn(function(event, handler) {
+			if (!eventListeners[event]) eventListeners[event] = [];
+			eventListeners[event].push(handler);
+			return this;
+		}),
+		off: vi.fn(function(event, handler) {
+			if (eventListeners[event]) eventListeners[event] = eventListeners[event].filter((h) => h !== handler);
+			return this;
+		}),
+		writableEnded: false,
+		sseResponse() {
+			return new Response(chunks.join(""));
+		}
+	};
+}
+/**
+* Sets up common environment variables for Databricks testing so code that
+* reads `DATABRICKS_HOST` / `DATABRICKS_WAREHOUSE_ID` finds test values.
+*/
+function setupDatabricksEnv(overrides = {}) {
+	process.env.DATABRICKS_HOST = "https://test.databricks.com";
+	process.env.DATABRICKS_WAREHOUSE_ID = "test-warehouse-id";
+	Object.assign(process.env, overrides);
+}
+/**
+* Clears AppKit's process-wide cache singleton so cached values don't leak
+* between tests in the same file.
+*
+* The cache `attach()` seeds is shared by every test in a file (Vitest isolates
+* files, not tests within a file). Call this in `beforeEach` when one test's
+* cached value must not be seen by the next, or mid-test to force a cache miss
+* before asserting a subsequent hit.
+*
+* No-ops when the cache has not been initialized yet, so it is safe to call
+* before any `attach()`.
+*
+* @example
+* ```ts
+* beforeEach(async () => {
+*   await resetTestCache();
+* });
+* ```
+*/
+async function resetTestCache() {
+	let cache;
+	try {
+		cache = CacheManager.getInstanceSync();
+	} catch {
+		return;
+	}
+	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.
+*/
+function buildServiceContextState(options = {}) {
+	return {
+		client: options.serviceDatabricksClient || createMockWorkspaceClient(),
+		serviceUserId: options.serviceUserId || "test-service-user",
+		warehouseId: Promise.resolve(options.warehouseId || "test-warehouse-id"),
+		workspaceId: Promise.resolve(options.workspaceId || "test-workspace-id")
+	};
+}
+/**
+* Mocks the `ServiceContext` singleton for testing — spies `get`,
+* `initialize`, `isInitialized`, and `createUserContext` so code that resolves
+* the service principal or an on-behalf-of user context gets test doubles.
+* Call in `beforeEach`; call the returned `restore()` in `afterEach`.
+*
+* @returns The mock context plus the spies and a `restore()` helper.
+*/
+function mockServiceContext(options = {}) {
+	const serviceContext = buildServiceContextState(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
+		};
+	});
+	return {
+		serviceContext,
+		getSpy,
+		initSpy,
+		isInitializedSpy,
+		createUserContextSpy,
+		restore: () => {
+			getSpy.mockRestore();
+			initSpy.mockRestore();
+			isInitializedSpy.mockRestore();
+			createUserContextSpy.mockRestore();
+		}
+	};
+}
+/**
+* Registers a fresh {@link mockServiceContext} before each test and restores it
+* after — the whole `beforeEach`/`afterEach` dance in one line.
+*
+* Call it at the top of a `describe` block (or module top-level), NOT inside a
+* test: Vitest's `beforeEach`/`afterEach` only register during collection, so a
+* call from within a test body registers nothing for that test.
+*
+* Returns a **live** accessor, not the handle: each `beforeEach` builds fresh
+* spies, so reading `.current` inside a test always sees that test's mock. A
+* handle captured once would go stale after the first hook runs.
+*
+* @example
+* ```ts
+* describe("my plugin", () => {
+*   const ctx = useServiceContextMock({ warehouseId: "wh-1" });
+*
+*   test("resolves the warehouse", async () => {
+*     await myHandler(req, res);
+*     expect(ctx.current.getSpy).toHaveBeenCalled();
+*   });
+* });
+* ```
+*
+* @returns `{ current }` — the active {@link ServiceContextMock} for the test.
+*/
+function useServiceContextMock(options = {}) {
+	let handle;
+	beforeEach(() => {
+		handle = mockServiceContext(options);
+	});
+	afterEach(() => {
+		handle?.restore();
+		handle = void 0;
+	});
+	return { get current() {
+		if (!handle) throw new Error("useServiceContextMock: no active mock. Call useServiceContextMock() at the top of a describe block (not inside a test), and read `.current` from within a test.");
+		return handle;
+	} };
+}
+/**
+* Runs a test function within a mocked service context: installs the mock,
+* runs `fn`, and restores the singleton afterward.
+*/
+async function runWithRequestContext(fn, context) {
+	const mocks = mockServiceContext(context);
+	try {
+		return await fn();
+	} finally {
+		mocks.restore();
+	}
+}
+/**
+* Builds a SUCCEEDED SQL statement response with a synthetic statement id,
+* `data_array` rows, and a manifest schema derived from `columns`.
+*/
+function createSuccessfulSQLResponse(data, columns) {
+	return {
+		status: { state: "SUCCEEDED" },
+		statement_id: `stmt-${Date.now()}`,
+		result: { data_array: data },
+		manifest: { schema: { columns: columns.map((col) => ({
+			name: col.name,
+			type_name: col.type_name ?? "STRING"
+		})) } }
+	};
+}
+/** Builds a FAILED SQL statement response carrying `errorMessage`. */
+function createFailedSQLResponse(errorMessage) {
+	return {
+		status: {
+			state: "FAILED",
+			error: { message: errorMessage }
+		},
+		statement_id: `stmt-${Date.now()}`
+	};
+}
+/**
+* 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.
+*/
+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
+		}
+	};
+}
+
+//#endregion
+export { createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock };
+//# sourceMappingURL=fixtures.js.map