UI kit reference

zidane-ui/chat/testing/contract

import { … } from 'zidane-ui/chat/testing/contract'ui/src/chat/testing/contract.ts

Functions#

`describeChatHostContract`Function#

Declares the shared ChatHost suite for one implementation.

TypeScript

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

Parameters

Parameters
Name	Type	Description
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.

ui/src/chat/testing/contract.ts:275

`describeComposerHostContract`Function#

Registers the contract's tests for one implementation.

TypeScript

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

Parameters

Parameters
Name	Type	Description
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.

ui/src/chat/testing/composer.contract.ts:292

`describeSidebarHostContract`Function#

Declares the shared SidebarHost suite for one implementation.

TypeScript

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

Parameters

Parameters
Name	Type	Description
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.

ui/src/chat/testing/sidebar.contract.ts:100

Interfaces#

`ChatHostContractBackend`Interface#

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

TypeScript

interface ChatHostContractBackend

Properties

ChatHostContractBackend properties
Name	Type	Description
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).

ui/src/chat/testing/contract.ts:130

`ChatHostContractControl`Interface#

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

TypeScript

interface ChatHostContractControl

Properties

ChatHostContractControl properties
Name	Type	Description
searchChanged?	`(state: ChatSearchState) => void`	Another window changed a session's transcript search.

ui/src/chat/testing/contract.ts:176

`ChatHostHarness`Interface#

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

TypeScript

interface ChatHostHarness

Properties

ChatHostHarness properties
Name	Type	Description
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.

ui/src/chat/testing/contract.ts:182

`ComposerContractSession`Interface#

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

TypeScript

interface ComposerContractSession

Properties

ComposerContractSession properties
Name	Type	Description
agent?	`string`	The agent profile.
effort?	`string`	The reasoning effort.
model?	`ModelPickRef[]`	The model chain, primary first.
options?	`Record<string, boolean>`	The enabled options.

ui/src/chat/testing/composer.contract.ts:125

`ComposerHostContractBackend`Interface#

What the backend behind the host holds.

TypeScript

interface ComposerHostContractBackend

Properties

ComposerHostContractBackend properties
Name	Type	Description
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.

ui/src/chat/testing/composer.contract.ts:137

`ComposerHostContractControl`Interface#

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

TypeScript

interface ComposerHostContractControl

Properties

ComposerHostContractControl properties
Name	Type	Description
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.

ui/src/chat/testing/composer.contract.ts:174

`ComposerHostHarness`Interface#

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

TypeScript

interface ComposerHostHarness

Properties

ComposerHostHarness properties
Name	Type	Description
control	`ComposerHostContractControl`	What the other windows do.
host	`ComposerHost`	The host under test.
dispose?	`() => void`	Closes connections after each test.

ui/src/chat/testing/composer.contract.ts:190

`SidebarHostContractBackend`Interface#

What the backend behind the host holds.

TypeScript

interface SidebarHostContractBackend

Properties

SidebarHostContractBackend properties
Name	Type	Description
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.

ui/src/chat/testing/sidebar.contract.ts:32

`SidebarHostContractControl`Interface#

Reads what the backend was asked to do.

TypeScript

interface SidebarHostContractControl

Properties

SidebarHostContractControl properties
Name	Type	Description
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`.

ui/src/chat/testing/sidebar.contract.ts:45

`SidebarHostHarness`Interface#

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

TypeScript

interface SidebarHostHarness

Properties

SidebarHostHarness properties
Name	Type	Description
control	`SidebarHostContractControl`	Reads the backend.
host	`SidebarHost`	The host under test.
dispose?	`() => void`	Closes connections after each test.

ui/src/chat/testing/sidebar.contract.ts:61

Types#

`ChatHostCapability`Type#

An optional ChatHost member, by its path.

TypeScript

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'

ui/src/chat/testing/contract.ts:33

`ChatHostHarnessFactory`Type#

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

TypeScript

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

ui/src/chat/testing/contract.ts:192

`ChatHostScriptStep`Type#

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

TypeScript

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

ui/src/chat/testing/contract.ts:121

`ComposerHostCapability`Type#

An optional ComposerHost member, by its path.

TypeScript

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'

ui/src/chat/testing/composer.contract.ts:37

`ComposerHostHarnessFactory`Type#

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

TypeScript

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

ui/src/chat/testing/composer.contract.ts:200

`SidebarHostCapability`Type#

An optional SidebarHost member.

TypeScript

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

ui/src/chat/testing/sidebar.contract.ts:21

`SidebarHostHarnessFactory`Type#

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

TypeScript

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

ui/src/chat/testing/sidebar.contract.ts:71

Functions#

describeChatHostContractFunction#

Parameters

describeComposerHostContractFunction#

Parameters

describeSidebarHostContractFunction#

Parameters

Interfaces#

ChatHostContractBackendInterface#

Properties

ChatHostContractControlInterface#

Properties

ChatHostHarnessInterface#

Properties

ComposerContractSessionInterface#

Properties

ComposerHostContractBackendInterface#

Properties

ComposerHostContractControlInterface#

Properties

ComposerHostHarnessInterface#

Properties

SidebarHostContractBackendInterface#

Properties

SidebarHostContractControlInterface#

Properties

SidebarHostHarnessInterface#

Properties

Types#

ChatHostCapabilityType#

ChatHostHarnessFactoryType#

ChatHostScriptStepType#

ComposerHostCapabilityType#

ComposerHostHarnessFactoryType#

SidebarHostCapabilityType#

SidebarHostHarnessFactoryType#

`describeChatHostContract`Function#

`describeComposerHostContract`Function#

`describeSidebarHostContract`Function#

`ChatHostContractBackend`Interface#

`ChatHostContractControl`Interface#

`ChatHostHarness`Interface#

`ComposerContractSession`Interface#

`ComposerHostContractBackend`Interface#

`ComposerHostContractControl`Interface#

`ComposerHostHarness`Interface#

`SidebarHostContractBackend`Interface#

`SidebarHostContractControl`Interface#

`SidebarHostHarness`Interface#

`ChatHostCapability`Type#

`ChatHostHarnessFactory`Type#

`ChatHostScriptStep`Type#

`ComposerHostCapability`Type#

`ComposerHostHarnessFactory`Type#

`SidebarHostCapability`Type#

`SidebarHostHarnessFactory`Type#