Files
orca/skill-guides/orca-plugin-authoring/references/testing.md
T
Neil ce8ea081c0 Plugin check shows what drew; responsive Table columns; quieter Table and Stack (#37062)
* plugins: check shows what drew; responsive Table columns; quieter Table and Stack

- orca plugin check: each scenario result carries a summary (headings,
  callouts, empty states, table and tree sizes, the selected tab, loading
  placeholders, danger/warning text), printed under its line, and --json
  adds the drawn tree. dev watch's check event keeps only the summary.
  orca/testing gains panel.summary().
- Table columns take minWidth (floor for an auto column) and hideBelow
  ('sm' 360px, 'md' 480px), measured on the table itself; at least one
  column stays. Cut-off cells and headers show their text on hover. The
  kit's columnsOf(table, { width }) answers which columns fit.
- The active-row ring shows only while the grid has keyboard focus.
- A Stack with no align keeps buttons at their own width while fields,
  tables and cards still fill it; align='stretch' stretches everything.
- Typings, docs, the skill's workflow reference, regenerated references;
  the gallery's Kind column drops out in a narrow sidebar.

* plugins: check can render one scenario and return its drawn tree

For orca plugin shot --scenario (tree replay): checkPluginPanels takes
{ panel, scenario, drawnTree }, and with drawnTree returns each render's
validated tree exactly as Orca draws it (handlers as { $callback }),
re-validated on the CLI side. An unknown scenario is reported as an issue.
readPluginCheckScenarioNames(dir, entry) lists a panel's scenarios by
loading its .check file without mounting anything.
2026-11-01 09:07:14 -08:00

7.1 KiB

Test kit (orca/testing)

ORCA plugin test runs *.test.ts(x) files in Node with orca and orca/testing resolved to what this Orca ships, and plugin sources (panels and the worker main) loaded as Orca loads them. Every act resolves once the panel or worker has settled: await it and never add sleeps.

Functions

  • function mockHost(options?: MockHostOptions): MockHost: A stand-in Orca host that refuses what Orca refuses, with the same codes: a missing capability, bad params, a method panels cannot call, and a user-gesture method (shell.openExternal, files.saveAs) without a press first.
  • function hostError(code: string, message?: string, retryAfterMs?: number): HostError
  • function stored(value: unknown, version: number): unknown: A persisted value an older version wrote, to test an atom's migrate.
  • function mount(target: PanelModule | (() => OrcaNode), options?: MountOptions): Promise<TestPanel>: Mounts a panel module (import * as panel from './panel') or its component, with the real runtime and Orca's own checks, and resolves once it has drawn. Mounting again starts over: every atom goes back to its initial value.
  • function mountWorker(module: WorkerModule, options?: MountWorkerOptions): Promise<TestWorker>: Calls the worker's default-exported activate(orca) with the orca object Orca passes, backed by mockHost (worker methods, the manifest's capabilities). .ts mains load as Orca loads them.
  • function defineCheck<S extends Record<string, CheckScenario>>(scenarios: S): S: Named scenarios for orca plugin check, as the default export of <entry>.check.ts beside the panel (src/panel.check.ts for src/panel.tsx). Check renders the panel once per scenario, with the plugin's worker on the same host; without the file it renders once with defaults.
  • function test(name: string, fn: () => unknown): Promise<void>: Node's node:test, re-exported so a test type-checks without the Node typings.
  • function describe(name: string, fn: () => unknown): Promise<void>
  • function beforeEach(fn: () => unknown): void
  • function afterEach(fn: () => unknown): void

TestPanel (from mount)

  • host: MockHost
  • errors: readonly PanelIssue[]
  • warnings: readonly string[]: Props and components Orca would drop, as Orca would warn.
  • refusals: readonly MockHostRefusal[]: Host calls Orca would refuse (a missing capability, no press), even ones the panel caught.
  • persisted: { plugin: Record<string, unknown>; workspace: Record<string, unknown>; storage: Record<string, unknown> }: What persisted atoms hold now, by scope and key; storage is the plugin's storage.
  • find(query: TestQuery): The innermost match, or null.
  • findAll(query: TestQuery)
  • tree(): The drawn tree as plain data, for snapshots; handlers show as [handler].
  • summary(): One line per thing a person notices first: headings, callouts, empty states, table and tree sizes, the selected tab, loading placeholders, danger or warning text.
  • press(target: Target): Each act grants one gesture (a press) and resolves once the panel has settled.
  • type(target: Target, text: string, options?: { replace?: boolean; submit?: boolean }): Types after what the field holds (replace clears it first); submit presses Enter.
  • submit(target: Target)
  • toggle(target: Target): A Switch, Checkbox or Collapsible.
  • select(target: Target, value: string): A Select or RadioGroup option, or a Tabs tab, by value.
  • slide(target: Target, value: number)
  • sort(target: Target, column: string): Table: a header click (ascending first, then flipping).
  • selectRows(target: Target, keys: readonly string[]): Table: replaces the selection with exactly these rows.
  • activateRow(target: Target, key: string): Table: Enter or a double click on a row.
  • loadMore(target: Target): Table: scrolls to the end of the loaded rows (needs hasMore and onLoadMore).
  • expand(target: Target, key: string): Tree: expand or collapse an item, calling onToggle.
  • collapse(target: Target, key: string)
  • selectItem(target: Target, key: string)
  • activateItem(target: Target, key: string)
  • expandedOf(target: Target): Tree: the items Orca shows expanded.
  • columnsOf(target: Target, view?: { width?: number }): Table: the column keys Orca shows at width px (wide when omitted), after hideBelow.
  • rowsOf(target: Target): Table: row keys in the order Orca draws them.
  • valueOf(target: Target): What Orca shows in a value control: text, a flag, a number, a tab, or selected keys.
  • emit(event: E, payload: OrcaEvents[E]): An Orca event: theme, or a workspace or agent event the panel subscribed to.
  • post(event: K, payload: PluginPanelEvents[K]): What the plugin's worker posts with orca.panels.post; plugin.on handlers hear it.
  • post(event: Undeclared<N, PluginPanelEvents>, payload?: JsonValue)
  • setVisible(visible: boolean)
  • rerender()
  • settled()
  • unmount(): Ends the run: setup cleanup, ctx.signal and subscriptions, as when the panel closes.

TestWorker (from mountWorker)

  • host: MockHost
  • logs: readonly string[]: What the worker passed to orca.log.
  • refusals: readonly MockHostRefusal[]
  • posts: readonly { event: string; payload?: unknown; panel?: string }[]: What the worker sent with orca.panels.post, in order.
  • emit(event: E, payload: PluginEvents[E]): Delivers an event as Orca would (checked against Orca's payload schema) and waits for every handler.
  • command(commandId: string, args?: unknown): Runs a registered command and resolves with its result.
  • request(name: K, input?: PluginRequestInput<K>, caller?: { panel?: string }): A panel's plugin.request, answered by the worker's orca.panels.handle; panel names the calling panel's contribution id. An unhandled name rejects with unknown_method.
  • request(name: Undeclared<N, PluginRequests>, input?: JsonValue, caller?: { panel?: string })
  • deactivate(): Runs the module's deactivate and drops its handlers.

MockHost (from mockHost)

  • calls: readonly { method: string; params: unknown }[]: Every call that reached the host, in order, refused ones included.
  • refusals: readonly MockHostRefusal[]: capability_denied, not_permitted, invalid_params or unknown_method calls.
  • callsOf(method: string)
  • respond(method: string, result: unknown)
  • data(): The plugin's storage, settings and secrets as they are now.

Options

  • MountOptions = { host?: MockHost; theme?: 'light' | 'dark'; locale?: string; visible?: boolean; panelId?: string; persisted?: { plugin?: Record<string, unknown>; workspace?: Record<string, unknown> } }
  • MountWorkerOptions = { host?: MockHost; events?: readonly string[]; commands?: readonly string[] }
  • MockHostOptions = { capabilities?: readonly string[]; results?: Record<string, unknown>; requests?: MockRequests; storage?: Record<string, JsonValue>; settings?: Record<string, JsonValue>; secrets?: Record<string, string> }
  • CheckScenario = MockHostOptions & { persisted?: MountOptions['persisted']; theme?: 'light' | 'dark'; events?: readonly { [E in keyof OrcaEvents]: { event: E; payload: OrcaEvents[E] } }[keyof OrcaEvents][] }