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 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 in the app

​bun verify.ts

​Preview fixtures

​Validating pieces in isolation

​Testing in the app

​What to test before sharing

`bun verify.ts`

Preview fixtures

Validating pieces in isolation

Testing in the app

What to test before sharing