# Plugin dev loop, shots, tests and checks
Hand-written companion to the `orca-plugin-authoring` guide. `ORCA` is the Orca executable you
resolved; pass `--json` and branch on `error.code`.
## dev watch
`ORCA plugin dev watch
[--check] [--shot [--shot-panel ]] [--approve ] --json`
loads the folder (refreshing `.orca/types`) and prints one JSON object per line:
- `loaded`, `unloaded`, `disconnected`, `warning`.
- `log`: what panels, editors and the worker print. Console errors and uncaught exceptions read
`[frame] :: ` at your source position, with engine frames such as
`Array.forEach ()` dropped. A `[frame]` line repeated within one reload prints once
(`count`: copies that came together, shown `×N`); later copies arrive as one `repeat: true`
line with their `count` at the next reload or when the watch ends.
- `reloaded` (before that reload's logs) and `status` (`errored`/`invalid` with the error).
- `approval`: an edit asked for new access; it carries the `dev reload … --approve` command to
show the user. The watch keeps running and never approves.
- `check` (with `--check`): `orca plugin check` after the load and each reload, with `panels`
and `editors` (each custom editor checked without running it). `ok` is false
unless Orca also runs the plugin; `checkOk` is the check alone, `pluginStatus`/`pluginError`
what Orca reports.
- `shot` (with `--shot`): `{ path, width, height, settled, errors }` for the panel opened once at
start (the first, or `--shot-panel `). Read the PNG. `shot_skipped` means the user switched
the sidebar away: leave it, shots resume when they show the panel again.
A first load that needs consent prints one error line and exits `3`; re-run with `--approve`
(Ctrl-C still unloads the folder the refused attempt added). Ctrl-C unloads only what this watch
loaded; a second Ctrl-C exits at once.
Off the watch: `ORCA plugin logs --json` (the same lines), `ORCA plugin restart
` (reruns a worker's startup code), `ORCA plugin dev reload ` (a missed save, or
re-checks changed commands and shortcuts), `ORCA plugin dev unload `.
## Seeing and showing the panel
- `ORCA plugin shot [--panel ] [--theme light|dark] [--width ] [--out ] --json`
waits for the panel's current code to draw and, for a components panel, for its host calls
(`plugin.request` included) to answer and redraw (at most 3s more), then writes a PNG cropped to
it (default `.orca/shots/-.png` in the plugin folder when run inside one, else
in ``) and returns `{ path, width, height, theme, themeApplied, themeReason?, settled,
errors, pendingRequests?, actions?, restored? }`. `pendingRequests` above 0 means a worker had
not answered, so the PNG may show the loading state. Check a narrow `--width` and both themes. `--theme` applies only while Orca's
window is hidden or minimized; otherwise `themeApplied` is false with a `themeReason`, so
nothing on the user's screen repaints.
- `--act ''` drives a components panel before the capture, in the test kit's verbs:
`[{"type":{"label":"New task"},"text":"Ship","submit":true},{"press":{"text":"Add"}},
{"select":{"label":"View"},"value":"done"},{"toggle":{"label":"Hide done"}}]` (at most 20;
queries take `text`, `label`, `testId`, `type`, `role`). Also `{"slide":Q,"value":7}`, for a
Table `{"sort":Q,"column":"name"}`, `{"selectRows":Q,"keys":["a"]}`,
`{"activateRow":Q,"key":"a"}`, `{"loadMore":Q}`, and for a Tree `{"expand":Q,"key":"src"}`,
`collapse`, `selectItem`, `activateItem` (same `key`). Each act goes through Orca's own control,
then waits for the panel to redraw and its host calls to answer; `actions` has one
`{ ok, error? }` each, the first failure skips the rest and exits 1. After the capture the
panel's atoms are put back, persisted ones included (`restored`; false if it reloaded
meanwhile), but not what handlers changed elsewhere: a `plugin.request` that wrote worker
storage stays written. It needs Orca's window hidden or minimized, so it never
clicks under the user, and refuses html panels. Acts are not a person's press: a Link's href
stays closed and `shell.openExternal` / `files.saveAs` are refused.
- `ORCA plugin shot --scenario [--panel ] [--theme] [--width] [--out]` shoots
one scenario of the panel's `.check.ts` instead of the live panel: the CLI renders it
as `plugin check` does (the panel and the worker against a stand-in host, so the scenario's
data never reaches the real panel, storage, settings or worker), then Orca draws that tree in
a preview apart from the plugin and captures it; the sidebar is not opened or switched. It
runs the plugin's code on this machine, unsandboxed, like `plugin check`. A key works only for
a dev plugin, run inside its folder. The result adds `replay: true` and `scenario`, and
`errors` has what the render reported; an unknown name fails and lists the scenarios. Limits:
a still frame (host-owned control values start from the tree's props), images show their
placeholder, no `--act`, local only (no `--environment`), and Orca's window must be hidden
or minimized. Default file `.orca/shots/-..png`.
- `ORCA plugin open [--panel | --editor ]` shows the panel in the right
sidebar, or a file in the plugin's custom editor. Neither raises the window. `--editor` opens the
file in the workspace that holds it (its real path counts: `/tmp` is `/private/tmp`), or else
opens the file's folder as a folder workspace first.
## Seeing and driving a custom editor
The editor loop: edit the editor's code (a `dev watch` reloads it), then
`ORCA plugin shot --editor [--theme light|dark] [--width ] [--height ]
[--act ''] --json`, then read the PNG. It opens the file like `plugin open --editor`, loads
the editor afresh, waits for it to get its document and ask for it (`orca.document.get` or
`onDidChange`) and paint, then captures exactly the editor with the window hidden. `--act` is real
input in the editor's own CSS pixels: `[{"click":[200,150]},{"drag":[[200,150],[400,300]]},
{"key":"r"}]` (`key` takes a name such as `Enter` and optional `"modifiers":["meta"]`), each
painted before the next; it needs the window hidden or minimized. A shot never changes your file:
`--act` runs on a copy in a temporary folder workspace that is removed afterwards (`--in-place`
acts on the file itself and keeps its tab open), and a shot without acts closes the tab it
opened. Edits only mark the tab dirty, as typing does: to write them to disk, end an `--in-place`
`--act` with `{"key":"s","modifiers":["meta"]}` (`"control"` on Linux and Windows). Before each `key` Orca focuses the editor's guest, so a canvas keeps getting keys. It exits 1 and lists `errors` when the editor threw, was blocked by its
content policy, or never asked for its document within 5s; the PNG is written anyway. The theme
and size are put back. Default file `.orca/shots/-.png`.
`ORCA plugin shot --status-bar [--theme light|dark]` captures Orca's status bar, where your
status bar items draw, and `--window` the whole window, both from the hidden window. Default files
`.orca/shots/-status-bar.png` and `-window.png`.
- Both need the desktop app with a workspace. With none showing, a shot selects one of this
machine's workspaces in the hidden window. A shot never changes the view: it fails with
`no_workspace` while Orca shows Settings or another full page. Without them, use `plugin check`.
- From an Orca source checkout, `ORCA` is `node config/scripts/orca-dev.mjs` after
`pnpm run build:cli` and `pnpm run build:electron-vite`; `ORCA open` starts that checkout's dev
app (`ORCA_BACKGROUND_LAUNCH=1` keeps its window hidden). The CLI has no quit command: stop a
hidden dev app by ending the Electron process whose arguments name the checkout.
## Events
`ORCA plugin dev emit --data ''` fires a test event under the real
rules (approved dev plugin, the event's capability, payload checked against its schema). The
worker hears it when it lists the event in `contributes.events`; each open panel hears it once it
called `orca.on(event, …)`. Nothing listening is refused. Handler errors arrive as `log` lines.
`ORCA plugin dev request --data ''` calls the worker's
`orca.panels.handle(name, …)` handler the way a panel's `plugin.request` does (approved dev plugin
with `main`; the worker starts if needed) and prints `{ pluginKey, name, result }`. A failure is
`plugin_request_failed` with the worker's code in `error.data.requestCode` (`unknown_method`,
`timeout`, ...). `--panel ` sets the caller panel id; `--timeout-ms` the handler's deadline.
## test and check
Both run the plugin's code on this machine, outside Orca's sandbox: only on code you trust.
- `ORCA plugin test [dir] --json` runs every `*.test.ts(x)` (also `.mts`, `.js(x)`, `.mjs`),
skipping `node_modules`, `.orca`, `dist` and dot-folders, with `node:test` or the plugin's own
vitest. Stdout is `{ ok, result: { runner, code, node: 'system' | 'orca', files } }`; the exit
code is the runner's (`plugin_tests_failed`).
- `ORCA plugin check [dir] --json` validates, then renders each components panel once against a
stand-in host with the manifest's capabilities: what it threw (`file:line:col`), layouts Orca
would refuse, props it would drop, and host calls Orca would refuse (`host refused …` warnings,
even when the panel caught the error). With a worker (`main`), it mounts the worker on the same
host first, so the panel's `plugin.request` reaches its `orca.panels.handle` handlers; a worker
that fails to activate is an issue named `worker (): …`. Each result carries a `summary`
of what drew (headings, callouts, empty states, table sizes, the selected tab) and, with
`--json`, the whole `tree`: read them to confirm each scenario shows what it should. Exit `0`,
`1` `plugin_check_failed`, `2` invalid.
The full kit API, generated from this Orca, is in `references/testing.md`.
### Check fixtures
Check renders against an empty host (no agents, no storage) unless the panel has scenarios. Put
them beside its entry (`src/panel.check.ts` for `src/panel.tsx`); check renders the panel once per
scenario, each on a fresh host with the worker, and labels each result with `scenario`:
```ts
import { defineCheck } from 'orca/testing'
export default defineCheck({
empty: {},
busy: {
results: {
'agents.list': {
agents: [
{
terminalId: 't1',
title: 'Claude',
agent: 'claude',
state: 'working',
stateStartedAt: 0
}
]
}
},
settings: { notifyOnBlocked: true },
events: [
{
event: 'agent.status.changed',
payload: {
workspaceId: null,
paneKey: 'p',
terminalId: 't1',
state: 'blocked',
receivedAt: 0
}
}
]
}
})
```
- A scenario takes `mockHost()` options (`results`, `requests`, `storage`, `settings`, `secrets`,
`capabilities`), plus `persisted` and `theme` as `mount()` takes them, and `events` delivered in
order after the first draw. `requests` stubs a name; any other goes to the worker.
- Add one per state worth seeing: empty, busy, an error answer (`hostError(code)` in `results`).
- Orca itself never loads `*.check.ts`; it may import `orca/testing`.
### Panels with orca/testing
Put tests next to the panel (`src/panel.test.tsx`; the components template writes one):
```tsx
import { afterEach, assert, mount, test, type TestPanel } from 'orca/testing'
import * as panelModule from './panel'
let panel: TestPanel | undefined
afterEach(() => panel?.unmount())
test('adds a task', async () => {
panel = await mount(panelModule, { persisted: { plugin: { todos: [] } } })
await panel.type({ label: 'New task' }, 'Ship it', { submit: true })
assert.ok(panel.find({ role: 'button', text: /Ship it/ }))
assert.equal(panel.valueOf({ label: 'New task' }), '')
assert.deepEqual(panel.errors, [])
})
```
- `mount(module, { host, theme, locale, visible, panelId, persisted })` runs `setup`, renders and
resolves once drawn; every mount resets every atom; one panel at a time. `stored(value,
version)` seeds what an older version wrote, to test `migrate`.
- `find` (innermost match or `null`) and `findAll` take `type`, `role`, `text`, `label` or
`testId` (the element's `key`); `text` and `label` match exactly, so use a RegExp for part.
- `press`, `type(el, text, { replace?, submit? })`, `submit`, `toggle`, `select(el, value)` resolve
once renders, host calls and persisted writes settle: `await` them, never sleep. `valueOf`,
`tree()`, `errors`, `warnings`, `persisted` inspect.
- `mockHost({ capabilities, results, requests, storage, settings, secrets })` (pass as `host`)
refuses what Orca refuses: undeclared capabilities, bad params, and `shell.openExternal` or
`files.saveAs` without a `press`. `results` may throw `hostError(code)`; `callsOf(method)` and
`host.data()` read back calls and data. `requests` fakes the worker for `plugin.request`;
`panel.post(event, payload)` is a worker post, `panel.emit` an Orca event.
- `panel.refusals` (and `host.refusals`) lists calls Orca would refuse, with their `code`, even ones
the code caught: assert it is `[]`.
- Mount the module, never call its default export. A control with `value` but no `onChange` is
read-only, so `type`/`toggle` throw on it.
### Workers with orca/testing
`mountWorker(main, { host, events, commands })` calls the module's default-exported
`activate(orca)` with Orca's worker `orca` backed by `mockHost`, loading `.ts` mains as Orca does.
```ts
import { assert, mountWorker, test } from 'orca/testing'
import * as main from './worker'
test('answers the panel and notifies on blocked agents', async () => {
const worker = await mountWorker(main)
assert.deepEqual(await worker.request('todos.list'), [])
await worker.emit('agent.status.changed', {
workspaceId: null,
paneKey: 'tab-1:pane-1',
state: 'blocked',
receivedAt: 1
})
assert.equal(worker.host.callsOf('notifications.show').length, 1)
assert.deepEqual(worker.refusals, [])
await worker.deactivate()
})
```
- Its `activate(orca)` must be the module's default export. Events, commands and capabilities
default to the manifest's (`mountWorker(main, { host, events, commands })` overrides).
- `emit` delivers only events `contributes.events` lists, checks the payload and waits for every
handler. `request(name, input, { panel })` is a panel's `plugin.request` answered by
`orca.panels.handle`; `posts` records `orca.panels.post`; `command(id, args)` runs a registered
command; `logs` holds `orca.log` lines; `refusals` the host calls Orca would refuse (assert `[]`);
`deactivate()` runs the module's `deactivate`.
- Seed storage, settings and secrets with `mockHost({ storage, settings, secrets })` as `{ host }`;
a panel mounted on the same host sees the same data.