# zidane-ui/files/testing/contract

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

## Functions

### `describeFilesHostContract`

Function.

Declares the shared `FilesHost` suite for one implementation.

```ts
function describeFilesHostContract(
  name: string,
  makeHarness: FilesHostHarnessFactory,
  capabilities: readonly FilesHostCapability[],
): void
```

**Parameters**

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

Source: [ui/src/files/testing/contract.ts:112](https://github.com/Tahul/zidane/blob/main/ui/src/files/testing/contract.ts#L112)

## Interfaces

### `FilesHostContractBackend`

Interface.

What the backend behind the host holds.

```ts
interface FilesHostContractBackend
```

**Properties**

- `cwd` (`string`): The folder (absolute).
- `diff` (`string`): Its working tree against HEAD, as a unified patch.
- `files` (`Readonly<Record<string, string>>`): Its text files, by path relative to it.
- `status` (`readonly GitStatusEntry[]`): Its git status.

Source: [ui/src/files/testing/contract.ts:52](https://github.com/Tahul/zidane/blob/main/ui/src/files/testing/contract.ts#L52)

### `FilesHostContractControl`

Interface.

Reads the backend and changes it from outside.

```ts
interface FilesHostContractControl
```

**Properties**

- `edit` (`(path: string, text: string) => void`): Another writer changed a file (its version moves).
- `file` (`(path: string) => string | undefined`): A file's text in the backend now, or `undefined`.
- `touch?` (`() => void`): The folder may have changed (a tool result in it): watchers hear it. Required with `watch`.

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

### `FilesHostHarness`

Interface.

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

```ts
interface FilesHostHarness
```

**Properties**

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

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

## Types

### `FilesHostCapability`

Type.

An optional `FilesHost` member.

```ts
type FilesHostCapability =
  | 'list'
  | 'read'
  | 'write'
  | 'entries'
  | 'search'
  | 'gitStatus'
  | 'workingTreeDiff'
  | 'watch'
  | 'editorPrefs'
  | 'diagnostics'
  | 'lsp'
  | 'system'
  | 'mediaUrl'
```

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

### `FilesHostHarnessFactory`

Type.

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

```ts
type FilesHostHarnessFactory = (backend: FilesHostContractBackend) => FilesHostHarness | Promise<FilesHostHarness>
```

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