# zidane-ui/machines/testing/contract Import: `import { … } from 'zidane-ui/machines/testing/contract'`. Source: [ui/src/machines/testing/contract.ts](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/contract.ts). ## Functions ### `describeMachinesHostContract` Function. Declares the shared `MachinesHost` suite for one implementation. ```ts function describeMachinesHostContract( name: string, makeHarness: MachinesHostHarnessFactory, capabilities: readonly MachinesHostCapability[], ): void ``` **Parameters** - `name` (`string`): The implementation's name, shown in the suite title. - `makeHarness` (`MachinesHostHarnessFactory`): Builds a fresh host over a backend that holds and records what it is given, once per test. - `capabilities` (`readonly MachinesHostCapability[]`): The optional members the host offers. Every other optional member must be undefined. Source: [ui/src/machines/testing/contract.ts:327](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/contract.ts#L327) ### `describeMachinesSyncContract` Function. Declares the shared suite of `MachinesHost.sync` and `signIn` for one implementation. ```ts function describeMachinesSyncContract( name: string, makeHarness: MachinesSyncHarnessFactory, capabilities: readonly MachinesSyncCapability[], ): void ``` **Parameters** - `name` (`string`): The implementation's name, shown in the suite title. - `makeHarness` (`MachinesSyncHarnessFactory`): Builds a fresh host over a backend that holds and records what it is given, once per test. - `capabilities` (`readonly MachinesSyncCapability[]`): The members the host offers. Every other one must be undefined. Source: [ui/src/machines/testing/sync.contract.ts:139](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/sync.contract.ts#L139) ## Interfaces ### `MachinesHostContractBackend` Interface. What the backend behind the host holds, and what it records. ```ts interface MachinesHostContractBackend ``` **Properties** - `capabilities` (`HostCapabilities`): What the server can do. The backend counts the probes that asked to refresh in `capabilityRefreshes`. - `capabilityRefreshes` (`number`): How many capability reads asked for a fresh probe. - `daemon` (`DaemonStatus`): The local daemon's status. - `folder` (`string`): The folder the native dialog answers. - `installs` (`string[]`): The tools an install was asked for, in order. - `links` (`MachineLinksStatus`): This computer's links. Read at each status; the link recorders change it. - `machines` (`MachineInfo[]`): The server's machines. Read at each listing; the harness changes a status before it pushes. - `presence` (`SessionPresence[]`): Every live session's presence. Read at each listing; the harness changes it before it pushes. - `server` (`{ addedAt: number; id: string; lastConnectedAt: number; name: string; url: string; version: string }`): The server under test, as its backend reports it. Its id is the one the suite passes to the host; the registry (`savedHosts`) lists it with its dates. - `tokens` (`ServerToken[]`): The server's tokens. Read at each listing; `created` and `revoked` change it. - `update` (`ServerUpdateStatus`): The server's self-update. Read at each status; `updated` changes it. - `added` (`(input: { name?: string; token: string; url: string }) => HostCheckResult`): The backend calls this when an add reaches it. - `created` (`(name: string, scope: ServerTokenScope) => ServerToken & { token: string }`): The backend calls this when a token is created, and answers with what it returns. - `daemonCalled` (`(action: 'restart' | 'reconnect' | 'stopRun' | 'relaunchApp', detail?: unknown) => void`): The backend calls this when a daemon action reaches it. - `forgot` (`(machineId: string) => void`): The backend calls this when a forget reaches it: the machine leaves `machines`. - `invited` (`(params: { name?: string; ttlMs?: number }) => { code: string; expiresAt: number }`): The backend calls this when a join code is asked for, and answers with what it returns. - `linked` (`(action: 'shareStart' | 'shareStop' | 'useServer', detail?: unknown) => void`): The backend calls this when a link action reaches it: `links` changes. - `removed` (`(id: string) => void`): The backend calls this when a removal reaches it. - `renamed` (`(id: string, name: string) => HostCheckResult`): The backend calls this when a rename reaches it. - `retried` (`(hostId: string) => void`): The backend calls this when a retry reaches it. - `revoked` (`(id: string) => void`): The backend calls this when a revoke reaches it. - `tested` (`(target: { id: string } | { token: string; url: string }) => HostCheckResult`): The backend calls this when a test reaches it, and answers with what it returns. - `updated` (`(action: 'check' | 'install' | 'configure', enabled?: boolean) => void`): The backend calls this when an update action reaches it: `update` changes. - `urlChanged` (`(id: string, url: string) => HostCheckResult`): The backend calls this when a URL change reaches it. Source: [ui/src/machines/testing/contract.ts:121](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/contract.ts#L121) ### `MachinesHostHarness` Interface. A host built over a contract backend, and the pushes its backend can make. ```ts interface MachinesHostHarness ``` **Properties** - `host` (`MachinesHost`): The host under test. - `dispose?` (`() => void`): Closes connections and listeners after each test. - `pushMachineStatus` (`(machineId: string, status: 'online' | 'offline') => void`): Sets a machine's status in the backend and pushes the change, as the backend does. - `pushPresence?` (`(sessions: SessionPresence[]) => void`): Sets the backend's presence and pushes the snapshot, as the backend does (needed for `presence`). - `pushTokenCreated?` (`(name: string) => void`): Adds a token elsewhere (another page, the CLI) and says so, as the backend does (needed for `tokens.onChanged`). Source: [ui/src/machines/testing/contract.ts:176](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/contract.ts#L176) ### `MachinesSyncContractBackend` Interface. What the backend behind the host holds, and what it records. ```ts interface MachinesSyncContractBackend ``` **Properties** - `fail` (`string | null`): When set, every action fails with this message. - `providers` (`HostProviderAuth[]`): The server's providers. - `server` (`{ id: string; name: string }`): The server under test. Its id is the one the suite passes to the host. - `signInUrl` (`string`): The page a sign-in opens. - `state` (`HostSyncState`): This computer's sync to the server. Read at each state read; the recorders change it. - `status` (`SyncStatus`): The server's record. Read at each status read; `reset` changes it. - `configured` (`(patch: HostSyncPatch) => void`): The backend calls this when a configure reaches it: `state` changes. - `pushed` (`() => void`): The backend calls this when a push reaches it. - `reset` (`(field: string) => void`): The backend calls this when a reset reaches it: the override leaves `status`. - `signedIn` (`(target: HostSignInTarget) => void`): The backend calls this when a sign-in starts. - `tookOver` (`() => void`): The backend calls this when a take over reaches it. Source: [ui/src/machines/testing/sync.contract.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/sync.contract.ts#L36) ### `MachinesSyncHarness` Interface. A host built over a contract backend, and the pushes its backend can make. ```ts interface MachinesSyncHarness ``` **Properties** - `host` (`MachinesHost`): The host under test. - `dispose?` (`() => void`): Closes connections and listeners after each test. - `pushSyncChanged?` (`() => void`): Tells the host the sync of the server changed, as the backend does (needed for `sync.state` live reads). Source: [ui/src/machines/testing/sync.contract.ts:62](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/sync.contract.ts#L62) ## Types ### `MachinesHostCapability` Type. An optional `MachinesHost` member, by its path. ```ts type MachinesHostCapability = | 'hosts' | 'refreshHosts' | 'retry' | 'testHost' | 'addHost' | 'renameHost' | 'setHostUrl' | 'removeHost' | 'savedHosts' | 'machines' | 'machines.forget' | 'machines.invite' | 'links' | 'links.shareStart' | 'links.shareStop' | 'links.useServer' | 'pickFolder' | 'updates' | 'updates.check' | 'updates.install' | 'updates.configure' | 'tokens' | 'tokens.create' | 'tokens.revoke' | 'tokens.onChanged' | 'daemon' | 'daemon.reconnect' | 'daemon.restart' | 'daemon.stopRun' | 'daemon.relaunchApp' | 'presence' | 'capabilities' | 'installTool' | 'permitted' ``` Source: [ui/src/machines/testing/contract.ts:35](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/contract.ts#L35) ### `MachinesHostHarnessFactory` Type. Builds a fresh host (and its backend) for one test. ```ts type MachinesHostHarnessFactory = (backend: MachinesHostContractBackend) => MachinesHostHarness | Promise ``` Source: [ui/src/machines/testing/contract.ts:190](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/contract.ts#L190) ### `MachinesSyncCapability` Type. A member of `MachinesHost.sync`, or `signIn`, by its path. ```ts type MachinesSyncCapability = | 'sync' | 'sync.state' | 'sync.configure' | 'sync.push' | 'sync.takeOver' | 'sync.reset' | 'sync.providers' | 'signIn' ``` Source: [ui/src/machines/testing/sync.contract.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/sync.contract.ts#L21) ### `MachinesSyncHarnessFactory` Type. Builds a fresh host (and its backend) for one test. ```ts type MachinesSyncHarnessFactory = (backend: MachinesSyncContractBackend) => MachinesSyncHarness | Promise ``` Source: [ui/src/machines/testing/sync.contract.ts:72](https://github.com/Tahul/zidane/blob/main/ui/src/machines/testing/sync.contract.ts#L72)