Testing agents and channels
Test tools, hooks, brains and channels as plain functions with @voicelayer/sdk/testing, with no network and no call.
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.
Prerequisites
- Node.js 22 or later, and a test runner. The example uses Vitest.
@voicelayer/sdkinstalled.
npm install @voicelayer/sdkThe 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.
// 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 } });
}
});// 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 } }). |
// 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: '[email protected]', 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: '[email protected]' } } });
});
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: the Playground, simulations and evals.
- Build your own channel
- Voice agents in code
- Testing kit reference: signatures, options and errors of every export.