@databricks/appkit 0.61.1 → 0.63.0

package/dist/workspace-client/legacy.js.map

@@ -1 +1 @@
-{"version":3,"file":"legacy.js","names":[],"sources":["../../src/workspace-client/legacy.ts"],"sourcesContent":["/**\n * The single module in AppKit allowed to import `@databricks/sdk-experimental`\n * directly (enforced by the Biome `noRestrictedImports` boundary rule). Every\n * other AppKit module reaches the SDK through the wrapper's re-exports and the\n * {@link WorkspaceClient} facade.\n *\n * Isolating the SDK here is what makes the incremental migration to the modular\n * Databricks SDK a localized change: to migrate a service, swap its getter in\n * `client.ts` from the legacy delegate to the modular client — nothing else in\n * the codebase imports the SDK, so the blast radius is one connector + its test.\n */\n\nimport type {\n  ClientOptions,\n  WorkspaceClient as SdkWorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport * as SDK from \"@databricks/sdk-experimental\";\n\nconst { WorkspaceClient: SdkWorkspaceClientCtor } = SDK;\n\n/** The concrete legacy SDK client type. */\nexport type LegacyWorkspaceClient = SdkWorkspaceClient;\n\n/**\n * Options used to construct the wrapper. Mirrors the subset of the old SDK's\n * `Config` + `ClientOptions` that AppKit relies on today; we deliberately do\n * NOT re-expose every old-SDK config knob.\n */\nexport interface WorkspaceClientOptions {\n  /** Databricks host, e.g. https://my-workspace.cloud.databricks.com. Defaults to DATABRICKS_HOST / profile resolution. */\n  host?: string;\n  /** `~/.databrickscfg` profile name. Used when no host/token is provided. */\n  profile?: string;\n  /** Bearer token. When set, `authType` defaults to \"pat\". */\n  token?: string;\n  /** Authentication strategy passed to the legacy client. */\n  authType?: \"pat\";\n  /**\n   * SDK client options (product / productVersion / userAgentExtra) used to\n   * stamp the outbound User-Agent. Produced by `getClientOptions()`; omitted\n   * by build-time callers that don't stamp a User-Agent.\n   */\n  clientOptions?: ClientOptions;\n}\n\n/**\n * Construct a legacy `WorkspaceClient` from wrapper options.\n *\n * Centralised so the wrapper facade, the `.toLegacyWorkspaceClient()` escape\n * hatch, and any per-request OBO client all build it the same way.\n */\nexport function buildLegacyWorkspaceClient(\n  opts: WorkspaceClientOptions,\n): LegacyWorkspaceClient {\n  // Check `token !== undefined`, NOT truthiness: an explicitly-passed token\n  // must stick to the PAT path even when it's an empty string. Falling through\n  // to the default-auth branch on an empty OBO token would silently\n  // authenticate as the service principal instead of failing — a privilege\n  // escalation in the OBO path. An invalid/empty token should blow up loudly.\n  const cfg =\n    opts.token !== undefined\n      ? { host: opts.host, token: opts.token, authType: opts.authType ?? \"pat\" }\n      : opts.host\n        ? { host: opts.host }\n        : opts.profile\n          ? { profile: opts.profile }\n          : {};\n  return new SdkWorkspaceClientCtor(cfg, opts.clientOptions);\n}\n\n// ── SDK type re-exports ──────────────────────────────────────────────\nexport type {\n  CancellationToken,\n  ClientOptions,\n} from \"@databricks/sdk-experimental\";\n// ── SDK value re-exports ─────────────────────────────────────────────\n//\n// AppKit modules import these from the wrapper instead of the SDK so the\n// boundary rule holds. `Context` bridges AbortSignal → CancellationToken\n// (serving/jobs/sql-warehouse); `Time`/`TimeUnits` drive genie polling;\n// `ConfigError` is matched in service-context's auth-failure handling.\n//\n// These are sourced off the namespace import rather than `export { ... } from`\n// because the SDK is CommonJS: its `Time` export is emitted as a getter that\n// calls `__importDefault(...)`, which defeats Node's static named-export\n// detection — a direct `export { Time }` throws \"does not provide an export\n// named 'Time'\" at ESM link time. `Time` is only reachable via the module\n// object, so we fall back to `SDK.default.Time` (matching the original genie\n// connector's `SDK.Time ?? SDK.default.Time` guard).\nexport const { ConfigError, Context, TimeUnits, loadConfigFile } = SDK;\nexport const Time =\n  SDK.Time ?? (SDK as unknown as { default: typeof SDK }).default.Time;\n\n// Deep-import types used by the genie connector's waiter idiom. Not exposed\n// on the SDK's top-level index, so re-exported here to keep the genie\n// connector off a direct `@databricks/sdk-experimental/dist/**` import.\nexport type { GenieMessage } from \"@databricks/sdk-experimental/dist/apis/dashboards\";\nexport type { Waiter } from \"@databricks/sdk-experimental/dist/wait\";\n"],"mappings":";;;AAkBA,MAAM,EAAE,iBAAiB,2BAA2B;;;;;;;AAiCpD,SAAgB,2BACd,MACuB;AAcvB,QAAO,IAAI,uBAPT,KAAK,UAAU,SACX;EAAE,MAAM,KAAK;EAAM,OAAO,KAAK;EAAO,UAAU,KAAK,YAAY;EAAO,GACxE,KAAK,OACH,EAAE,MAAM,KAAK,MAAM,GACnB,KAAK,UACH,EAAE,SAAS,KAAK,SAAS,GACzB,EAAE,EAC2B,KAAK,cAAc;;AAsB5D,MAAa,EAAE,aAAa,SAAS,WAAW,mBAAmB;AACnE,MAAa,OACX,IAAI,QAAS,IAA2C,QAAQ"}
+{"version":3,"file":"legacy.js","names":[],"sources":["../../src/workspace-client/legacy.ts"],"sourcesContent":["/**\n * The single module in AppKit allowed to import `@databricks/sdk-experimental`\n * directly (enforced by the oxlint `no-restricted-imports` boundary rule). Every\n * other AppKit module reaches the SDK through the wrapper's re-exports and the\n * {@link WorkspaceClient} facade.\n *\n * Isolating the SDK here is what makes the incremental migration to the modular\n * Databricks SDK a localized change: to migrate a service, swap its getter in\n * `client.ts` from the legacy delegate to the modular client — nothing else in\n * the codebase imports the SDK, so the blast radius is one connector + its test.\n */\n\nimport type {\n  ClientOptions,\n  WorkspaceClient as SdkWorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport * as SDK from \"@databricks/sdk-experimental\";\n\nconst { WorkspaceClient: SdkWorkspaceClientCtor } = SDK;\n\n/** The concrete legacy SDK client type. */\nexport type LegacyWorkspaceClient = SdkWorkspaceClient;\n\n/**\n * Options used to construct the wrapper. Mirrors the subset of the old SDK's\n * `Config` + `ClientOptions` that AppKit relies on today; we deliberately do\n * NOT re-expose every old-SDK config knob.\n */\nexport interface WorkspaceClientOptions {\n  /** Databricks host, e.g. https://my-workspace.cloud.databricks.com. Defaults to DATABRICKS_HOST / profile resolution. */\n  host?: string;\n  /** `~/.databrickscfg` profile name. Used when no host/token is provided. */\n  profile?: string;\n  /** Bearer token. When set, `authType` defaults to \"pat\". */\n  token?: string;\n  /** Authentication strategy passed to the legacy client. */\n  authType?: \"pat\";\n  /**\n   * SDK client options (product / productVersion / userAgentExtra) used to\n   * stamp the outbound User-Agent. Produced by `getClientOptions()`; omitted\n   * by build-time callers that don't stamp a User-Agent.\n   */\n  clientOptions?: ClientOptions;\n}\n\n/**\n * Construct a legacy `WorkspaceClient` from wrapper options.\n *\n * Centralised so the wrapper facade, the `.toLegacyWorkspaceClient()` escape\n * hatch, and any per-request OBO client all build it the same way.\n */\nexport function buildLegacyWorkspaceClient(\n  opts: WorkspaceClientOptions,\n): LegacyWorkspaceClient {\n  // Check `token !== undefined`, NOT truthiness: an explicitly-passed token\n  // must stick to the PAT path even when it's an empty string. Falling through\n  // to the default-auth branch on an empty OBO token would silently\n  // authenticate as the service principal instead of failing — a privilege\n  // escalation in the OBO path. An invalid/empty token should blow up loudly.\n  const cfg =\n    opts.token !== undefined\n      ? { host: opts.host, token: opts.token, authType: opts.authType ?? \"pat\" }\n      : opts.host\n        ? { host: opts.host }\n        : opts.profile\n          ? { profile: opts.profile }\n          : {};\n  return new SdkWorkspaceClientCtor(cfg, opts.clientOptions);\n}\n\n// ── SDK type re-exports ──────────────────────────────────────────────\nexport type {\n  CancellationToken,\n  ClientOptions,\n} from \"@databricks/sdk-experimental\";\n// ── SDK value re-exports ─────────────────────────────────────────────\n//\n// AppKit modules import these from the wrapper instead of the SDK so the\n// boundary rule holds. `Context` bridges AbortSignal → CancellationToken\n// (serving/jobs/sql-warehouse); `Time`/`TimeUnits` drive genie polling;\n// `ConfigError` is matched in service-context's auth-failure handling.\n//\n// These are sourced off the namespace import rather than `export { ... } from`\n// because the SDK is CommonJS: its `Time` export is emitted as a getter that\n// calls `__importDefault(...)`, which defeats Node's static named-export\n// detection — a direct `export { Time }` throws \"does not provide an export\n// named 'Time'\" at ESM link time. `Time` is only reachable via the module\n// object, so we fall back to `SDK.default.Time` (matching the original genie\n// connector's `SDK.Time ?? SDK.default.Time` guard).\nexport const { ConfigError, Context, TimeUnits, loadConfigFile } = SDK;\nexport const Time =\n  SDK.Time ?? (SDK as unknown as { default: typeof SDK }).default.Time;\n\n// Deep-import types used by the genie connector's waiter idiom. Not exposed\n// on the SDK's top-level index, so re-exported here to keep the genie\n// connector off a direct `@databricks/sdk-experimental/dist/**` import.\nexport type { GenieMessage } from \"@databricks/sdk-experimental/dist/apis/dashboards\";\nexport type { Waiter } from \"@databricks/sdk-experimental/dist/wait\";\n"],"mappings":";;;AAkBA,MAAM,EAAE,iBAAiB,2BAA2B;;;;;;;AAiCpD,SAAgB,2BACd,MACuB;AAcvB,QAAO,IAAI,uBAPT,KAAK,UAAU,SACX;EAAE,MAAM,KAAK;EAAM,OAAO,KAAK;EAAO,UAAU,KAAK,YAAY;EAAO,GACxE,KAAK,OACH,EAAE,MAAM,KAAK,MAAM,GACnB,KAAK,UACH,EAAE,SAAS,KAAK,SAAS,GACzB,EAAE,EAC2B,KAAK,cAAc;;AAsB5D,MAAa,EAAE,aAAa,SAAS,WAAW,mBAAmB;AACnE,MAAa,OACX,IAAI,QAAS,IAA2C,QAAQ"}

package/dist/workspace-client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/workspace-client/types.ts"],"mappings":";;;;;;;;;;;;UAkCiB,iBAAA;EAWA;EAAA,SATN,KAAA,EAAO,qBAAA;EAYa;EAAA,SATpB,UAAA,EAAY,qBAAA;EAYM;EAAA,SATlB,KAAA,EAAO,qBAAA;EAYM;EAAA,SATb,IAAA,EAAM,qBAAA;EAgBE;EAAA,SAbR,kBAAA,EAAoB,qBAAA;EAoBT;EAAA,SAjBX,gBAAA,EAAkB,qBAAA;EAwBA;EAAA,SArBlB,WAAA,EAAa,qBAAA;EAqB0B;;;;;EAAA,SAdvC,MAAA,EAAQ,qBAAA;;;;;;WAOR,SAAA,EAAW,qBAAA;;;;;;EAOpB,uBAAA,IAA2B,qBAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/workspace-client/types.ts"],"mappings":";;;;;;;;;;;;UA6BiB,iBAAA;EAWA;EAAA,SATN,KAAA,EAAO,qBAAA;EAYa;EAAA,SATpB,UAAA,EAAY,qBAAA;EAYM;EAAA,SATlB,KAAA,EAAO,qBAAA;EAYM;EAAA,SATb,IAAA,EAAM,qBAAA;EAgBE;EAAA,SAbR,kBAAA,EAAoB,qBAAA;EAoBT;EAAA,SAjBX,gBAAA,EAAkB,qBAAA;EAwBA;EAAA,SArBlB,WAAA,EAAa,qBAAA;EAqB0B;;;;;EAAA,SAdvC,MAAA,EAAQ,qBAAA;;;;;;WAOR,SAAA,EAAW,qBAAA;;;;;;EAOpB,uBAAA,IAA2B,qBAAA;AAAA"}

package/docs/plugins/testing.md

@@ -0,0 +1,245 @@
+# Testing
+
+AppKit ships a testing kit at `@databricks/appkit/testing` so you can test a plugin — including its cross-plugin tool calls and streaming responses — without a live Databricks workspace, credentials, or network access. That makes plugin tests fast and lets them run in CI, where no workspace is available.
+
+## Goal[​](#goal "Direct link to Goal")
+
+Exercise a plugin's real code paths — route registration, cross-plugin tool dispatch, user-scoped (on-behalf-of) execution, and per-call timeouts — against a real `PluginContext` with only its outer edges faked. Nothing about the context is reimplemented, so a test can't drift from production behavior.
+
+The kit has two entry points plus a set of fixture helpers:
+
+* **`createTestPluginContext()`** — build a real `PluginContext` with faked edges and attach it to a plugin.
+* **`expectStream(...).toEmit(...)`** — assert the ordered event types a stream emits.
+* **Fixtures** — `createMockRequest`, `createMockResponse`, `mockServiceContext`, and SQL response builders.
+
+The kit uses [Vitest](https://vitest.dev)'s `vi` for its mocks, so `vitest` is an **optional peer dependency**: you already have it (you're writing Vitest tests), and the kit resolves to your copy rather than bundling a second one. Because it's optional, it is not installed into apps that never import `@databricks/appkit/testing` — production installs stay free of the test framework. Any Vitest v3 or v4 works.
+
+## `createTestPluginContext()`[​](#createtestplugincontext "Direct link to createtestplugincontext")
+
+`PluginContext` is the mediator AppKit passes to every plugin — it buffers routes, tracks tool providers, and runs cross-plugin tool calls with user scoping and a timeout. `createTestPluginContext()` returns the **real** context with three edges faked:
+
+| Edge           | How it's faked                                                                            |
+| -------------- | ----------------------------------------------------------------------------------------- |
+| Telemetry      | A no-op mock provider — no OpenTelemetry pipeline needed.                                 |
+| Tool providers | Fakes registered through the real `registerToolProvider`, keyed by plugin then tool name. |
+| Routes         | The real `addRoute`/`addMiddleware` are wrapped to record what a plugin registers.        |
+
+Because the context is real, `executeTool` still resolves the user scope via `asUser(req)` and still composes the abort signal from your timeout — so those paths are genuinely under test.
+
+### Registering fake tool responses[​](#registering-fake-tool-responses "Direct link to Registering fake tool responses")
+
+Pass canned responses keyed by plugin name, then tool name. A response is either a static value or a function of the call arguments and the composed abort signal:
+
+```ts
+import { createTestPluginContext } from "@databricks/appkit/testing";
+
+const mock = createTestPluginContext({
+  analytics: {
+    // static response
+    top_users: [{ user: "alice", events: 42 }],
+    // function response — assert on args, or simulate slow/aborting work
+    query: (args, signal) => runFakeQuery(args, signal),
+  },
+});
+
+```
+
+### Attaching to a plugin[​](#attaching-to-a-plugin "Direct link to Attaching to a plugin")
+
+`attach()` wires the context to a plugin the production way: it seeds an in-memory cache (if AppKit hasn't already initialized one), then calls the plugin's `attachContext`, which rebuilds telemetry and flips `isReady` to `true`. Await it before exercising any handler that reads `this.context`, `this.cache`, or gates on `isReady`:
+
+```ts
+const plugin = new MyAgentPlugin({ dir: false });
+await mock.attach(plugin);
+
+```
+
+Instantiate the plugin **class** directly (`new MyAgentPlugin(...)`). The `analytics()` / `agents()` factories you pass to `createApp` return a descriptor for the app to construct — for a unit test you want the instance.
+
+The cache `attach()` seeds is a process-wide singleton: `CacheManager` is initialized once per test process and reused. Vitest isolates test *files* in separate workers, so caches never leak across files, but tests **within one file** share it. If a test populates the cache and a later test in the same file must not see it, clear it between tests with `resetTestCache()`:
+
+```ts
+import { resetTestCache } from "@databricks/appkit/testing";
+
+beforeEach(async () => {
+  await resetTestCache(); // no-op if the cache isn't initialized yet
+});
+
+```
+
+It also helps *within* a single test — clear the cache to force a miss, then assert the following call is a hit.
+
+### Inspecting what happened[​](#inspecting-what-happened "Direct link to Inspecting what happened")
+
+The returned object exposes live views you read after the action under test runs:
+
+```ts
+await someHandler(req, res);
+
+// Every cross-plugin tool dispatch, in order.
+expect(mock.toolCalls[0]).toMatchObject({
+  plugin: "analytics",
+  tool: "query",
+  asUser: true, // proves the on-behalf-of path ran
+});
+
+// Every route the plugin registered (raw handlers, before wrapping).
+expect(mock.routes).toContainEqual(
+  expect.objectContaining({ method: "post", path: "/invocations" }),
+);
+
+// The injected telemetry provider records the context's own spans — i.e. the
+// span PluginContext.executeTool opens around each cross-plugin tool call.
+expect(mock.telemetry.getTracer().startActiveSpan).toHaveBeenCalled();
+
+```
+
+`mock.telemetry` is injected into the `PluginContext`, so it captures the spans the *context* opens (notably `executeTool`). It is **not** the plugin's own telemetry: `attachContext` rebuilds `this.telemetry` from the real `TelemetryManager`, so spans a plugin opens internally do not land on `mock.telemetry`.
+
+`RecordedToolCall.asUser` is the high-value signal for cross-plugin calls: because the fake `asUser` enforces the same token precondition as the real `Plugin.asUser`, a dispatch that records `asUser: true` (with `userId` set) genuinely resolved the caller's user scope, and a request missing `x-forwarded-access-token` **rejects** instead — the OBO distinction that silent `{ executeTool }` stubs cannot verify. Assert both directions: a well-formed request records the expected `userId`, and a token-less one throws.
+
+The fake replicates `asUser`'s **token precondition**, not its internal dev-mode telemetry marker: in `NODE_ENV=development` the real `Plugin.asUser` skips impersonation and sets an OTel `isDevOboFallback()` flag, which the fake does not reproduce. Assert OBO through the recorded `asUser`/`userId` fields rather than `isDevOboFallback()`.
+
+## `expectStream(...)`[​](#expectstream "Direct link to expectstream")
+
+AppKit plugins stream Server-Sent Events. `expectStream` consumes a stream and asserts the ordered event types it emits. It accepts an async iterable (an agent adapter's `run()`), a plain array of events, an SSE `Response` (or a promise of one) whose body it parses, or a `createMockResponse()` whose captured writes it replays.
+
+```ts
+import { expectStream } from "@databricks/appkit/testing";
+
+// In-order subsequence match — interleaved events (heartbeats, deltas) are ignored.
+await expectStream(agent.adapter.run(input)).toEmit("tool_call", "message_delta");
+
+// Exact match — the stream's full shape, in order, with nothing else.
+await expectStream(events).toEmitExactly("warehouse_status", "result");
+
+// Or collect without asserting.
+const types = await expectStream(res).collectTypes();
+
+```
+
+### Asserting a plugin's streaming route[​](#asserting-a-plugins-streaming-route "Direct link to Asserting a plugin's streaming route")
+
+Most plugins stream SSE from a **route handler** (`res.write(...)`), not a bare generator. `createMockResponse()` captures those writes, and `expectStream` reads them straight back — drive the real handler, then assert:
+
+```ts
+import { createMockRequest, createMockResponse, expectStream } from "@databricks/appkit/testing";
+
+const res = createMockResponse();
+await plugin._handleStream(createMockRequest({ obo: true }), res);
+
+// The mock captured the SSE the handler wrote; expectStream parses it.
+await expectStream(res).toEmit("status", "result");
+
+```
+
+`expectStream(res)` and `expectStream(res.sseResponse())` are equivalent — the latter hands you the raw `Response` if you want it. Do **not** pass the SSE body as a string: a string is an iterable of characters, so `expectStream` rejects it with a pointer to `sseResponse()` rather than emitting one "event" per character.
+
+`toEmit` checks that the expected types appear **in order** but tolerates other events before, between, or after them — which is what you want for streams that interleave bookkeeping events like heartbeats or metadata. Use `toEmitExactly` when the stream's shape is fully determined.
+
+`expectStream` buffers the whole source before asserting, so a stream that never terminates would otherwise hang until the test runner's own timeout. Pass `{ timeout }` to fail fast with a clear error instead:
+
+```ts
+await expectStream(handler.stream(req), { timeout: 1000 }).toEmit("result");
+
+```
+
+## Fixtures[​](#fixtures "Direct link to Fixtures")
+
+The kit re-exports the request/response/context fixtures AppKit uses internally:
+
+* `createMockRequest(overrides?)` / `createMockResponse()` — Express request/response doubles, including the streaming flags (`headersSent`, `writableEnded`). Pass `obo: true` (or `obo: { userId, token, email }`) to set the forwarded identity headers `asUser` requires, instead of hand-adding them. `createMockResponse()` also captures everything a handler writes; pass it to `expectStream` (or call `sseResponse()`) to assert a streaming route's SSE. (Plugins resolve the workspace client through `getWorkspaceClient()`, not the request — use `mockServiceContext` to control it.)
+* `mockServiceContext(options?)` — spy the `ServiceContext` singleton so code that resolves the service principal or a user context gets test doubles. Call in `beforeEach`, and call the returned `restore()` in `afterEach`.
+* `useServiceContextMock(options?)` — the same, in one line: it registers the `beforeEach` install and `afterEach` restore for you. Call it at the top of a `describe` block (not inside a test), and read the live `.current` handle from within a test:
+  <!-- -->
+  ```ts
+  describe("my plugin", () => {
+    const ctx = useServiceContextMock();
+    test("...", async () => {
+      await handler(createMockRequest({ obo: true }), res);
+      expect(ctx.current.createUserContextSpy).toHaveBeenCalled();
+    });
+  });
+
+  ```
+* `createSuccessfulSQLResponse(rows, columns)` / `createFailedSQLResponse(message)` — build SQL Warehouse statement responses.
+* `setupDatabricksEnv(overrides?)` — set `DATABRICKS_HOST` / `DATABRICKS_WAREHOUSE_ID` to test values.
+* `resetTestCache()` — clear the shared cache singleton between (or within) tests; no-ops if the cache isn't initialized yet.
+
+## Full example[​](#full-example "Direct link to Full example")
+
+Instantiate the plugin **class** directly with `new`. The `analytics()` / `agents()` factory functions you pass to `createApp` return a descriptor for the app to construct — for a unit test you want the instance itself.
+
+```ts
+import { Plugin, type PluginManifest } from "@databricks/appkit";
+import { expectStream, createMockRequest, createTestPluginContext } from "@databricks/appkit/testing";
+import { describe, expect, test } from "vitest";
+
+// A small plugin that registers a route and streams two events.
+class GreeterPlugin extends Plugin {
+  static manifest = {
+    name: "greeter",
+    displayName: "Greeter",
+    description: "Example plugin",
+    resources: { required: [], optional: [] },
+  } as PluginManifest<"greeter">;
+
+  async setup() {
+    this.context?.addRoute("get", "/hello", (_req, res) => res.end());
+  }
+
+  async *greet(name: string) {
+    yield { type: "greeting_start", name };
+    yield { type: "greeting_end", message: `Hello, ${name}!` };
+  }
+}
+
+describe("greeter plugin", () => {
+  test("registers its route through the context", async () => {
+    const mock = createTestPluginContext();
+    const plugin = new GreeterPlugin({});
+
+    await mock.attach(plugin);
+    await plugin.setup();
+
+    expect(mock.routes).toContainEqual(
+      expect.objectContaining({ method: "get", path: "/hello" }),
+    );
+  });
+
+  test("streams events in order", async () => {
+    const plugin = new GreeterPlugin({});
+    await expectStream(plugin.greet("world")).toEmit(
+      "greeting_start",
+      "greeting_end",
+    );
+  });
+});
+
+```
+
+To test a plugin that dispatches cross-plugin tool calls, register fake providers and assert on `mock.toolCalls` — including `asUser`, which confirms the on-behalf-of path ran:
+
+```ts
+const mock = createTestPluginContext({ analytics: { query: [{ n: 1 }] } });
+const plugin = new MyAgentPlugin({ dir: false });
+await mock.attach(plugin);
+
+// `obo` sets the forwarded identity headers `asUser` needs — without them the
+// dispatch would (correctly) reject with "Missing user token".
+const req = createMockRequest({ obo: true });
+await plugin.runSomethingThatCallsAnalytics(req);
+
+expect(mock.toolCalls[0]).toMatchObject({
+  plugin: "analytics",
+  tool: "query",
+  asUser: true,
+});
+
+```
+
+## See also[​](#see-also "Direct link to See also")
+
+* [Custom plugins](./docs/plugins/custom-plugins.md) — build the plugins you test with this kit.
+* [Execution context](./docs/plugins/execution-context.md) — how `asUser` and the service principal differ at runtime.
+* [Local development](./docs/development/local-development.md) — run your app with hot reload while iterating.

package/llms.txt

@@ -58,6 +58,7 @@ npx @databricks/appkit docs <query>
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
 - [Plugin Stability Tiers](./docs/plugins/stability.md): AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
+- [Testing](./docs/plugins/testing.md): AppKit ships a testing kit at @databricks/appkit/testing so you can test a plugin — including its cross-plugin tool calls and streaming responses — without a live Databricks workspace, credentials, or network access. That makes plugin tests fast and lets them run in CI, where no workspace is available.
 
 ## appkit API reference [collapsed]
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.61.1",
+  "version": "0.63.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
@@ -33,6 +33,10 @@
     "./beta": "./dist/beta.js",
     "./dist/shared/src/plugin": "./dist/shared/src/plugin.d.ts",
     "./type-generator": "./dist/type-generator/index.js",
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -86,6 +90,14 @@
     "commander": "12.1.0",
     "yaml": "2.8.2"
   },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@opentelemetry/context-async-hooks": "2.8.0",
     "@types/express": "4.17.25",
@@ -93,7 +105,8 @@
     "@types/json-schema": "7.0.15",
     "@types/pg": "8.16.0",
     "@types/ws": "8.18.1",
-    "@vitejs/plugin-react": "5.1.1"
+    "@vitejs/plugin-react": "5.1.1",
+    "vitest": "3.2.4"
   },
   "overrides": {
     "vite": "npm:rolldown-vite@7.1.14"