# zidane-ui/onboarding/testing/contract

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

## Functions

### `describeOnboardingHostContract`

Function.

Declares the shared `OnboardingHost` suite for one implementation.

```ts
function describeOnboardingHostContract(
  name: string,
  makeHarness: OnboardingHostHarnessFactory,
  capabilities: readonly OnboardingHostCapability[],
): void
```

**Parameters**

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

Source: [ui/src/onboarding/testing/contract.ts:237](https://github.com/Tahul/zidane/blob/main/ui/src/onboarding/testing/contract.ts#L237)

## Interfaces

### `OnboardingContractModel`

Interface.

A model the backend serves, as its listing names it.

```ts
interface OnboardingContractModel
```

**Properties**

- `id` (`string`): Model id.
- `label` (`string`): Display name.
- `reasoning` (`boolean`): It takes a reasoning effort.

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

### `OnboardingHostContractBackend`

Interface.

What the backend behind the host holds, and what it records.

```ts
interface OnboardingHostContractBackend
```

**Properties**

- `connectors` (`string[]`): The ids of the connectors already installed. A connector added reaches `connectorAdded`.
- `extensions` (`string[]`): The names of the native extensions installed.
- `failing` (`string[]`): Provider keys whose key, sign-in and test fail.
- `githubToken` (`string | null`): The GitHub token the backend already knows.
- `importPreview` (`OnboardingImportPreview`): What an import from Claude Code brings over.
- `installProgress` (`string[]`): What an install reports while it runs, one line at a time.
- `models` (`Record<string, OnboardingContractModel[]>`): The models each provider serves, by provider key.
- `providers` (`OnboardingProvider[]`): The providers and their status. Read at each listing; a saved key or a finished sign-in marks one ready.
- `settings` (`Partial<Settings>`): The stored settings: what the run starts from.
- `skillListings` (`Readonly<Record<string, SkillSourceListing>>`): The skill sources a browse lists, by what the user typed.
- `skills` (`string[]`): The names of the skills installed.
- `committed` (`(settings: Partial<Settings>) => void`): The backend calls this with the settings a finished run writes.
- `connectorAdded` (`(id: string) => void`): The backend calls this when a connector's server is added: its id joins `connectors`.
- `extensionInstalled` (`(name: string) => void`): The backend calls this when a native extension is installed: its name joins `extensions`.
- `imported` (`(selection: OnboardingImportSelection) => void`): The backend calls this when an import runs.
- `keySaved` (`(key: string, value: string | undefined) => void`): The backend calls this when a key reaches it: the provider turns ready.
- `signedIn` (`(key: string) => void`): The backend calls this when a browser sign-in of a provider finishes: the provider turns ready.
- `skillsInstalled` (`(source: string, rels: readonly string[]) => void`): The backend calls this when skills of a source are installed: their names join `skills`.

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

### `OnboardingHostHarness`

Interface.

A host built over a contract backend, and what its backend can push.

```ts
interface OnboardingHostHarness
```

**Properties**

- `host` (`OnboardingHost`): The host under test.
- `dispose?` (`() => void`): Stops sign-ins, listeners and connections after each test.
- `finishSignIn?` (`(id: string) => void`): The browser came back for a sign-in that takes no typed answer. Absent: every sign-in the host offers takes `submit`.

Source: [ui/src/onboarding/testing/contract.ts:118](https://github.com/Tahul/zidane/blob/main/ui/src/onboarding/testing/contract.ts#L118)

## Types

### `OnboardingHostCapability`

Type.

An optional `OnboardingHost` member, by its path.

```ts
type OnboardingHostCapability =
  | 'providers.saveKey'
  | 'providers.signIn'
  | 'providers.test'
  | 'providers.models'
  | 'imports'
  | 'connectors'
  | 'connectors.signIn'
  | 'connectors.githubToken'
  | 'skills'
  | 'skills.images'
  | 'extensions'
  | 'themes'
  | 'appIcons'
```

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

### `OnboardingHostHarnessFactory`

Type.

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

```ts
type OnboardingHostHarnessFactory = (backend: OnboardingHostContractBackend) => OnboardingHostHarness | Promise<OnboardingHostHarness>
```

Source: [ui/src/onboarding/testing/contract.ts:128](https://github.com/Tahul/zidane/blob/main/ui/src/onboarding/testing/contract.ts#L128)