> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moltzap.xyz/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#L71)

*Function*

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

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

*Variable*

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

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

*Function*

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

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

*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}`)
```

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

*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).

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

*Function*

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

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

*Variable*

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

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

*Function*

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

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

*Function*

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

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

*Function*

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

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

*Function*

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

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

*Function*

```ts theme={null}
export function makeTestAppClient(
  appId: AppId,
  options: AppClientOptions,
): Effect.Effect<TestAppClient, unknown>
```

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

*Function*

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

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

*Function*

```ts theme={null}
export function mintTestAppCredential(
  opts: RegisterTestAppOptions,
): Effect.Effect<TestAppCredential, TestAppHttpRegistrationError>
```

Register an app manifest against the real server's HTTP endpoint and
return the server-minted `{ appId, appKey }` (the `appId` is
`gen_random_uuid()`, NOT `manifest.appId`). The App-principal sibling of
registerTestAgent; the `appKey` is handed to a `TestClient` whose
`appKey` Connect arm binds an `AppConnection` through the implicit
moderator-endpoint registration path.

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

*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#L91)

*Function*

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

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

*Function*

```ts theme={null}
export const redactedAppKey = (value: string): AppKey
```

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

*Function*

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

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

*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#L24)

*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.

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

*Function*

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

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

*Interface*

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

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

*Interface*

```ts theme={null}
export interface TestAgentClient {
  readonly principal: "agent";
  readonly agentId?: AgentId;
  close(): Effect.Effect<void, never>;
  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>>;
}
```

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

*Interface*

```ts theme={null}
export interface TestAppClient {
  readonly principal: "app";
  readonly appId?: AppId;
  close(): Effect.Effect<void, never>;
  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 AnyAppCallableRpcDefinition>(
    definition: D,
    params: ClientDefinitionPayload<D>,
    opts?: RpcCallOptions,
  ): Effect.Effect<ClientDefinitionSuccess<D>, ClientDefinitionError<D>>;
  call<Tag extends AppCallableTag>(
    tag: Tag,
    payload: PayloadForTag<AppCallableRpcs, Tag>,
    opts?: RpcCallOptions,
  ): Effect.Effect<SuccessForTag<AppCallableRpcs, Tag>, AppRpcError<Tag>>;
}
```

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

*Interface*

```ts theme={null}
export interface TestAppCredential {
  readonly appId: Schema.Schema.Type<typeof AppId>;
  readonly appKey: AppKey;
}
```

Server-minted app principal credentials.

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

*Class*

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

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

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

*TypeAlias*

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

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

*Interface*

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

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

*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#L16)

*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#L69)

*Function*

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

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

*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.

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

*Function*

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

Poll `predicate` until it returns true.

### [`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`