Testing & debugging

Every scaffolded folder ships with its own test harness. The loop is short:

edit → bun verify.ts → fix → Reload in VoiceOS

`bun verify.ts`

The verifier speaks real MCP over stdio to your server, exactly the way VoiceOS does — no mocks. It re-reads your manifest every run and checks that:

the manifest and preview fixture are schemaVersion: 1;
the MCP handshake succeeds;
the tools your server registers match the manifest exactly, both directions — a drifted name is the classic silent failure;
every tool has a model-facing description worth routing on;
every tool, called with its preview-fixture args, returns text and 1–3 glance blocks.

It exits non-zero on any failure, which makes it the feedback loop for AI coding agents too — AGENTS.md in your folder tells them to run it after every change.

Preview fixtures

voiceos.integration.preview.json holds safe sample inputs per tool:

{
  "schemaVersion": 1,
  "tools": {
    "log_coffee": { "args": { "drink": "flat white" }, "expectedGlanceBlocks": 2 }
  }
}

They’re what verify.ts calls your tools with, and what the Integration Studio uses to preview cards.

Keep fixtures safe to execute. A fixture for an acting tool should point at a harmless target — it will really run.

In the Studio, fixtures self-heal: every real test-drive run overwrites them with what the tool actually returned.

Validating pieces in isolation

From the command line:

bunx @voiceos/integration-sdk validate voiceos.integration.json

In tests, the SDK exports the same validators VoiceOS runs:

import { validateManifest, validateView } from "@voiceos/integration-sdk";

const result = validateManifest(JSON.parse(manifestJson));
if (!result.ok) throw new Error(result.errors.join("\n"));

Errors come back as flat path: message strings — e.g. tools.0.name: tool name must be snake_case starting with a letter.

Testing fast intents

Fast intents need both declaration checks and live Agent Mode checks. verify.ts calls tool handlers; it does not prove that the intent selector will choose them. From a repository checkout:

bun voiceos-integration-sdk/src/cli.ts validate path/to/voiceos.integration.json
bun voiceos-integration-sdk/src/cli.ts intents test "Show Hacker News" --manifest path/to/voiceos.integration.json

Validation checks tool references, slot types, required inputs, language tags, placeholders, and declaration limits. The dry-run prints intent IDs and arguments without executing any tools. It checks exact phrases and static enum templates only; it does not call the live model, extract free text/numeric slots, or fetch valuesFrom: "tool" choices. Use the real app to test those cases. After reloading, test voice and typed commands against safe data:

Case	What to check
Clear request	Correct tool and arguments; expected result card.
Paraphrase	Meaning is understood even when the wording differs from an example.
Missing input, negation, or ambiguous name	No unintended action; the normal agent can clarify or handle the request.
Confirmation edit or cancellation	Edited arguments are validated; cancellation runs no action.
Changed live choices	New names work after the MCP update; removed names cannot execute from a stale proposal.
Empty or invalid live choices	The affected intent is omitted; it does not become an unrestricted string slot.
Handler failure	Failure is reported honestly, without a premature success acknowledgement or automatic duplicate write.

A working tool call alone does not prove the fast path won. If you operate a VoiceOS development server, inspect its intent selection/race telemetry and shadow-mode evaluation. A supporting desktop and an enabled server rollout are required for fast dispatch; shadow mode evaluates without dispatching the selected intent. Do not use offline matches as a latency or accuracy benchmark.

Testing in the app

Install from folder

Settings → Agent Mode → Integrations → Install from folder, then talk to the agent.

Reload after edits

Hit the integration’s Reload — it re-reads the manifest and restarts your server. Tools update on the next turn.

Read the logs

Your server’s stderr is the diagnostic channel. VoiceOS captures it and the integration’s log view shows it. console.error freely — but never log secrets.

Test-drive in the Studio

For anything opened in the Studio: real scoped agent turns against your draft. Click any tool row to stage its card, and fill Required fields to test key-gated paths.


The unhappy paths	Missing API key — does your error say where to get one? The external API down. Empty results — an honest empty card beats a blank one.
Card budgets	Over-cap strings and off-schema blocks are silently dropped at render time. `verify.ts` plus a real install is how you catch a card that quietly lost a block.
Confirmation edits	Approve an acting tool after editing its arguments. Your handler should honor the edited values.
A cold start	Delete `node_modules`, reinstall from the folder. That’s the experience anyone you share it with gets.

Get started

Building blocks

Custom widgets

Ship it

Reference

`bun verify.ts`

Preview fixtures

Validating pieces in isolation

Testing fast intents

Testing in the app

​bun verify.ts

​Preview fixtures

​Validating pieces in isolation

​Testing fast intents

​Testing in the app

​What to test before sharing

`bun verify.ts`

Preview fixtures

Validating pieces in isolation

Testing fast intents

Testing in the app

What to test before sharing