# zidane-ui/appearance/testing/contract

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

## Functions

### `describeAppearanceHostContract`

Function.

Declares the shared `AppearanceHost` suite for one implementation.

```ts
function describeAppearanceHostContract(
  name: string,
  makeHarness: AppearanceHostHarnessFactory,
  capabilities: readonly AppearanceHostCapability[],
): void
```

**Parameters**

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

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

## Interfaces

### `AppearanceHostContractBackend`

Interface.

What the backend behind the host holds.

```ts
interface AppearanceHostContractBackend
```

**Properties**

- `stored` (`string | null`): The stored preferences blob, or `null` when nothing is stored (a first run).
- `themes` (`Readonly<Record<string, readonly Theme[]>>`): The extra themes per folder (a folder missing here has none).

Source: [ui/src/appearance/testing/contract.ts:42](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/testing/contract.ts#L42)

### `AppearanceHostContractControl`

Interface.

Reads the backend and changes it from outside.

```ts
interface AppearanceHostContractControl
```

**Properties**

- `boot?` (`() => BootSnapshot | null`): The snapshot the backend holds, or `null` (hosts with `boot`).
- `reopen` (`() => AppearanceHost`): A fresh host over the same backend: what a relaunch reads.
- `stored` (`() => string | null`): The blob the backend holds now.
- `storeExternally` (`(raw: string | null) => void`): Another window stored this blob (`null` clears it), announced as the backend does.
- `windowCalls?` (`() => readonly AppearanceHostContractWindowCall[]`): The window calls the backend saw, in order (hosts with `window`).

Source: [ui/src/appearance/testing/contract.ts:50](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/testing/contract.ts#L50)

### `AppearanceHostHarness`

Interface.

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

```ts
interface AppearanceHostHarness
```

**Properties**

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

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

## Types

### `AppearanceHostCapability`

Type.

An optional `AppearanceHost` member, by its path.

```ts
type AppearanceHostCapability =
  | 'themes'
  | 'boot'
  | 'window'
  | 'window.setBackground'
  | 'window.setZoom'
  | 'window.setNativeTheme'
```

Source: [ui/src/appearance/testing/contract.ts:23](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/testing/contract.ts#L23)

### `AppearanceHostContractWindowCall`

Type.

A window call the backend saw.

```ts
type AppearanceHostContractWindowCall =
  | { color: string; kind: 'background' }
  | { factor: number; kind: 'zoom' }
  | { kind: 'nativeTheme'; mode: AppearanceMode }
```

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

### `AppearanceHostHarnessFactory`

Type.

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

```ts
type AppearanceHostHarnessFactory = (backend: AppearanceHostContractBackend) => AppearanceHostHarness | Promise<AppearanceHostHarness>
```

Source: [ui/src/appearance/testing/contract.ts:74](https://github.com/Tahul/zidane/blob/main/ui/src/appearance/testing/contract.ts#L74)