# Testing agents and channels

> Test tools, hooks, brains and channels as plain functions with @voicelayer/sdk/testing, with no network and no call.

Source: https://docs.vlayers.ai/developers/sdks/testing

Kind: How-to guide

## What you'll build

A test file that checks an agent's manifest, runs its tools and hooks against a fake call, runs a brain for one turn, and parses a channel's events. Nothing here touches the network. The conversation itself runs on VoiceLayer, so for the whole thing end to end use `voicelayer dev` and the Playground: see [Test an agent](https://docs.vlayers.ai/build/testing).

## Prerequisites

- Node.js 22 or later, and a test runner. The example uses [Vitest](https://vitest.dev).
- `@voicelayer/sdk` installed.

```bash
npm install @voicelayer/sdk
```

## The pieces

Import everything from `@voicelayer/sdk/testing`.

| Export | What it does |
|---|---|
| `checkAgent(agent)` | Builds the manifest and runs the upload's own checks, offline. Returns `{ ok, errors, warnings, result }`. |
| `assertAgent(agent)` | The same, and throws with every problem named. Good for a CI test. |
| `testContext(options)` | A fake call context to hand to a handler. It records what the handler did. |
| `invoke(agent, handlerId, input, ctx)` | Runs one handler by id, validating its input the way the runner does. |
| `runBrain(agent, { messages, tools }, { tools, signal })` | Runs the agent's brain (`onQuery` or an adapter) for one turn. Returns `{ text, events, finishReason, error }`. |
| `testChannel(channel, { store })` | Tests a channel: its manifest, `onEvent`, actions and schedules. |
| `buildManifest`, `manifestHash`, `manifestIssues` | The manifest builder and its checks, if you need them directly. |
| `HandlerInvocationError` | What `invoke` throws, with a `code`: `not_registered`, `invalid_args`, `invalid_result` or `handler_error`. |

### `testContext` options

| Option | Meaning |
|---|---|
| `call` | Override `callId`, `callerId` (a placeholder such as `<PII_PHONE_1>` by default), `to`, `startedAt`, `metadata` |
| `channel` | `{ kind: 'voice' \| 'text', label }`. On `text`, `ask`, `sendDtmf`, `handoff` and `watchFormSession` fail with `unsupported_on_channel`, as on a real text session. |
| `capabilities` | Override the channel capabilities (`canBargeIn`, `canReceiveDtmf`, and so on) |
| `process` | `{ data, complete }` for an agent with a process |
| `metadata` | The call's handler state at the start |
| `connectors` | Stand-ins for connectors |
| `realValues` | `true` to behave as a handler that is allowed real values |
| `answers` | `ask` (a string, or a function of the question), `memory` (what `ctx.memory.get` reads), `memoryFacts` (what `ctx.memory.search` finds; none by default) |
| `refuse` | Make one call fail like the pool's refusal, for example `{ handoff: 'guard_denied' }` |
| `strictChannelLabel` | Reading `ctx.channel.label` throws. A handler should branch on `capabilities`, never on the channel's name. |
| `signal` | The call's abort signal |

### What the context records

| Property | What it holds |
|---|---|
| `said` | Every `ctx.say` text |
| `responded` | Every `ctx.respond` instruction |
| `handoffs` | `{ to, opts }` for each `ctx.handoff` |
| `ended` | Each `ctx.endCall` |
| `events` | Each `ctx.recordEvent` |
| `dtmf` | Each `ctx.sendDtmf` |
| `memoryStore` | The memory map, after the handler wrote to it |
| `actions` | Every call in order, with its kind and parameters |
| `statePatch()` | What the handler changed in `ctx.metadata`, as the patch the runner would send |

A handler that calls `ctx.ask` with no scripted `answers.ask` fails the test with a message that says so.

### Handler ids

`tool.<name>` for a tool, `hook.onCallEnd` for the end-of-call hook, `brain.onQuery` for a brain. The error from `invoke` lists the ids the agent serves when you name one it does not.

## A complete test file

Save these two files in one folder. Install Vitest and run `npx vitest run`.

```ts
// front-desk.ts
import { defineAgent, defineTool, deepgram, openai } from '@voicelayer/sdk';

export default defineAgent({
  name: 'front-desk',
  prompt: 'You answer the phone for Harbor Dental. Be brief and friendly.',
  greeting: 'Harbor Dental, how can I help?',
  capabilities: ['system.say', 'system.transfer_call', 'system.memory.read', 'system.memory.write', 'system.record_event'],
  // a transfer's destination must be declared here (or allowed in Settings): `reception` is a route name
  handoff: { fallback: '+14155550000', routes: { reception: '+14155550001' } },
  toolBindings: [],
  models: {
    stt: deepgram.stt({ model: 'nova-3' }),
    llm: openai.llm({ model: 'gpt-4o' }),
    tts: deepgram.tts({ model: 'aura-2-harmonia-en' })
  },
  tools: {
    ...defineTool({
      name: 'book_visit',
      description: 'Book a visit for the caller, or hand them to a person when the day is a Sunday',
      input: { day: 'string' },
      run: async ({ day }, ctx) => {
        if (day.toLowerCase() === 'sunday') {
          await ctx.say('We are closed on Sundays. Let me get a colleague.');
          await ctx.handoff('reception', { reason: 'asked for Sunday' });
          return { booked: false };
        }
        const visits = ((await ctx.memory.get('visits')) as number | undefined) ?? 0;
        await ctx.memory.set('visits', visits + 1);
        ctx.metadata['lastBooking'] = day;
        return { booked: true, day };
      }
    })
  },
  onCallEnd: async (outcome, ctx) => {
    ctx.recordEvent({ kind: 'call_summary', data: { reason: outcome.reason } });
  }
});
```

```ts
// front-desk.test.ts
import { defineAgent } from '@voicelayer/sdk';
import { assertAgent, checkAgent, HandlerInvocationError, invoke, runBrain, testContext } from '@voicelayer/sdk/testing';
import { describe, expect, it } from 'vitest';
import frontDesk from './front-desk.js';

describe('front-desk', () => {
  it('builds and passes the upload checks', () => {
    assertAgent(frontDesk); // throws and names every problem when it does not build
    const check = checkAgent(frontDesk);
    expect(check.ok).toBe(true);
    expect(check.warnings).toEqual([]);
  });

  it('books a weekday, counts the visit and leaves a note for the next handler', async () => {
    const ctx = testContext({ answers: { memory: { visits: 2 } } });
    const result = await invoke(frontDesk, 'tool.book_visit', { day: 'Tuesday' }, ctx);
    expect(result).toEqual({ booked: true, day: 'Tuesday' });
    expect(ctx.memoryStore.get('visits')).toBe(3);
    expect(ctx.statePatch()).toEqual({ lastBooking: 'Tuesday' });
  });

  it('hands a Sunday caller to reception', async () => {
    const ctx = testContext();
    await invoke(frontDesk, 'tool.book_visit', { day: 'Sunday' }, ctx);
    expect(ctx.said).toEqual(['We are closed on Sundays. Let me get a colleague.']);
    expect(ctx.handoffs).toEqual([{ to: 'reception', opts: { reason: 'asked for Sunday' } }]);
  });

  it('shows the refusal a handler gets when the call is not allowed to transfer', async () => {
    const ctx = testContext({ refuse: { handoff: 'guard_denied' } });
    await expect(invoke(frontDesk, 'tool.book_visit', { day: 'Sunday' }, ctx)).rejects.toMatchObject({ code: 'handler_error' });
  });

  it('rejects arguments the tool does not accept', async () => {
    await expect(invoke(frontDesk, 'tool.book_visit', { day: 7 }, testContext())).rejects.toBeInstanceOf(HandlerInvocationError);
  });

  it('records a timeline entry when the call ends', async () => {
    const ctx = testContext();
    await invoke(frontDesk, 'hook.onCallEnd', { outcome: { reason: 'hangup', durationMs: 4_000, processCompleted: false, fieldsCaptured: 0, handoffOccurred: false } }, ctx);
    expect(ctx.events).toEqual([{ kind: 'call_summary', data: { reason: 'hangup' } }]);
  });
});

describe('a brain', () => {
  const brain = defineAgent({
    name: 'opening-hours',
    prompt: 'unused: the brain answers',
    onQuery: async (text) => (text.includes('open') ? 'We open at nine.' : 'Sorry, I do not know.')
  });

  it('answers from the history it is given', async () => {
    const out = await runBrain(brain, { messages: [{ role: 'user', content: 'when do you open?' }] });
    expect(out.text).toBe('We open at nine.');
    expect(out.finishReason).toBe('stop');
    expect(out.error).toBeUndefined();
  });
});
```

The project needs `"type": "module"`. Both files are in the repository under `examples/docs/`, and they run in the SDK's own type check.

For a brain built on an adapter that calls VoiceLayer's tools, pass `{ tools }` as the third argument to stand in for them. Pass `{ signal }` to test a barge-in.

## Test a channel

`testChannel(channel)` returns a tester.

| Member | What it does |
|---|---|
| `manifest(connectorId?)` | The manifest and its `issues`, checked with the schema the API uses at publish |
| `parse(...events)` | Runs `onEvent` for each event. An event is `{ body, kind?, eventId?, contentType? }`; `body` is a string or an object. One result per event: `event`, `ignored` or `mapping_failure`. |
| `action(name, input, { phase, fetch, settings })` | Runs an action's code, or a schedule, with `fetch` as the stand-in for `ctx.fetch`. Returns what it produced: a `prepare`'s slots (checked against their kinds), a `run`'s data, or a schedule's `{ delivered }`. |
| `calls` | The calls `ctx.fetch` made: `{ path, init }` |
| `store` | The in-memory `ctx.store`. Read it to check a cursor. Seed it with `testChannel(channel, { store: { cursor: 40 } })`. |

```ts
// custom-channel.test.ts
import { testChannel } from '@voicelayer/sdk/testing';
import { describe, expect, it } from 'vitest';
import helpdesk from './custom-channel.js'; // the channel from "Build your own channel"

const ticket = { id: 41, subject: 'Refund', body: 'Where is it?', requester: { email: 'sam@example.com', name: 'Sam' } };

describe('helpdesk channel', () => {
  it('builds a manifest the API accepts', () => {
    const { manifest, issues } = testChannel(helpdesk).manifest();
    expect(issues).toEqual([]);
    expect(manifest?.schedules).toEqual([{ name: 'catch_up', everySeconds: 300 }]);
  });

  it('turns a delivered ticket into a message for the agent', async () => {
    const [result] = await testChannel(helpdesk).parse({ body: { ticket } });
    expect(result).toMatchObject({ outcome: 'event', event: { providerId: '41', conversationKey: '41', from: { kind: 'email', address: 'sam@example.com' } } });
  });

  it('ignores a closed ticket, with the reason on the record', async () => {
    const [result] = await testChannel(helpdesk).parse({ body: { ticket: { ...ticket, status: 'closed' } } });
    expect(result).toMatchObject({ outcome: 'ignored', reason: 'closed or empty ticket' });
  });

  it('a body that is not valid JSON is a mapping failure for that event only', async () => {
    const [bad, good] = await testChannel(helpdesk).parse({ body: 'not json' }, { body: { ticket } });
    expect(bad?.outcome).toBe('mapping_failure');
    expect(good?.outcome).toBe('event');
  });

  it('closes a ticket through the one call it declared', async () => {
    const t = testChannel(helpdesk);
    const result = await t.action('closeTicket', { ticketId: 41 }, { fetch: () => ({ ok: true }) });
    expect(result).toEqual({ closed: 41 });
    expect(t.calls).toEqual([{ path: '/api/tickets/41/close', init: { method: 'POST', json: {} } }]);
  });

  it('the catch-up schedule delivers new tickets and moves its cursor', async () => {
    const t = testChannel(helpdesk, { store: { cursor: 40 } });
    const result = await t.action('catch_up', {}, { fetch: () => ({ tickets: [ticket] }) });
    expect(result).toMatchObject({ delivered: [{ providerId: '41' }] });
    expect(await t.store.get('cursor')).toBe(41);
    expect(t.calls[0]?.init.query).toEqual({ since: 40, limit: 25 });
  });
});
```

## Common errors

| Problem | Fix |
|---|---|
| `the agent serves no tool.x` | The id is `tool.<name>`. The error lists the ids the agent serves. |
| `invalid input for tool.x` | The input does not match the tool's `input`. |
| `the handler asked “…” but the test context has no scripted answer` | Pass `answers: { ask: '…' }`. |
| `ask isn't available on a text session` | You set `channel: { kind: 'text' }`. Use voice, or do not call `ask`. |
| `the agent serves no brain` | Set `onQuery` or `brain` on the agent. |
| `ctx.fetch … this test gave no fetch stub` | Pass `fetch` to `tester.action`. |

## Next steps

- [Test an agent](https://docs.vlayers.ai/build/testing): the Playground, simulations and evals.
- [Build your own channel](https://docs.vlayers.ai/developers/sdks/custom-channels)
- [Voice agents in code](https://docs.vlayers.ai/developers/sdks/voice-agents)
- [Testing kit reference](https://docs.vlayers.ai/developers/sdks/reference/testing): signatures, options and errors of every export.
