# The testing kit

> Reference for testContext, invoke, checkAgent, assertAgent, runBrain and testChannel from @voicelayer/sdk/testing.

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

Kind: Reference

The testing kit runs your handlers, brains and channels as plain functions, with no network and no call.

Import from `@voicelayer/sdk/testing`. For a walk-through, see [Testing agents and channels](https://docs.vlayers.ai/developers/sdks/testing).

### testContext

function · `import { testContext } from '@voicelayer/sdk/testing'`

```ts
testContext(opts?: TestContextOptions): TestContext
```

Build a test context. It makes no network calls.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `opts` | `TestContextOptions` | no | The call, channel, scripted answers and refusals. |

##### Returns

`TestContext`: A `TestContext`.

##### Example

```ts
import { testContext } from '@voicelayer/sdk/testing';

const ctx = testContext({ answers: { ask: 'jane@example.com' } });
```

### TestContextOptions

interface · `import { TestContextOptions } from '@voicelayer/sdk/testing'`

```ts
interface TestContextOptions
```

How to set up a test context: the call, the channel, the captured process data, scripted answers, and which calls to refuse.

#### Fields

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `call` | `object` | no |  | Fields of `ctx.call` to override. The defaults are a fixed call id, a placeholder caller, a fixed number and a fixed start time. |
| `call.metadata` | `Readonly<Record<string, unknown>>` | no |  | The metadata the call was started with, read only. To keep state across handlers, use `ctx.metadata`. |
| `call.callId` | `string` | no |  | The call's id, the same one the dashboard and the API show. |
| `call.callerId` | `string` | no |  | The caller's number (a placeholder like `<PII_PHONE_1>` unless real values were released to this handler). |
| `call.to` | `string \| null` | no |  | The number that was called. |
| `call.startedAt` | `Date` | no |  | When the call started. |
| `language` | `string` | no | `'en-US'` | The call's language (`ctx.language`). |
| `channel` | `object` | no |  | Whether the conversation is `voice` (the default) or `text`, and its display label. |
| `channel.kind` | `ChannelKind` | no | `'voice'` | `voice` or `text`. One of `voice`, `text`. |
| `channel.label` | `string` | no | `'phone' for voice, 'web' for text` | The display label. |
| `capabilities` | `Partial<WorkerCapabilities>` | no |  | Overrides for `ctx.capabilities`. |
| `process` | `object` | no |  | What `ctx.process` holds: the captured `data` and whether the process is `complete`. |
| `process.data` | `Record<string, unknown>` | no |  | The captured fields. |
| `process.complete` | `boolean` | no | `false` | Whether the process is complete. |
| `metadata` | `Record<string, unknown>` | no |  | The starting value of `ctx.metadata`, as the invocation would carry it. |
| `connectors` | `Record<string, unknown>` | no |  | The value of `ctx.connectors`. |
| `realValues` | `boolean` | no | `false` | The value of `ctx.realValues`. |
| `answers` | `object` | no |  | Scripted answers: `ask` (a string, or a function of the question), `memory` (the store `memory.get` reads) and `memoryFacts` (what `memory.search` finds; none by default, as for a version without the memory opt-in). |
| `answers.ask` | `string \| ((question: string) => string)` | no |  | The answer to `ctx.ask`: a string, or a function of the question. Without one, `ask` fails the test. |
| `answers.memory` | `Record<string, unknown>` | no |  | The starting contents of the store `memory.get` reads. |
| `answers.memoryFacts` | `Awaited<ReturnType<HandlerContext['memory']['search']>>['facts']` | no |  | What `memory.search` finds. |
| `refuse` | `Partial<Record<RecordedAction['kind'], string>>` | no |  | Make a call reject as the platform would, by call kind and code, for example `{ handoff: 'guard_denied' }`. |
| `strictChannelLabel` | `boolean` | no | `false` | Make reading `ctx.channel.label` throw, to catch a handler that branches on the label instead of on `capabilities`. |
| `signal` | `AbortSignal` | no |  | The value of `ctx.signal`. |

### TestContext

interface · `import { TestContext } from '@voicelayer/sdk/testing'`

```ts
interface TestContext extends HandlerContext
```

A `HandlerContext` for tests. Its calls record what the handler asked for and return the scripted answers, so you can assert on `said`, `handoffs` and the rest.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `actions` | `readonly RecordedAction[]` | yes | Every call, in order. |
| `said` | `readonly string[]` | yes | The text passed to `say`. |
| `responded` | `readonly string[]` | yes | The instructions passed to `respond`. |
| `handoffs` | `object[]` | yes | Each `handoff`, with its destination and options. |
| `handoffs.to` | `string` | yes | The destination passed to `handoff`. |
| `handoffs.opts` | `HandoffOptions \| undefined` | yes | The options passed to `handoff`. |
| `ended` | `object[]` | yes | Each `endCall`, with its reason. |
| `ended.reason` | `string` | no | The reason passed to `endCall`. |
| `events` | `readonly RecordEventInput[]` | yes | Each event passed to `recordEvent`. |
| `dtmf` | `readonly string[]` | yes | The digits passed to `sendDtmf`. |
| `memoryStore` | `ReadonlyMap<string, unknown>` | yes | What `memory.set` stored. |

#### statePatch

```ts
statePatch(): Record<string, unknown> | undefined
```

Everything the handler changed in `ctx.metadata` since the context was built, as the merge patch the platform would receive. `undefined` when nothing changed.

##### Returns

`Record<string, unknown> | undefined`

### RecordedAction

interface · `import { RecordedAction } from '@voicelayer/sdk/testing'`

```ts
interface RecordedAction
```

One call a handler made back to the platform, in order.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `kind` | `'say' \| 'respond' \| 'ask' \| 'handoff' \| 'endCall' \| 'recordEvent' \| 'memory.get' \| 'memory.set' \| 'memory.search' \| 'sendDtmf' \| 'watchFormSession' \| 'unwatchFormSession'` | yes | Which call it was: `say`, `respond`, `ask`, `handoff`, `endCall`, `recordEvent`, `memory.get`, `memory.set`, `memory.search`, `sendDtmf`, `watchFormSession` or `unwatchFormSession`. |
| `params` | `Record<string, unknown>` | yes | The arguments the handler passed. |

### invoke

function · `import { invoke } from '@voicelayer/sdk/testing'`

```ts
invoke(agent: AgentHandle | BuildResult, handlerId: string, input?: unknown, ctx?: HandlerContext): Promise<unknown>
```

Run one handler by id as the runner would. `input` is a tool's arguments or a hook's payload. Arguments are validated as the runner validates them, a blocking handler's value is checked against its result shape, and the handler's own error is rethrown as a `HandlerInvocationError`.

##### Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `agent` | `AgentHandle \| BuildResult` | yes |  | The agent, or a built manifest. |
| `handlerId` | `string` | yes |  | The handler to run, such as `tool.lookup_order`. |
| `input` | `unknown` | no |  | The tool's arguments or the hook's payload. |
| `ctx` | `HandlerContext` | no | `testContext()` | The context to run with. |

##### Returns

`Promise<unknown>`: What the handler returned.

##### Throws

- HandlerInvocationError when the handler is not served, the input is invalid, the result has the wrong shape, or the handler throws.

##### Example

```ts
const ctx = testContext();
const result = await invoke(agent, 'tool.lookup_order', { orderId: '42' }, ctx);
expect(result).toMatchObject({ status: 'shipped' });
```

### HandlerInvocationError

class · `import { HandlerInvocationError } from '@voicelayer/sdk/testing'`

```ts
class HandlerInvocationError extends Error
```

A handler's problem as a test sees it: the error the platform would have replied with. `code` is `not_registered` (no such handler), `invalid_args` (the input does not match), `invalid_result` (a blocking handler's result is the wrong shape) or `handler_error` (the handler threw).

```ts
new HandlerInvocationError(code: 'not_registered' | 'invalid_args' | 'invalid_result' | 'handler_error', message: string, cause?: unknown)
```

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `code` | `'not_registered' \| 'invalid_args' \| 'invalid_result' \| 'handler_error'` | yes | Which problem it was. |
| `cause` | `unknown` | no | The error the handler threw, for `handler_error`. |

### checkAgent

function · `import { checkAgent } from '@voicelayer/sdk/testing'`

```ts
checkAgent(agent: AgentHandle | Parameters<typeof buildManifest>[0], opts?: BuildOptions): AgentCheck
```

Build the manifest and run the upload's own lint offline. `ok` is false for an unsupported field, a secret or a bad handler declaration: the same findings `voicelayer manifest --check` and the upload make.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | `AgentHandle \| Parameters<typeof buildManifest>[0]` | yes | The agent, or its config. |
| `opts` | `BuildOptions` | no | Build options. |

##### Returns

`AgentCheck`: The errors, warnings and build result.

### assertAgent

function · `import { assertAgent } from '@voicelayer/sdk/testing'`

```ts
assertAgent(agent: AgentHandle | Parameters<typeof buildManifest>[0], opts?: BuildOptions): BuildResult
```

Throw with every finding named when the agent does not build. For a CI test.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | `AgentHandle \| Parameters<typeof buildManifest>[0]` | yes | The agent, or its config. |
| `opts` | `BuildOptions` | no | Build options. |

##### Returns

`BuildResult`: The build result.

##### Throws

- Error listing each error when the agent does not build.

##### Example

```ts
import { assertAgent } from '@voicelayer/sdk/testing';

it('builds', () => {
  assertAgent(agent);
});
```

### AgentCheck

interface · `import { AgentCheck } from '@voicelayer/sdk/testing'`

```ts
interface AgentCheck
```

The outcome of `checkAgent`.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `ok` | `boolean` | yes | True when the agent has no errors. |
| `errors` | `readonly BuildIssue[]` | yes | Findings that block an upload. |
| `warnings` | `readonly BuildIssue[]` | yes | Findings that do not block an upload. |
| `result` | `BuildResult` | yes | The full build result. |

### buildManifest

function · `import { buildManifest } from '@voicelayer/sdk/testing'`

```ts
buildManifest(config: AgentConfig<Record<string, ProcessField>> | Readonly<Record<string, unknown>>, opts?: BuildOptions): BuildResult
```

Build an agent's manifest, handler table and issues from its config, without running anything. Accepts an `AgentConfig` or any config object, so a JavaScript author or an older config is checked too.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `config` | `AgentConfig<Record<string, ProcessField>> \| Readonly<Record<string, unknown>>` | yes | The agent's config. |
| `opts` | `BuildOptions` | no | Build options. |

##### Returns

`BuildResult`: The manifest, table, hash and issues.

### BuildOptions

interface · `import { BuildOptions } from '@voicelayer/sdk/testing'`

```ts
interface BuildOptions
```

Options for building a manifest.

#### Fields

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `textAnsweredBy` | `'direct'` | no |  | Set to `direct` when the agent has `onMessage`: its own process answers text through the API. |
| `build` | `string` | no | `'local'` | The deploy identity. A fresh one per deploy makes every deploy a new hash. |

### BuildResult

interface · `import { BuildResult } from '@voicelayer/sdk/testing'`

```ts
interface BuildResult
```

What building an agent produces.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `manifest` | `AgentManifestInput` | yes | The manifest that would be uploaded. |
| `table` | `HandlerTable` | yes | The handlers the agent serves, by id. |
| `hash` | `string` | yes | The manifest's hash, which the platform pins and retires builds by. |
| `issues` | `readonly BuildIssue[]` | yes | Errors and warnings. The manifest may be uploaded only when none is an error. |
| `ok` | `boolean` | yes | True when there are no errors. |

### BuildIssue

interface · `import { BuildIssue } from '@voicelayer/sdk/testing'`

```ts
interface BuildIssue
```

A problem found when building an agent's manifest.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `severity` | `'error' \| 'warning'` | yes | `error` blocks an upload; `warning` does not. |
| `code` | `ManifestIssueCode \| BuildOnlyIssueCode` | yes | A stable code naming the problem. |
| `path` | `string` | yes | Where in the config (or the manifest) the problem is, as a dotted path. |
| `message` | `string` | yes | What is wrong and how to fix it. |

### runBrain

function · `import { runBrain } from '@voicelayer/sdk/testing'`

```ts
runBrain(agent: AgentHandle | BuildResult, turn: { messages, tools? }, opts?: { tools?, signal? }): Promise<BrainTurnResult>
```

Run the agent's brain (`onQuery` or an adapter's handler) for one turn, as the runner would: no network, the turn's history in, the deltas out.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `agent` | `AgentHandle \| BuildResult` | yes | The agent, or a built manifest. |
| `turn` | `object` | yes | The conversation so far, and the tools the request carries. |
| `turn.messages` | `ReadonlyArray<{ readonly role: string; readonly content: string }>` | yes | The conversation so far, oldest first. |
| `turn.tools` | `ReadonlyArray<Record<string, unknown>>` | no | Tool definitions the request carries. |
| `opts` | `object` | no | `tools` stands in for VoiceLayer's tools (what an adapter's tool bodies call); `signal` is the turn's abort, as for a barge-in. |
| `opts.tools` | `BrainToolCaller` | no | A stand-in for VoiceLayer's tools. |
| `opts.signal` | `AbortSignal` | no | The turn's abort signal. |

##### Returns

`Promise<BrainTurnResult>`: The text, events, finish reason and error.

##### Throws

- HandlerInvocationError with code `not_registered` when the agent serves no brain.

##### Example

```ts
const out = await runBrain(agent, { messages: [{ role: 'user', content: 'what time do you open?' }] });
expect(out.text).toContain('9');
```

### BrainTurnResult

interface · `import { BrainTurnResult } from '@voicelayer/sdk/testing'`

```ts
interface BrainTurnResult
```

What a brain produced for one turn.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `text` | `string` | yes | Every text delta, joined. |
| `events` | `readonly BrainTurnEvent[]` | yes | Every event the brain yielded. |
| `finishReason` | `string \| undefined` | yes | The finish reason of the `done` event (`stop` when the handler just ended). `undefined` after an error. |
| `error` | `object` | yes | The error the brain reported, if any. |
| `error.code` | `string` | yes | The error code. |
| `error.message` | `string` | yes | The error message. |

### testChannel

function · `import { testChannel } from '@voicelayer/sdk/testing'`

```ts
testChannel(channel: ChannelHandle, options?: TestChannelOptions): ChannelTester
```

Build a tester for a channel, with no network.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `channel` | `ChannelHandle` | yes | The channel from `defineChannel`. |
| `options` | `TestChannelOptions` | no | The starting store. |

##### Returns

`ChannelTester`: The tester.

##### Example

```ts
import { testChannel } from '@voicelayer/sdk/testing';

const t = testChannel(channel);
expect(t.manifest().issues).toEqual([]);
const [r] = await t.parse({ kind: 'message', body: JSON.stringify(update) });
expect(r.outcome).toBe('event');
```

### TestChannelOptions

interface · `import { TestChannelOptions } from '@voicelayer/sdk/channel'`

```ts
interface TestChannelOptions
```

Options for `testChannel`.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `store` | `Readonly<Record<string, unknown>>` | no | What `ctx.store` holds when the test starts. It lives for the tester, so a cursor one run keeps is there for the next. |

### ChannelTester

interface · `import { ChannelTester } from '@voicelayer/sdk/channel'`

```ts
interface ChannelTester
```

Runs a channel offline: check the manifest, parse events, run actions with a stubbed provider.

#### Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `calls` | `object[]` | yes | The provider calls `ctx.fetch` made, in order. |
| `calls.path` | `string` | yes | The path passed to `ctx.fetch`. |
| `calls.init` | `ChannelFetchInit` | yes | The options passed to `ctx.fetch`. |
| `store` | `ChannelStore & { readonly entries: ReadonlyMap<string, unknown> }` | yes | The connection's store for this tester. Read it to check a cursor. |

#### manifest

```ts
manifest(connectorId?: string): { readonly manifest: { channels: string[]; id: string; displayName: string; inbound: { verification: { scheme: "slack_v0"; toleranceSec: number; } | { scheme: "meta_hmac_sha256"; } | { scheme: "twilio_hmac_sha1"; } | { scheme: "ed25519"; toleranceSec: number; signatureHeader: string; timestampHeader: string; } | { scheme: "secret_token_header"; header: string; }; events: { kind: string; id: { path: string; from: "json"; } | { name: string; from: "header"; }; items?: string | undefined; lane?: string | undefined; }[]; ack: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; } | { type: "echo_query"; param: string; } | { path: string; type: "echo_json"; as: { format: "text"; } | { format: "json"; key: string; }; } | { path: string; type: "typed"; cases: Record<string, { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }>; fallback: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }; }; handshakes: { name: string; when: { method: "GET" | "POST"; query?: { param: string; equals?: string | undefined; } | undefined; json?: { path: string; equals: string | number | boolean; } | undefined; }; authentication: { by: "signature"; } | { by: "token"; queryParam: string; }; reply: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; } | { type: "echo_query"; param: string; } | { path: string; type: "echo_json"; as: { format: "text"; } | { format: "json"; key: string; }; } | { path: string; type: "typed"; cases: Record<string, { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }>; fallback: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }; }; }[]; attribution: { from: "path"; } | { path: string; from: "body"; } | { name: string; from: "header"; }; }; egressHosts: string[]; api?: { host: string; calls: (string | { call: string; query?: string[] | undefined; })[]; } | undefined; sends?: { operations: Partial<Record<"send.text" | "reply.in_window" | "send.media", { path: string; method: "POST" | "PUT" | "PATCH"; recipients: string[]; messageId: string; query?: Record<string, string> | undefined; headers?: Record<string, string> | undefined; body?: { kind: "json"; template: Record<string, unknown>; } | { kind: "form"; fields: Record<string, string>; } | undefined; address?: "peer" | "answered" | undefined; }>>; } | undefined; live?: { events: string[]; protocol: "discord_gateway"; intents: number; } | { protocol: "slack_socket"; } | { protocol: "imap"; mailbox: string; } | undefined; actions?: Record<string, { kind: "send"; sends: number; send: { path: string; method: "POST" | "PUT" | "PATCH"; recipients: string[]; messageId: string; query?: Record<string, string> | undefined; headers?: Record<string, string> | undefined; body?: { kind: "json"; template: Record<string, unknown>; } | { kind: "form"; fields: Record<string, string>; } | undefined; address?: "peer" | "answered" | undefined; }; hasPrepare: boolean; describe: string; forAgent: boolean; input?: Record<string, "string" | "number" | "boolean" | "text" | "url"> | undefined; slots?: Record<string, "digits" | "uuid" | "hex"> | undefined; } | { kind: "code"; describe: string; forAgent: boolean; access: "read" | "write"; input?: Record<string, "string" | "number" | "boolean" | "text" | "url"> | undefined; }> | undefined; schedules?: { name: string; everySeconds: number; }[] | undefined; store?: boolean | undefined; } | undefined; readonly issues: readonly ChannelIssue[]; }
```

The manifest for `ws/test/<name>` (or the id you pass), with its issues.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `connectorId` | `string` | no | A connector id to build for. |

##### Returns

`{ readonly manifest: { channels: string[]; id: string; displayName: string; inbound: { verification: { scheme: "slack_v0"; toleranceSec: number; } | { scheme: "meta_hmac_sha256"; } | { scheme: "twilio_hmac_sha1"; } | { scheme: "ed25519"; toleranceSec: number; signatureHeader: string; timestampHeader: string; } | { scheme: "secret_token_header"; header: string; }; events: { kind: string; id: { path: string; from: "json"; } | { name: string; from: "header"; }; items?: string | undefined; lane?: string | undefined; }[]; ack: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; } | { type: "echo_query"; param: string; } | { path: string; type: "echo_json"; as: { format: "text"; } | { format: "json"; key: string; }; } | { path: string; type: "typed"; cases: Record<string, { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }>; fallback: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }; }; handshakes: { name: string; when: { method: "GET" | "POST"; query?: { param: string; equals?: string | undefined; } | undefined; json?: { path: string; equals: string | number | boolean; } | undefined; }; authentication: { by: "signature"; } | { by: "token"; queryParam: string; }; reply: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; } | { type: "echo_query"; param: string; } | { path: string; type: "echo_json"; as: { format: "text"; } | { format: "json"; key: string; }; } | { path: string; type: "typed"; cases: Record<string, { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }>; fallback: { type: "fixed"; status: number; body: string; contentType: "text/plain" | "application/json" | "text/xml"; }; }; }[]; attribution: { from: "path"; } | { path: string; from: "body"; } | { name: string; from: "header"; }; }; egressHosts: string[]; api?: { host: string; calls: (string | { call: string; query?: string[] | undefined; })[]; } | undefined; sends?: { operations: Partial<Record<"send.text" | "reply.in_window" | "send.media", { path: string; method: "POST" | "PUT" | "PATCH"; recipients: string[]; messageId: string; query?: Record<string, string> | undefined; headers?: Record<string, string> | undefined; body?: { kind: "json"; template: Record<string, unknown>; } | { kind: "form"; fields: Record<string, string>; } | undefined; address?: "peer" | "answered" | undefined; }>>; } | undefined; live?: { events: string[]; protocol: "discord_gateway"; intents: number; } | { protocol: "slack_socket"; } | { protocol: "imap"; mailbox: string; } | undefined; actions?: Record<string, { kind: "send"; sends: number; send: { path: string; method: "POST" | "PUT" | "PATCH"; recipients: string[]; messageId: string; query?: Record<string, string> | undefined; headers?: Record<string, string> | undefined; body?: { kind: "json"; template: Record<string, unknown>; } | { kind: "form"; fields: Record<string, string>; } | undefined; address?: "peer" | "answered" | undefined; }; hasPrepare: boolean; describe: string; forAgent: boolean; input?: Record<string, "string" | "number" | "boolean" | "text" | "url"> | undefined; slots?: Record<string, "digits" | "uuid" | "hex"> | undefined; } | { kind: "code"; describe: string; forAgent: boolean; access: "read" | "write"; input?: Record<string, "string" | "number" | "boolean" | "text" | "url"> | undefined; }> | undefined; schedules?: { name: string; everySeconds: number; }[] | undefined; store?: boolean | undefined; } | undefined; readonly issues: readonly ChannelIssue[]; }`

#### parse

```ts
parse(events?: TestRawEvent[]): Promise<({ eventId: string; outcome: "event"; event: { kind: "message"; from: { kind: AnyIdentifierKind; address: string; displayName?: string | undefined; }; channel: string; providerId: string; conversationKey: string; content: ({ text: string; kind: "text"; } | { kind: "media"; locator: string; format?: string | undefined; })[]; replyTo?: string | undefined; threadKey?: string | undefined; replyContext?: Record<string, unknown> | undefined; providerMetadata?: Record<string, unknown> | undefined; surface?: Record<string, unknown> | undefined; context?: string | undefined; occurredAt?: number | undefined; } | { status: "read" | "sent" | "delivered" | "failed"; kind: "status"; channel: string; providerId: string; at?: number | undefined; errorCode?: string | undefined; error?: string | undefined; metadata?: Record<string, unknown> | undefined; errors?: { code: string; message?: string | undefined; }[] | undefined; correlationTag?: string | undefined; } | { kind: "reaction"; from: { kind: AnyIdentifierKind; address: string; displayName?: string | undefined; }; channel: string; providerId: string; targetProviderId: string; emoji: string; removed: boolean; }; } | { eventId: string; outcome: "mapping_failure"; failure: { reason: string; providerId?: string | undefined; }; } | { eventId: string; outcome: "ignored"; reason: string; })[]>
```

Run the channel's `onEvent` on these events. Results are validated strictly, as the platform validates them.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `events` | `TestRawEvent[]` | no | The raw events to parse. |

##### Returns

`Promise<({ eventId: string; outcome: "event"; event: { kind: "message"; from: { kind: AnyIdentifierKind; address: string; displayName?: string | undefined; }; channel: string; providerId: string; conversationKey: string; content: ({ text: string; kind: "text"; } | { kind: "media"; locator: string; format?: string | undefined; })[]; replyTo?: string | undefined; threadKey?: string | undefined; replyContext?: Record<string, unknown> | undefined; providerMetadata?: Record<string, unknown> | undefined; surface?: Record<string, unknown> | undefined; context?: string | undefined; occurredAt?: number | undefined; } | { status: "read" | "sent" | "delivered" | "failed"; kind: "status"; channel: string; providerId: string; at?: number | undefined; errorCode?: string | undefined; error?: string | undefined; metadata?: Record<string, unknown> | undefined; errors?: { code: string; message?: string | undefined; }[] | undefined; correlationTag?: string | undefined; } | { kind: "reaction"; from: { kind: AnyIdentifierKind; address: string; displayName?: string | undefined; }; channel: string; providerId: string; targetProviderId: string; emoji: string; removed: boolean; }; } | { eventId: string; outcome: "mapping_failure"; failure: { reason: string; providerId?: string | undefined; }; } | { eventId: string; outcome: "ignored"; reason: string; })[]>`

#### action

```ts
action(name: string, input?: Record<string, unknown>, opts?: TestActionOptions): Promise<unknown>
```

Run an action's code and return what it produced: a prepare's slots (a sentence in a `digits` slot rejects with `slot_invalid`), a run's or a control's data, or a schedule's `{ delivered }`.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The action's name. |
| `input` | `Record<string, unknown>` | no | The action's input. |
| `opts` | `TestActionOptions` | no | The phase, a stub for `ctx.fetch` and the settings. |

##### Returns

`Promise<unknown>`: What the action produced.

##### Throws

- ChannelActionError when the action is refused, for example `slot_invalid`.

### TestActionOptions

interface · `import { TestActionOptions } from '@voicelayer/sdk/channel'`

```ts
interface TestActionOptions
```

Options for running a channel action in a test.

#### Fields

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `phase` | `ChannelActionPhase` | no | `'prepare' for a send action, 'run' for a code action for the agent, else 'control'` | Which step to run. One of `schedule`, `prepare`, `run`, `control`. |
| `fetch` | `(path: string, init: ChannelFetchInit) => unknown \| Promise<unknown>` | no |  | What `ctx.fetch` answers. Without it, a call to `ctx.fetch` fails the action. |
| `settings` | `Record<string, unknown>` | no |  | The connection's saved settings. |

### TestRawEvent

interface · `import { TestRawEvent } from '@voicelayer/sdk/channel'`

```ts
interface TestRawEvent
```

A raw webhook event to feed a channel's `onEvent` in a test.

#### Fields

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `body` | `string \| Record<string, unknown>` | yes |  | The event body: a string, or an object that is JSON-encoded. |
| `kind` | `string` | no | `the first declared` | One of the declaration's event kinds. |
| `eventId` | `string` | no |  | The provider's event id. |
| `contentType` | `ChannelRawEvent['contentType']` | no |  | The body's content type. |
