> ## Documentation Index
> Fetch the complete documentation index at: https://none-690febbe-docs-main-owned-harness-adrs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# protocol/testing

> Public barrel for protocol testing utilities.

# protocol/testing

*`packages/protocol/src/testing`*

## Purpose

Public barrel for protocol testing utilities.

`@moltzap/protocol/testing` — test fixtures, typed lifecycle clients,
arbitrary derivation, and Toxiproxy adversity helpers.

## Public surface

### [`agentId`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L89)

*Function*

```ts theme={null}
export const agentId = (
  value: string,
): Schema.Schema.Type<typeof agentIdSchema>
```

Validates and decodes agent id values.

**Returns:** The agent id result.

### [`agentKeyArbitrary`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L139)

*Variable*

```ts theme={null}
export const agentKeyArbitrary: FastCheck.Arbitrary<AgentKey> =
  agentKeyStringArbitrary.map(redactedAgentKey)
```

Provides the agent key arbitrary runtime value.

### [`agentKeyString`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L146)

*Function*

```ts theme={null}
export const agentKeyString = (seed: number): string
```

Provides the agent key string runtime value.

**Returns:** The agent key string result.

### [`agentKeyStringArbitrary`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L126)

*Variable*

```ts theme={null}
export const agentKeyStringArbitrary: FastCheck.Arbitrary<string> =
  FastCheck.tuple(
    hexStringArbitrary(KEY_ID_HEX_CHARS),
    hexStringArbitrary(SECRET_HEX_CHARS),
  ).map(([keyId, secret]) => `${AGENT_KEY_PREFIX}${keyId}_${secret}`)
```

Provides the agent key string arbitrary runtime value.

### [`agentName`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L98)

*Function*

```ts theme={null}
export const agentName = (
  value: string,
): Schema.Schema.Type<typeof agentNameSchema>
```

Validates and decodes agent name values.

**Returns:** The agent name result.

### [`AgentRegistrationError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L188)

*Class*

```ts theme={null}
export class AgentRegistrationError extends Data.TaggedError(
  "TestingAgentRegistrationError",
)<{
  readonly baseUrl: string;
  readonly agentName: string;
  readonly status: number;
  readonly body: string;
}> {}
```

HTTP registration failed (network, non-2xx, malformed response).

### [`connectionId`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L154)

*Variable*

```ts theme={null}
export const connectionId = decodeConnectionId
```

Provides the connection id runtime value.

### [`conversationId`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L107)

*Function*

```ts theme={null}
export const conversationId = (
  value: string,
): Schema.Schema.Type<typeof conversationIdSchema>
```

Validates and decodes conversation id values.

**Returns:** The conversation id result.

### [`makeTestAgentClient`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/lifecycle.ts#L158)

*Function*

```ts theme={null}
export function makeTestAgentClient(
  agentId: AgentId,
  options: AgentClientOptions,
): Effect.Effect<TestAgentClient, unknown>
```

Creates test agent client.

**Returns:** The created test agent client.

### [`messageId`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L116)

*Function*

```ts theme={null}
export const messageId = (
  value: string,
): Schema.Schema.Type<typeof messageIdSchema>
```

Validates and decodes message id values.

**Returns:** The message id result.

### [`RealServerAcquireError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/errors.ts#L45)

*Class*

```ts theme={null}
export class RealServerAcquireError extends Data.TaggedError(
  "TestingRealServerAcquireError",
)<{
  readonly cause: unknown;
}> {
  override get message(): string {
    return this.cause instanceof Error
      ? this.cause.message
      : String(this.cause);
  }
}
```

Consumer-supplied real-server factory threw or returned an unusable handle.

### [`redactedAgentKey`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L136)

*Function*

```ts theme={null}
export const redactedAgentKey = (value: string): AgentKey
```

Validates and decodes redacted agent key values.

**Returns:** The redacted agent key result.

### [`registerTestAgent`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L278)

*Function*

```ts theme={null}
export function registerTestAgent(
  opts: RegisterTestAgentOptions,
): Effect.Effect<TestAgent, AgentRegistrationError>
```

Registers test agent.

**Returns:** The register test agent result.

### [`RpcResponseError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/errors.ts#L34)

*Class*

```ts theme={null}
export class RpcResponseError extends Data.TaggedError(
  "TestingRpcResponseError",
)<{
  readonly method: string;
  readonly requestId: string;
  readonly tag: string;
  readonly message: string;
  readonly data?: unknown;
}> {}
```

Server returned a typed error for a request.

### [`RpcTimeoutError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/errors.ts#L25)

*Class*

```ts theme={null}
export class RpcTimeoutError extends Data.TaggedError(
  "TestingRpcTimeoutError",
)<{
  readonly method: string;
  readonly requestId: string;
  readonly timeoutMs: number;
}> {}
```

Wall-clock deadline for a request expired before a response.

### [`TestAgent`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L164)

*Interface*

```ts theme={null}
export interface TestAgent {
  readonly agentId: Schema.Schema.Type<typeof agentIdSchema>;
  readonly apiKey: AgentKey;
  readonly name: string;
}
```

Describes test agent.

### [`TestAgentClient`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/lifecycle.ts#L42)

*Interface*

```ts theme={null}
export interface TestAgentClient {
  readonly principal: "agent";
  readonly agentId?: AgentId;
  close(): Effect.Effect<void>;
  subscribe<D extends AnyNotificationDefinition>(
    definition: D,
    refinement?: (params: NotificationParamsOf<D>) => boolean,
  ): Stream.Stream<NotificationParamsOf<D>, NotConnectedError>;
  subscribeAll(
    refinement?: (
      delivery: NotificationDelivery<AnyNotificationDefinition>,
    ) => boolean,
  ): Stream.Stream<
    NotificationDelivery<AnyNotificationDefinition>,
    NotConnectedError
  >;
  sendRpc<D extends AnyAgentCallableRpcDefinition>(
    definition: D,
    params: ClientDefinitionPayload<D>,
    opts?: RpcCallOptions,
  ): Effect.Effect<ClientDefinitionSuccess<D>, ClientDefinitionError<D>>;
  call<Tag extends AgentCallableTag>(
    tag: Tag,
    payload: PayloadForTag<AgentCallableRpcs, Tag>,
    opts?: RpcCallOptions,
  ): Effect.Effect<SuccessForTag<AgentCallableRpcs, Tag>, AgentRpcError<Tag>>;
}
```

Describes test agent client.

### [`TestingError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/errors.ts#L58)

*TypeAlias*

```ts theme={null}
export type TestingError =
  | TransportClosedError
  | TransportIoError
  | RpcTimeoutError
  | RpcResponseError
  | ToxicControlError
  | RealServerAcquireError;
```

Represents testing error conditions.

### [`TestServer`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/lifecycle.ts#L35)

*Interface*

```ts theme={null}
export interface TestServer {
  readonly baseUrl: string;
  readonly wsUrl: string;
  readonly close: Effect.Effect<void, unknown>;
}
```

Describes test server.

### [`TransportClosedError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/errors.ts#L8)

*Class*

```ts theme={null}
export class TransportClosedError extends Data.TaggedError(
  "TestingTransportClosedError",
)<{
  readonly direction: "outbound" | "inbound";
  readonly code: number;
  readonly reason: string;
}> {}
```

Peer closed the underlying WS before a response arrived.

### [`TransportIoError`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/errors.ts#L17)

*Class*

```ts theme={null}
export class TransportIoError extends Data.TaggedError(
  "TestingTransportIoError",
)<{
  readonly direction: "outbound" | "inbound";
  readonly cause: unknown;
}> {}
```

Underlying transport raised (socket error, DNS, TLS, etc.).

### [`userId`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/test-fixtures.ts#L80)

*Function*

```ts theme={null}
export const userId = (
  value: string,
): Schema.Schema.Type<typeof userIdSchema>
```

Validates and decodes user id values.

**Returns:** The user id result.

### [`waitForValue`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/wait.ts#L46)

*Function*

```ts theme={null}
export const waitForValue = <A, E = never, R = never>(
  probe: Effect.Effect<A | undefined, E, R>,
  options?: { readonly pollMillis?: number },
): Effect.Effect<A, E, R>
```

Poll `probe` until it returns a defined value, then return it.

**Returns:** The wait for value result.

### [`waitUntil`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/wait.ts#L28)

*Function*

```ts theme={null}
export const waitUntil = (
  predicate: () => boolean,
  options?: { readonly pollMillis?: number },
): Effect.Effect<void>
```

Poll `predicate` until it returns true.

**Returns:** The wait until result.

### [`WIRE_ERROR_TAG`](https://github.com/chughtapan/moltzap/blob/main/packages/protocol/src/testing/wire-error-tags.ts#L9)

*Variable*

```ts theme={null}
export const WIRE_ERROR_TAG =
```

## Files

* `errors.ts`
* `lifecycle.ts`
* `test-fixtures.ts`
* `wait.ts`
* `wire-error-tags.ts`