# zidane-ui/git/testing/contract

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

## Functions

### `describeGitHostContract`

Function.

Declares the shared `GitHost` suite for one implementation.

```ts
function describeGitHostContract(
  name: string,
  makeHarness: GitHostHarnessFactory,
  capabilities: readonly GitHostCapability[],
): void
```

**Parameters**

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

Source: [ui/src/git/testing/contract.ts:265](https://github.com/Tahul/zidane/blob/main/ui/src/git/testing/contract.ts#L265)

## Interfaces

### `GitHostContractBackend`

Interface.

What the backend behind the host holds, and what it does with each action.

```ts
interface GitHostContractBackend
```

**Properties**

- `branches` (`GitBranch[]`): Local branches, most recent first. The first is checked out.
- `branchPullRequests` (`Record<string, GitBranchPullRequest>`): The open pull request per branch. Branches left out have none.
- `cloned` (`{ input: string; parent: string }[]`): Clones that ran: what was cloned, and where.
- `current` (`string`): The current branch. Switches and new branches land here.
- `cwd` (`string`): The checkout's folder.
- `environments` (`EnvironmentDescriptor[]`): The environment kinds for `cwd`.
- `existsMessage` (`string`): Creating a branch that exists fails with this message.
- `folders` (`{ existsMessage: string; outsideMessage: string; roots: string[]; tree: Record<string, string[]> }`): The remote host's folders: its roots, and the folders under each path. A path outside the roots is refused with
  `outsideMessage`; a new folder whose name is taken, with `existsMessage`. New folders land in `tree`.
- `held` (`{ branch: string; chats: string[]; message: string; worktree: string }`): A branch another worktree has checked out: switching to it is refused with git's message, the worktree and its chats.
- `hostId` (`string`): The saved server whose folders `listFolders` lists (hosts that reach several pass it on).
- `moves` (`{ branch?: string; sessionId: string }[]`): Sessions moved into worktrees land here.
- `origins` (`Record<string, string>`): The `origin` URL of each checkout on this computer. Other folders have none.
- `pickedFolder` (`string`): What the native folder dialog answers.
- `pullRequests` (`GitPullRequest[]`): Open pull requests. A search answers the ones `prMatches` finds.
- `relocations` (`{ branch?: string; cwd?: string; kind: string; sessionId: string }[]`): Sessions moved anywhere (`moveSession`) land here: where, and in which folder.
- `repo` (`{ defaultParent: string; info: GitRepoInfo; input: string; progress: GitCloneProgress[]; refusedInput: string; refusedMessage: string; spec: GitRepoSpec }`): The repository import: what `repo.input` parses to, where clones land by default, the progress a clone reports, and a refused input.
- `serverClones` (`{ hostId: string; input: string; parent: string }[]`): Clones that ran on a server: which server, what, and where.
- `sessionId` (`string`): A session in that folder.
- `status` (`GitStatus`): The checkout's status.
- `sync` (`{ conflictCwd: string; conflictMessage: string; conflicts: string[] }`): What a sync does: it pulls `behind` and pushes `ahead` of `status`. Syncing `conflictCwd` fails with `conflictMessage` and `conflicts`.
- `synced` (`string[]`): Syncs that ran, by folder.

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

### `GitHostHarness`

Interface.

A host built over a backend, and what the suite drives on it.

```ts
interface GitHostHarness
```

**Properties**

- `host` (`GitHost`): The host under test.
- `activity?` (`(sessionId: string) => void`): Has the backend report work by a session that may have moved its checkout (needed for `subscribeActivity`).
- `changeEnvironments?` (`() => void`): Has the backend announce that the environment kinds may have changed (needed for `subscribeEnvironments`).
- `dispose?` (`() => void`): Closes connections and timers after each test.
- `moveRefs?` (`() => void`): Has the backend announce that the checkout's refs moved (needed for `subscribeRefs`).

Source: [ui/src/git/testing/contract.ts:136](https://github.com/Tahul/zidane/blob/main/ui/src/git/testing/contract.ts#L136)

## Types

### `GitHostCapability`

Type.

An optional `GitHost` member.

```ts
type GitHostCapability =
  | 'branches'
  | 'pullRequests'
  | 'checkout'
  | 'createBranch'
  | 'startWorktree'
  | 'moveSession'
  | 'environments'
  | 'subscribeEnvironments'
  | 'status'
  | 'subscribeRefs'
  | 'listFolders'
  | 'pickFolder'
  | 'subscribeActivity'
  | 'branchPullRequest'
  | 'sync'
  | 'clone'
  | 'createFolder'
  | 'searchFolders'
  | 'originUrl'
  | 'cloneOnServer'
```

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

### `GitHostHarnessFactory`

Type.

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

```ts
type GitHostHarnessFactory = (backend: GitHostContractBackend) => GitHostHarness | Promise<GitHostHarness>
```

Source: [ui/src/git/testing/contract.ts:150](https://github.com/Tahul/zidane/blob/main/ui/src/git/testing/contract.ts#L150)