> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing & debugging

> Verify like VoiceOS does — before your users do.

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

```text theme={null}
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:

```json theme={null}
{
  "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.

> [!WARNING]
>
> 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:

```bash theme={null}
bunx @voiceos/integration-sdk validate voiceos.integration.json
```

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

```ts theme={null}
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](https://docs.voiceos.com/integrations/intents.md) 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:

```bash theme={null}
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

**1. Install from folder**

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

**2. Reload after edits**

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

**3. 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.

**4. Test-drive in the Studio**

For anything opened in the [Studio](https://docs.voiceos.com/integrations/build-with-ai.md): real scoped
agent turns against your draft. Click any tool row to stage its card, and fill
**Required fields** to test key-gated paths.

## What to test before sharing

| | |
| - | - |
| **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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.