# zidane-ui/chat/testing/contract

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

## Functions

### `describeChatHostContract`

Function.

Declares the shared `ChatHost` suite for one implementation.

```ts
function describeChatHostContract(
  name: string,
  makeHarness: ChatHostHarnessFactory,
  capabilities: readonly ChatHostCapability[],
): void
```

**Parameters**

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

Source: [ui/src/chat/testing/contract.ts:275](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L275)

### `describeComposerHostContract`

Function.

Registers the contract's tests for one implementation.

```ts
function describeComposerHostContract(
  name: string,
  makeHarness: ComposerHostHarnessFactory,
  capabilities: readonly ComposerHostCapability[],
): void
```

**Parameters**

- `name` (`string`): The implementation's name, in the suite's title.
- `makeHarness` (`ComposerHostHarnessFactory`): Builds a host over the scripted backend.
- `capabilities` (`readonly ComposerHostCapability[]`): The optional members the implementation offers.

Source: [ui/src/chat/testing/composer.contract.ts:292](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L292)

### `describeSidebarHostContract`

Function.

Declares the shared `SidebarHost` suite for one implementation.

```ts
function describeSidebarHostContract(
  name: string,
  makeHarness: SidebarHostHarnessFactory,
  capabilities: readonly SidebarHostCapability[],
): void
```

**Parameters**

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

Source: [ui/src/chat/testing/sidebar.contract.ts:100](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/sidebar.contract.ts#L100)

## Interfaces

### `ChatHostContractBackend`

Interface.

What the backend behind the host holds, and how it answers a prompt.

```ts
interface ChatHostContractBackend
```

**Properties**

- `badgeEffects` (`Readonly<Record<string, BadgeActionEffect>>`): The effect running an item answers, by item id.
- `badgeItems` (`Readonly<Record<string, readonly BadgeMenuItem[]>>`): The extensions' badge items per folder.
- `blockRuns` (`{ exitCode: number; output: string }`): Run here: what every block writes, and its exit code.
- `commands` (`Readonly<Record<string, readonly ChatCommandFacts[]>>`): Commands per folder.
- `commits` (`Readonly<Record<string, ChatCommit>>`): Commits by full sha (any folder).
- `contexts` (`Readonly<Record<string, ChatContextFacts>>`): Context gauges by session id.
- `mainSession` (`string | null`): The orchestration Main session's id (created by the first ask), `null` while orchestration is off.
- `paths` (`Readonly<Record<string, Readonly<Record<string, ChatResolvedPath>>>>`): What each text names, per folder (a text missing here names nothing: `missing`).
- `providerReady` (`boolean`): Whether a model provider can answer a prompt.
- `references` (`{ providers: Readonly<Record<string, readonly ReferenceProviderWire[]>>; views: Readonly<Record<string, ExtensionReferenceView>> }`): Extension reference providers per folder, and the views of their keys by `providerId:key`.
- `sessionFacts` (`readonly ChatSessionFacts[]`): The sessions `#chat` cards read.
- `sessions` (`readonly ChatSession[]`): The sessions the backend starts with.
- `siteIcons` (`Readonly<Record<string, string>>`): Site icons by origin (an origin missing here has none).
- `skills` (`Readonly<Record<string, readonly ChatSkillFacts[]>>`): Skills per folder.
- `toolOutputs` (`Readonly<Record<string, string>>`): A tool call's full output, by call id (any session).
- `transcripts` (`Readonly<Record<string, readonly ChatEvent[]>>`): Stored events per session id (a session missing here has none).
- `script` (`(prompt: string) => readonly ChatHostScriptStep[]`): What a run does with a sent prompt. The backend echoes the prompt into the transcript, starts the
  run, plays these steps, and ends the run when they are done (unless a step holds it).
- `shell` (`(command: string) => string`): What a `!` run of `command` prints; the backend streams it into the session's transcript (no prompt echo).

Source: [ui/src/chat/testing/contract.ts:130](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L130)

### `ChatHostContractControl`

Interface.

Changes the backend from outside, as another window or the backend does.

```ts
interface ChatHostContractControl
```

**Properties**

- `searchChanged?` (`(state: ChatSearchState) => void`): Another window changed a session's transcript search.

Source: [ui/src/chat/testing/contract.ts:176](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L176)

### `ChatHostHarness`

Interface.

A host built over a scripted backend, and how to tear it down.

```ts
interface ChatHostHarness
```

**Properties**

- `control?` (`ChatHostContractControl`): Changes the backend from outside. Absent: the behaviours that need it are skipped.
- `host` (`ChatHost`): The host under test.
- `dispose?` (`() => void`): Closes connections and timers after each test.

Source: [ui/src/chat/testing/contract.ts:182](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L182)

### `ComposerContractSession`

Interface.

A session's picks as the backend holds them: what the controls write.

```ts
interface ComposerContractSession
```

**Properties**

- `agent?` (`string`): The agent profile.
- `effort?` (`string`): The reasoning effort.
- `model?` (`ModelPickRef[]`): The model chain, primary first.
- `options?` (`Record<string, boolean>`): The enabled options.

Source: [ui/src/chat/testing/composer.contract.ts:125](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L125)

### `ComposerHostContractBackend`

Interface.

What the backend behind the host holds.

```ts
interface ComposerHostContractBackend
```

**Properties**

- `agents` (`readonly ComposerAgentProfile[]`): The agent profiles.
- `cacheImpact` (`CacheImpact | null`): What any switch costs the cache.
- `chats` (`readonly ChatReferenceEntry[]`): The sessions `#` can reference.
- `commandArgs` (`Readonly<Record<string, readonly CommandArgSuggestionSummary[]>>`): The argument suggestions per command name.
- `commands` (`readonly CommandSummary[]`): The `/` commands.
- `context` (`Record<string, { breakdown?: ComposerContextBreakdown; cost?: ComposerCostStatus; status?: ComposerContextStatus }>`): Each session's meters.
- `drafts` (`Record<string, SharedDraft>`): The shared draft per session (a session missing here has none).
- `files` (`Readonly<Record<string, readonly FileEntry[]>>`): The files under each root.
- `ghosts` (`Readonly<Record<string, readonly string[]>>`): The ghost text completions per draft text.
- `lastFolder` (`string | null`): The folder last used for a new session (`folders.setLastUsed` writes here).
- `models` (`readonly ComposerModelEntry[]`): The chat models.
- `prefs` (`ComposerPrefsState`): The remembered picks (prefs write here).
- `runProgress` (`Record<string, ComposerRunProgress>`): Each session's run in progress.
- `sessions` (`Record<string, ComposerContractSession>`): Each session's picks (the controls write here).
- `skills` (`readonly SkillConfig[]`): The enabled skills.

Source: [ui/src/chat/testing/composer.contract.ts:137](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L137)

### `ComposerHostContractControl`

Interface.

What the other windows (and the agent) do, announced as the backend announces it.

```ts
interface ComposerHostContractControl
```

**Properties**

- `runSignal?` (`(signal: RunMeterSignal) => void`): The backend streams a run signal. Needed for `runs`.
- `setDraft` (`(sessionId: string, text: string, shell?: boolean) => void`): Another window changed a session's draft text.
- `setDraftAttachments` (`(sessionId: string, attachments: PromptAttachment[]) => void`): Another window changed a session's staged files.
- `shareGhost` (`(ghost: ComposerSharedGhost) => void`): Another window resolved a ghost text.
- `startRun` (`(sessionId: string) => void`): A run started in a session.
- `suggest` (`(suggestion: ComposerPromptSuggestion) => void`): A run ended with a next-prompt suggestion.

Source: [ui/src/chat/testing/composer.contract.ts:174](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L174)

### `ComposerHostHarness`

Interface.

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

```ts
interface ComposerHostHarness
```

**Properties**

- `control` (`ComposerHostContractControl`): What the other windows do.
- `host` (`ComposerHost`): The host under test.
- `dispose?` (`() => void`): Closes connections after each test.

Source: [ui/src/chat/testing/composer.contract.ts:190](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L190)

### `SidebarHostContractBackend`

Interface.

What the backend behind the host holds.

```ts
interface SidebarHostContractBackend
```

**Properties**

- `badges` (`Readonly<Record<string, readonly SessionBadgeEntry[]>>`): Each session's badges; a session left out has none.
- `environments` (`Readonly<Record<string, { actions: readonly EnvironmentActionSummary[]; results: Readonly<Record<string, EnvironmentActionResult>> }>>`): Each session's environment: the commands it offers and what running each answers.

Source: [ui/src/chat/testing/sidebar.contract.ts:32](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/sidebar.contract.ts#L32)

### `SidebarHostContractControl`

Interface.

Reads what the backend was asked to do.

```ts
interface SidebarHostContractControl
```

**Properties**

- `changeArtifacts?` (`(sessionId: string) => void`): The backend records or changes an artifact of `sessionId`. Only called with `badges`.
- `changeKinds?` (`() => void`): The backend's badge kinds change (extensions installed or removed). Only called with `badges`.
- `hostSettingsOpened?` (`() => readonly string[]`): The hosts whose settings were opened, in order. Only read with `openHostSettings`.
- `retried?` (`() => readonly string[]`): The environments set up again, in order. Only read with `environment`.
- `revealed?` (`() => readonly string[]`): The folders revealed, in order. Only read with `revealPath`.
- `windows?` (`() => readonly { mode: SessionWindowMode; sessionId: string }[]`): The windows opened, in order. Only read with `openWindow`.

Source: [ui/src/chat/testing/sidebar.contract.ts:45](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/sidebar.contract.ts#L45)

### `SidebarHostHarness`

Interface.

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

```ts
interface SidebarHostHarness
```

**Properties**

- `control` (`SidebarHostContractControl`): Reads the backend.
- `host` (`SidebarHost`): The host under test.
- `dispose?` (`() => void`): Closes connections after each test.

Source: [ui/src/chat/testing/sidebar.contract.ts:61](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/sidebar.contract.ts#L61)

## Types

### `ChatHostCapability`

Type.

An optional `ChatHost` member, by its path.

```ts
type ChatHostCapability =
  | 'sessions'
  | 'sessions.create'
  | 'sessions.rename'
  | 'sessions.setArchived'
  | 'sessions.setFavorite'
  | 'sessions.remove'
  | 'sessions.query'
  | 'sessions.setSpace'
  | 'sessions.search'
  | 'sessions.onChanged'
  | 'sessions.views'
  | 'sessions.main'
  | 'send'
  | 'interrupt'
  | 'shell'
  | 'providerReady'
  | 'interactions'
  | 'interactions.cancel'
  | 'interactions.all'
  | 'models'
  | 'toolOutput'
  | 'cancelTool'
  | 'searchSync'
  | 'references'
  | 'paths'
  | 'chips'
  | 'chips.commit'
  | 'chips.sessions'
  | 'chips.context'
  | 'chips.skills'
  | 'chips.commands'
  | 'badges'
  | 'siteIcons'
  | 'blockRuns'
```

Source: [ui/src/chat/testing/contract.ts:33](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L33)

### `ChatHostHarnessFactory`

Type.

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

```ts
type ChatHostHarnessFactory = (backend: ChatHostContractBackend) => ChatHostHarness | Promise<ChatHostHarness>
```

Source: [ui/src/chat/testing/contract.ts:192](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L192)

### `ChatHostScriptStep`

Type.

One thing the backend does while it runs a prompt, in order.

```ts
type ChatHostScriptStep =
  | { kind: 'reply'; text: string }
  | { kind: 'ask'; request: InteractionRequest }
  | { kind: 'hold' }
```

Source: [ui/src/chat/testing/contract.ts:121](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/contract.ts#L121)

### `ComposerHostCapability`

Type.

An optional `ComposerHost` member, by its path.

```ts
type ComposerHostCapability =
  | 'drafts'
  | 'drafts.setAttachments'
  | 'drafts.onChanged'
  | 'drafts.onAttachmentsChanged'
  | 'completions'
  | 'completions.files'
  | 'completions.commands'
  | 'completions.commandArgs'
  | 'completions.chats'
  | 'completions.watchSkills'
  | 'completions.watchExtensionProviders'
  | 'completions.extensionItems'
  | 'completions.submit'
  | 'completions.locationOf'
  | 'folders'
  | 'autocomplete'
  | 'autocomplete.onShared'
  | 'suggestions'
  | 'suggestions.onStale'
  | 'controls'
  | 'controls.setModel'
  | 'controls.setEffort'
  | 'controls.setModelOptions'
  | 'controls.setAgent'
  | 'controls.cacheImpact'
  | 'models'
  | 'models.images'
  | 'models.providers'
  | 'agents'
  | 'agents.onChanged'
  | 'prefs'
  | 'pickerPrefs'
  | 'context'
  | 'context.status'
  | 'context.breakdown'
  | 'context.cost'
  | 'runs'
  | 'runs.progress'
  | 'runs.noteSeen'
  | 'runs.noteProgress'
  | 'runs.settleCost'
```

Source: [ui/src/chat/testing/composer.contract.ts:37](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L37)

### `ComposerHostHarnessFactory`

Type.

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

```ts
type ComposerHostHarnessFactory = (backend: ComposerHostContractBackend) => ComposerHostHarness | Promise<ComposerHostHarness>
```

Source: [ui/src/chat/testing/composer.contract.ts:200](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/composer.contract.ts#L200)

### `SidebarHostCapability`

Type.

An optional `SidebarHost` member.

```ts
type SidebarHostCapability =
  | 'revealPath'
  | 'openWindow'
  | 'environment'
  | 'badges'
  | 'openHostSettings'
```

Source: [ui/src/chat/testing/sidebar.contract.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/sidebar.contract.ts#L21)

### `SidebarHostHarnessFactory`

Type.

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

```ts
type SidebarHostHarnessFactory = (backend: SidebarHostContractBackend) => SidebarHostHarness | Promise<SidebarHostHarness>
```

Source: [ui/src/chat/testing/sidebar.contract.ts:71](https://github.com/Tahul/zidane/blob/main/ui/src/chat/testing/sidebar.contract.ts#L71)