# zidane-ui/settings/testing/contract

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

## Functions

### `describeSettingsAccountsContract`

Function.

Declares the shared suite of the `providers` and `mcp` groups for one implementation.

```ts
function describeSettingsAccountsContract(
  name: string,
  makeHarness: SettingsAccountsHarnessFactory,
  capabilities: readonly SettingsAccountsCapability[],
): void
```

**Parameters**

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

Source: [ui/src/settings/testing/accounts.contract.ts:162](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L162)

### `describeSettingsClaudeImportContract`

Function.

Declares the shared `SettingsHost.claudeImport` suite for one implementation.

```ts
function describeSettingsClaudeImportContract(
  name: string,
  makeHarness: SettingsClaudeImportHarnessFactory,
  offered: boolean,
): void
```

**Parameters**

- `name` (`string`): The implementation's name, shown in the suite title.
- `makeHarness` (`SettingsClaudeImportHarnessFactory`): Builds a fresh host over a backend that holds what it is given, once per test.
- `offered` (`boolean`): Whether the host offers `claudeImport`.

Source: [ui/src/settings/testing/claude-import.contract.ts:57](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/claude-import.contract.ts#L57)

### `describeSettingsExtensionOptionsContract`

Function.

Declares the shared extension options suite for one implementation.

```ts
function describeSettingsExtensionOptionsContract(
  name: string,
  makeHarness: SettingsExtensionOptionsHarnessFactory,
  capabilities: readonly SettingsExtensionOptionsCapability[],
): void
```

**Parameters**

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

Source: [ui/src/settings/testing/extension-options.contract.ts:104](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/extension-options.contract.ts#L104)

### `describeSettingsHostContract`

Function.

Declares the shared `SettingsHost` suite for one implementation.

```ts
function describeSettingsHostContract(
  name: string,
  makeHarness: SettingsHostHarnessFactory,
  capabilities: readonly SettingsHostCapability[],
  traits?: SettingsHostContractTraits,
): void
```

**Parameters**

- `name` (`string`): The implementation's name, shown in the suite title.
- `makeHarness` (`SettingsHostHarnessFactory`): Builds a fresh host over a backend that holds what it is given, once per test.
- `capabilities` (`readonly SettingsHostCapability[]`): The optional members the host offers. Every other optional member must be undefined.
- `traits?` (`SettingsHostContractTraits`, default `{}`): The failures the backend can stage.

Source: [ui/src/settings/testing/contract.ts:95](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/contract.ts#L95)

### `describeSettingsModelsContract`

Function.

Declares the shared `SettingsHost.models` suite for one implementation.

```ts
function describeSettingsModelsContract(
  name: string,
  makeHarness: SettingsModelsHarnessFactory,
  capabilities: readonly SettingsModelsCapability[],
): void
```

**Parameters**

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

Source: [ui/src/settings/testing/models.contract.ts:72](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/models.contract.ts#L72)

### `describeSettingsPerformanceContract`

Function.

Declares the shared `SettingsHost.performance` suite for one implementation.

```ts
function describeSettingsPerformanceContract(
  name: string,
  makeHarness: SettingsPerformanceHarnessFactory,
  capabilities: false | readonly SettingsPerformanceCapability[],
  options?: SettingsPerformanceContractOptions,
): void
```

**Parameters**

- `name` (`string`): The implementation's name, shown in the suite title.
- `makeHarness` (`SettingsPerformanceHarnessFactory`): Builds a fresh host over a backend that holds what it is given, once per test.
- `capabilities` (`false | readonly SettingsPerformanceCapability[]`): The optional members the host offers; `false`: no `performance` at all.
- `options?` (`SettingsPerformanceContractOptions`, default `{}`): What else to check (refused watches).

Source: [ui/src/settings/testing/performance.contract.ts:103](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L103)

### `describeSettingsSectionsContract`

Function.

Declares the shared suite of the catalog and diagnostics groups for one implementation.

```ts
function describeSettingsSectionsContract(
  name: string,
  makeHarness: SettingsSectionsHarnessFactory,
  capabilities: readonly SettingsSectionsCapability[],
): void
```

**Parameters**

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

Source: [ui/src/settings/testing/sections.contract.ts:195](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/sections.contract.ts#L195)

## Constants

### `ACCOUNTS_CONTRACT_CWD`

Constant.

The folder the suite's MCP calls name.

```ts
const ACCOUNTS_CONTRACT_CWD = '/work/app'
```

Source: [ui/src/settings/testing/accounts.contract.ts:84](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L84)

## Interfaces

### `SettingsAccountsBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsAccountsBackend
```

**Properties**

- `instances` (`SettingsMcpInstance[]`): The running processes of those servers.
- `providers` (`SettingsProvider[]`): The providers and their credentials.
- `servers` (`SettingsMcpServer[]`): The MCP servers of the folder the suite names (`ACCOUNTS_CONTRACT_CWD`).

Source: [ui/src/settings/testing/accounts.contract.ts:47](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L47)

### `SettingsAccountsControl`

Interface.

Reads the backend and acts on it from outside.

```ts
interface SettingsAccountsControl
```

**Properties**

- `credentials` (`(provider: string) => readonly SettingsCredential[]`): The stored credentials of a provider now (no `env`).
- `finishSignIn` (`() => void | Promise<void>`): The browser of the sign-in that waits came back: it finishes.
- `restarts?` (`() => readonly string[]`): The servers restarted, in order. Required with `mcp.restart`.
- `serverNames` (`() => string[]`): The servers held now, by name.

Source: [ui/src/settings/testing/accounts.contract.ts:57](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L57)

### `SettingsAccountsHarness`

Interface.

A host built over a backend, its control, and how to tear them down.

```ts
interface SettingsAccountsHarness
```

**Properties**

- `control` (`SettingsAccountsControl`): Reads and acts on the backend.
- `host` (`SettingsHost`): The host under test.
- `dispose?` (`() => void`): Closes listeners after each test.

Source: [ui/src/settings/testing/accounts.contract.ts:69](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L69)

### `SettingsClaudeImportBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsClaudeImportBackend
```

**Properties**

- `detect` (`SettingsClaudeImportDetect`): What `~/.claude` holds.
- `summary` (`SettingsClaudeImportSummary`): What an import answers.

Source: [ui/src/settings/testing/claude-import.contract.ts:19](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/claude-import.contract.ts#L19)

### `SettingsClaudeImportHarness`

Interface.

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

```ts
interface SettingsClaudeImportHarness
```

**Properties**

- `host` (`SettingsHost`): The host under test.
- `dispose?` (`() => void`): Closes listeners after each test.
- `runs?` (`() => SettingsClaudeImportSelection[]`): The selections the backend imported, in order.

Source: [ui/src/settings/testing/claude-import.contract.ts:27](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/claude-import.contract.ts#L27)

### `SettingsExtensionOptionsBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsExtensionOptionsBackend
```

**Properties**

- `actions` (`SettingsExtensionAction[]`): The action rows declared.
- `runs` (`Record<string, SettingsExtensionActionResult>`): What running each action answers, keyed `extension:key`.
- `schema` (`WireExtensionConfigSchema`): The options declared (for every folder).
- `statuses` (`Record<string, SettingsExtensionActionStatus>`): The probes, keyed `extension:key`.

Source: [ui/src/settings/testing/extension-options.contract.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/extension-options.contract.ts#L36)

### `SettingsExtensionOptionsHarness`

Interface.

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

```ts
interface SettingsExtensionOptionsHarness
```

**Properties**

- `host` (`SettingsHost`): The host under test.
- `created?` (`() => string[]`): The extensions scaffolded, by name.
- `dispose?` (`() => void`): Closes listeners after each test.

Source: [ui/src/settings/testing/extension-options.contract.ts:48](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/extension-options.contract.ts#L48)

### `SettingsHostContractBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsHostContractBackend
```

**Properties**

- `unreadable` (`boolean`): Reads fail.
- `values` (`Partial<Settings>`): The stored settings (a partial document: the host fills the rest from `DEFAULT_SETTINGS`).
- `writable` (`boolean`): This connection may write.

Source: [ui/src/settings/testing/contract.ts:38](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/contract.ts#L38)

### `SettingsHostContractControl`

Interface.

Reads the backend and changes it from outside.

```ts
interface SettingsHostContractControl
```

**Properties**

- `refuse?` (`(next: boolean) => void`): Refuse the next writes (`traits.refusedWrite`).
- `store` (`(patch: Partial<Settings>) => void`): Another writer changed the stored settings. The host shows them after its next `refresh` (or sooner).
- `stored` (`() => Partial<Settings>`): The settings stored now.

Source: [ui/src/settings/testing/contract.ts:48](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/contract.ts#L48)

### `SettingsHostContractTraits`

Interface.

Failures the backend can stage. Default: both.

```ts
interface SettingsHostContractTraits
```

**Properties**

- `failedRead?` (`boolean`): A read can fail (the document lands on an error).
- `refusedWrite?` (`boolean`): A write can be refused (`control.refuse`).

Source: [ui/src/settings/testing/contract.ts:73](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/contract.ts#L73)

### `SettingsHostHarness`

Interface.

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

```ts
interface SettingsHostHarness
```

**Properties**

- `control` (`SettingsHostContractControl`): Reads and changes the backend.
- `host` (`SettingsHost`): The host under test.
- `dispose?` (`() => void`): Closes listeners after each test.

Source: [ui/src/settings/testing/contract.ts:58](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/contract.ts#L58)

### `SettingsModelsBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsModelsBackend
```

**Properties**

- `decisionModels` (`SettingsDecisionModel[]`): The decision models (for every folder).
- `lastUsed` (`ModelPickRef | null`): The last model picked.
- `tests` (`Record<string, SettingsModelTest>`): How a test of each model goes, by model setting (`"provider/model"`); a model left out fails.

Source: [ui/src/settings/testing/models.contract.ts:25](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/models.contract.ts#L25)

### `SettingsModelsHarness`

Interface.

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

```ts
interface SettingsModelsHarness
```

**Properties**

- `host` (`SettingsHost`): The host under test.
- `dispose?` (`() => void`): Closes listeners after each test.

Source: [ui/src/settings/testing/models.contract.ts:35](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/models.contract.ts#L35)

### `SettingsPerformanceBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsPerformanceBackend
```

**Properties**

- `profile` (`PerfProfileOutcome`): What a profile answers.
- `reportPath` (`string`): Where a report is written.
- `samples` (`PerfSample[]`): The samples held, oldest first.
- `threads` (`Record<number, PerfOsThread[]>`): Each process's threads.
- `watchError?` (`PerfWatchError`): Set: the backend refuses every watch with this (only with `watchErrors`).

Source: [ui/src/settings/testing/performance.contract.ts:34](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L34)

### `SettingsPerformanceContractOptions`

Interface.

What the suite checks beyond the members.

```ts
interface SettingsPerformanceContractOptions
```

**Properties**

- `watchErrors?` (`boolean`): The host can refuse a watch: build it over `backend.watchError`.

Source: [ui/src/settings/testing/performance.contract.ts:48](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L48)

### `SettingsPerformanceControl`

Interface.

Drives the backend and reads it back.

```ts
interface SettingsPerformanceControl
```

**Properties**

- `emit` (`(sample: PerfSample) => void`): The backend takes a sample: every watcher gets it.
- `profiles` (`() => { seconds: number; target: PerfProfileTarget }[]`): Profiles the backend recorded, in order.
- `resets` (`() => number`): Counter resets the backend took.
- `watching` (`() => number`): How many watches are open on the backend (it samples only while one is).

Source: [ui/src/settings/testing/performance.contract.ts:54](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L54)

### `SettingsPerformanceHarness`

Interface.

A host built over a backend, its control, and how to tear them down.

```ts
interface SettingsPerformanceHarness
```

**Properties**

- `control` (`SettingsPerformanceControl`): Drives the backend: pushes samples, fails calls.
- `host` (`SettingsHost`): The host under test, its `performance` member over the backend.
- `dispose?` (`() => void`): Tears the host down after the test.

Source: [ui/src/settings/testing/performance.contract.ts:66](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L66)

### `SettingsSectionsBackend`

Interface.

What the backend behind the host holds.

```ts
interface SettingsSectionsBackend
```

**Properties**

- `environments` (`EnvironmentDescriptor[]`): The environment kinds.
- `extensions` (`SettingsExtension[]`): The extensions on disk (for every folder).
- `hostCatalog` (`FixtureHostCatalogs | null`): `null`: the host can't list its catalogs (an older server).
- `instructions` (`Record<string, ContextSegmentsReport>`): Each session's prompt.
- `logs` (`LogRecord[]`): The log records held.
- `plugins` (`SettingsPlugin[]`): The plugins (for every folder).
- `skills` (`SkillConfig[]`): The skills on disk (for every folder).

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

### `SettingsSectionsControl`

Interface.

Reads the backend and changes it from outside.

```ts
interface SettingsSectionsControl
```

**Properties**

- `catalogChanged` (`(kind: SettingsCatalogKind) => void`): One of the host's catalogs changed there (another client installed something).
- `environmentChanges` (`() => readonly EnvironmentSettingsChange[]`): Environment edits the backend took, in order.
- `extensionNames` (`() => string[]`): The extensions held now (by name).
- `log` (`(record: LogRecord) => void`): The backend logs a record.
- `skillNames` (`() => string[]`): The skills held now (by name).

Source: [ui/src/settings/testing/sections.contract.ts:64](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/sections.contract.ts#L64)

### `SettingsSectionsHarness`

Interface.

A host built over a backend, its control, and how to tear them down.

```ts
interface SettingsSectionsHarness
```

**Properties**

- `control` (`SettingsSectionsControl`): Reads and changes the backend.
- `host` (`SettingsHost`): The host under test.
- `dispose?` (`() => void`): Closes listeners after each test.

Source: [ui/src/settings/testing/sections.contract.ts:78](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/sections.contract.ts#L78)

## Types

### `SettingsAccountsCapability`

Type.

A group of `SettingsHost` this suite covers, or one of its optional actions.

```ts
type SettingsAccountsCapability =
  | 'providers'
  | 'providers.setApiKey'
  | 'providers.configure'
  | 'providers.clear'
  | 'providers.remove'
  | 'providers.setPreferred'
  | 'providers.rename'
  | 'providers.signIn'
  | 'mcp'
  | 'mcp.test'
  | 'mcp.signIn'
  | 'mcp.signOut'
  | 'mcp.add'
  | 'mcp.remove'
  | 'mcp.instances'
  | 'mcp.restart'
```

Source: [ui/src/settings/testing/accounts.contract.ts:25](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L25)

### `SettingsAccountsHarnessFactory`

Type.

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

```ts
type SettingsAccountsHarnessFactory = (backend: SettingsAccountsBackend) => SettingsAccountsHarness | Promise<SettingsAccountsHarness>
```

Source: [ui/src/settings/testing/accounts.contract.ts:79](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/accounts.contract.ts#L79)

### `SettingsClaudeImportHarnessFactory`

Type.

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

```ts
type SettingsClaudeImportHarnessFactory = (backend: SettingsClaudeImportBackend) => SettingsClaudeImportHarness | Promise<SettingsClaudeImportHarness>
```

Source: [ui/src/settings/testing/claude-import.contract.ts:37](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/claude-import.contract.ts#L37)

### `SettingsExtensionOptionsCapability`

Type.

An extension options member of `SettingsHost.extensions`.

```ts
type SettingsExtensionOptionsCapability =
  | 'configSchema'
  | 'actions'
  | 'actionStatuses'
  | 'runAction'
  | 'create'
```

Source: [ui/src/settings/testing/extension-options.contract.ts:25](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/extension-options.contract.ts#L25)

### `SettingsExtensionOptionsHarnessFactory`

Type.

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

```ts
type SettingsExtensionOptionsHarnessFactory = (backend: SettingsExtensionOptionsBackend) => SettingsExtensionOptionsHarness | Promise<SettingsExtensionOptionsHarness>
```

Source: [ui/src/settings/testing/extension-options.contract.ts:58](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/extension-options.contract.ts#L58)

### `SettingsHostCapability`

Type.

An optional `SettingsHost` member.

```ts
type SettingsHostCapability = 'update' | 'writable'
```

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

### `SettingsHostHarnessFactory`

Type.

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

```ts
type SettingsHostHarnessFactory = (backend: SettingsHostContractBackend) => SettingsHostHarness | Promise<SettingsHostHarness>
```

Source: [ui/src/settings/testing/contract.ts:68](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/contract.ts#L68)

### `SettingsModelsCapability`

Type.

A member of `SettingsHost.models`.

```ts
type SettingsModelsCapability = 'decisionModels' | 'test' | 'testDecision' | 'lastUsed'
```

Source: [ui/src/settings/testing/models.contract.ts:20](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/models.contract.ts#L20)

### `SettingsModelsHarnessFactory`

Type.

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

```ts
type SettingsModelsHarnessFactory = (backend: SettingsModelsBackend) => SettingsModelsHarness | Promise<SettingsModelsHarness>
```

Source: [ui/src/settings/testing/models.contract.ts:43](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/models.contract.ts#L43)

### `SettingsPerformanceCapability`

Type.

An optional member of `SettingsHost.performance`.

```ts
type SettingsPerformanceCapability =
  | 'threads'
  | 'resetCounters'
  | 'exportReport'
  | 'profile'
```

Source: [ui/src/settings/testing/performance.contract.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L29)

### `SettingsPerformanceHarnessFactory`

Type.

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

```ts
type SettingsPerformanceHarnessFactory = (backend: SettingsPerformanceBackend) => SettingsPerformanceHarness | Promise<SettingsPerformanceHarness>
```

Source: [ui/src/settings/testing/performance.contract.ts:76](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/performance.contract.ts#L76)

### `SettingsSectionsCapability`

Type.

A catalog or diagnostics group of `SettingsHost`.

```ts
type SettingsSectionsCapability =
  | 'skills'
  | 'extensions'
  | 'plugins'
  | 'instructions'
  | 'environments'
  | 'logs'
  | 'hostCatalog'
  | 'paths'
```

Source: [ui/src/settings/testing/sections.contract.ts:31](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/sections.contract.ts#L31)

### `SettingsSectionsHarnessFactory`

Type.

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

```ts
type SettingsSectionsHarnessFactory = (backend: SettingsSectionsBackend) => SettingsSectionsHarness | Promise<SettingsSectionsHarness>
```

Source: [ui/src/settings/testing/sections.contract.ts:88](https://github.com/Tahul/zidane/blob/main/ui/src/settings/testing/sections.contract.ts#L88)