# zidane-ui/session/testing/contract

Import: `import { … } from 'zidane-ui/session/testing/contract'`. Source: [ui/src/session/testing/contract.ts](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts).

## Functions

### `describeSessionHostContract`

Function.

Declares the shared `SessionHost` suite for one implementation.

```ts
function describeSessionHostContract(
  name: string,
  makeHarness: SessionHostHarnessFactory,
  capabilities: readonly SessionHostCapability[],
): void
```

**Parameters**

- `name` (`string`): The implementation's name, shown in the suite title.
- `makeHarness` (`SessionHostHarnessFactory`): Builds a fresh host over a backend that holds what it is given, once per test.
- `capabilities` (`readonly SessionHostCapability[]`): The optional members the host offers. Every other optional member must be undefined.

Source: [ui/src/session/testing/contract.ts:315](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L315)

## Interfaces

### `SessionHostContractBackend`

Interface.

What the backend behind the host holds, per session id.

```ts
interface SessionHostContractBackend
```

**Properties**

- `artifacts` (`Readonly<Record<string, readonly SessionArtifact[]>>`): The stored artifacts per session, newest first.
- `queue` (`Readonly<Record<string, readonly SessionHostContractEntry[]>>`): The queue per session.
- `scheduleFires` (`Readonly<Record<string, readonly ScheduleFire[]>>`): Each reminder's fires, newest first.
- `schedules` (`readonly Schedule[]`): The stored reminders, oldest first (the Reminders setting is on). Serve them as `createFixtureScheduleBackend` does.
- `secrets` (`Readonly<Record<string, readonly SessionSecretEntry[]>>`): The saved secrets per session (its project's), without values.
- `sides` (`Record<string, string>`): Each session's side chat, by the parent's id: side chats created land here, removed ones leave.
- `todos` (`Readonly<Record<string, readonly TodoItem[]>>`): Each session's task list as the agent wrote it (`todowrite`): its applying plan. A session missing here holds
  no plans (its snapshot reads `null`). `createFixturePlansBackend({ todos })` serves it.
- `turns` (`Readonly<Record<string, readonly SessionTurn[]>>`): The stored turns per session.
- `work` (`Readonly<Record<string, readonly RunningWorkItem[]>>`): The running work per session.

Source: [ui/src/session/testing/contract.ts:148](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L148)

### `SessionHostContractControl`

Interface.

Changes the backend from outside and announces it as the backend does.

```ts
interface SessionHostContractControl
```

**Properties**

- `recordArtifact` (`(sessionId: string, artifact: SessionArtifact) => void`): The session recorded an artifact (it becomes the newest).
- `setQueue` (`(sessionId: string, entries: readonly SessionHostContractEntry[]) => void`): Another window changed the session's queue.
- `setSchedules?` (`(list: readonly Schedule[]) => void`): The stored reminders changed (the agent set one, one fired): announced as `schedules:changed`. Absent: not checked.
- `setSecrets` (`(sessionId: string, entries: readonly SecretEntry[]) => void`): The session's project secrets changed (the agent saved one, another window revoked one): announced as a store change.
- `setWork` (`(sessionId: string, items: readonly RunningWorkItem[]) => void`): The session's work changed (a tool call started or ended).
- `writeTodos` (`(sessionId: string, items: readonly TodoItem[]) => void`): The agent wrote its task list again (`todowrite`): announced as a plans snapshot.

Source: [ui/src/session/testing/contract.ts:173](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L173)

### `SessionHostContractEntry`

Interface.

A queued message the backend holds, with its attachments' bytes.

```ts
interface SessionHostContractEntry
```

**Properties**

- `attachments?` (`PromptAttachment[]`): Its attachments, with their bytes.
- `id` (`string`): The entry's id.
- `text` (`string`): The message text.

Source: [ui/src/session/testing/contract.ts:138](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L138)

### `SessionHostHarness`

Interface.

A host built over a backend, the backend's control, and how to tear them down.

```ts
interface SessionHostHarness
```

**Properties**

- `control` (`SessionHostContractControl`): Changes the backend from outside.
- `host` (`SessionHost`): The host under test.
- `dispose?` (`() => void`): Closes connections and timers after each test.

Source: [ui/src/session/testing/contract.ts:189](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L189)

## Types

### `SessionHostCapability`

Type.

An optional `SessionHost` member, by its path.

```ts
type SessionHostCapability =
  | 'plans'
  | 'plans.edit'
  | 'plans.control'
  | 'plans.retry'
  | 'queue'
  | 'queue.add'
  | 'queue.remove'
  | 'queue.update'
  | 'queue.attachments'
  | 'queue.pushNow'
  | 'artifacts'
  | 'artifacts.remove'
  | 'artifacts.refreshRow'
  | 'runningWork'
  | 'runningWork.cancel'
  | 'turns'
  | 'turns.fork'
  | 'turns.editText'
  | 'turns.delete'
  | 'turns.rewind'
  | 'details'
  | 'details.titleStatus'
  | 'details.generateTitle'
  | 'details.export'
  | 'details.compact'
  | 'details.setFolder'
  | 'details.cacheReport'
  | 'usage'
  | 'usage.summary'
  | 'usage.providers'
  | 'usage.github'
  | 'usage.redeemReset'
  | 'side'
  | 'side.subscribe'
  | 'secrets'
  | 'secrets.save'
  | 'secrets.revoke'
  | 'schedules'
  | 'schedules.create'
  | 'schedules.update'
  | 'schedules.remove'
  | 'schedules.runNow'
  | 'schedules.fires'
```

Source: [ui/src/session/testing/contract.ts:46](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L46)

### `SessionHostHarnessFactory`

Type.

Builds a fresh host (and its backend) for one test.

```ts
type SessionHostHarnessFactory = (backend: SessionHostContractBackend) => SessionHostHarness | Promise<SessionHostHarness>
```

Source: [ui/src/session/testing/contract.ts:199](https://github.com/Tahul/zidane/blob/main/ui/src/session/testing/contract.ts#L199)