How-to guide

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/sdk installed.
npm install @voicelayer/sdk

The pieces

Import everything from @voicelayer/sdk/testing.

ExportWhat 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, manifestIssuesThe manifest builder and its checks, if you need them directly.
HandlerInvocationErrorWhat invoke throws, with a code: not_registered, invalid_args, invalid_result or handler_error.

testContext options

OptionMeaning
callOverride 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.
capabilitiesOverride the channel capabilities (canBargeIn, canReceiveDtmf, and so on)
process{ data, complete } for an agent with a process
metadataThe call's handler state at the start
connectorsStand-ins for connectors
realValuestrue to behave as a handler that is allowed real values
answersask (a string, or a function of the question), memory (what ctx.memory.get reads), memoryFacts (what ctx.memory.search finds; none by default)
refuseMake one call fail like the pool's refusal, for example { handoff: 'guard_denied' }
strictChannelLabelReading ctx.channel.label throws. A handler should branch on capabilities, never on the channel's name.
signalThe call's abort signal

What the context records

PropertyWhat it holds
saidEvery ctx.say text
respondedEvery ctx.respond instruction
handoffs{ to, opts } for each ctx.handoff
endedEach ctx.endCall
eventsEach ctx.recordEvent
dtmfEach ctx.sendDtmf
memoryStoreThe memory map, after the handler wrote to it
actionsEvery 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.

MemberWhat 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 }.
callsThe calls ctx.fetch made: { path, init }
storeThe 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

ProblemFix
the agent serves no tool.xThe id is tool.<name>. The error lists the ids the agent serves.
invalid input for tool.xThe input does not match the tool's input.
the handler asked “…” but the test context has no scripted answerPass answers: { ask: '…' }.
ask isn't available on a text sessionYou set channel: { kind: 'text' }. Use voice, or do not call ask.
the agent serves no brainSet onQuery or brain on the agent.
ctx.fetch … this test gave no fetch stubPass fetch to tester.action.

Next steps

On this page