# zidane-ui/workspace/testing/contract

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

## Functions

### `describeWorkspaceHostContract`

Function.

Declares the shared `WorkspaceHost` suite for one implementation.

```ts
function describeWorkspaceHostContract<S extends WorkspaceScope>(
  name: string,
  makeHarness: WorkspaceHostHarnessFactory<S>,
  capabilities: readonly WorkspaceHostCapability[],
): void
```

**Type parameters**

- `S` (`extends WorkspaceScope`)

**Parameters**

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

Source: [ui/src/workspace/testing/contract.ts:115](https://github.com/Tahul/zidane/blob/main/ui/src/workspace/testing/contract.ts#L115)

## Interfaces

### `WorkspaceHostContractBackend`

Interface.

What the backend behind the host holds.

```ts
interface WorkspaceHostContractBackend
```

**Properties**

- `content` (`Readonly<Record<string, PanelContent>>`): Each panel's content, by id; a panel missing here fails to load.
- `cwd` (`string`): The folder the extension panels are offered in (no other folder offers any).
- `failingAction` (`{ actionId: string; message: string; panelId: string }`): The one action that fails, with the extension's words; every other action succeeds.
- `layouts` (`Readonly<Record<string, WorkspaceLayout>>`): The layouts stored per scope key (a key missing here has nothing stored).
- `panels` (`readonly WorkspacePanelSummary[]`): The extension panels offered in `cwd`.

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

### `WorkspaceHostContractControl`

Interface.

Changes the backend from outside and announces it as the backend does.

```ts
interface WorkspaceHostContractControl
```

**Properties**

- `changeCatalog` (`() => void`): An extension loaded or left: the catalog may have changed.
- `changePanel` (`(cwd: string, panelId: string) => void`): A panel's content changed in `cwd`.
- `writeLayout` (`(key: string, layout: WorkspaceLayout) => void`): Another window stored `layout` for the scope `key`.

Source: [ui/src/workspace/testing/contract.ts:51](https://github.com/Tahul/zidane/blob/main/ui/src/workspace/testing/contract.ts#L51)

### `WorkspaceHostHarness`

Interface.

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

```ts
interface WorkspaceHostHarness<S extends WorkspaceScope = WorkspaceScope>
```

**Type parameters**

- `S` (`extends WorkspaceScope`, default `WorkspaceScope`)

**Properties**

- `control` (`WorkspaceHostContractControl`): Changes the backend from outside.
- `host` (`WorkspaceHost<S>`): The host under test.
- `dispose?` (`() => void`): Closes connections and timers after each test.
- `scope` (`(key: string) => S`): The scope the host takes for a scope key.

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

## Types

### `WorkspaceHostCapability`

Type.

An optional `WorkspaceHost` member, by its path.

```ts
type WorkspaceHostCapability =
  | 'layouts'
  | 'panels'
  | 'panels.watch'
  | 'panels.subscribe'
  | 'panels.subscribeCatalog'
```

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

### `WorkspaceHostHarnessFactory`

Type.

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

```ts
type WorkspaceHostHarnessFactory<S extends WorkspaceScope = WorkspaceScope> = (backend: WorkspaceHostContractBackend) => WorkspaceHostHarness<S> | Promise<WorkspaceHostHarness<S>>
```

**Type parameters**

- `S` (`extends WorkspaceScope`, default `WorkspaceScope`)

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