Skip to content
zidane
UI kit reference

zidane-ui/extensions/testing/contract

import { … } from 'zidane-ui/extensions/testing/contract'ui/src/extensions/testing/contract.ts

Functions#

describeExtensionsHostContractFunction#

Declares the shared ExtensionsHost suite for one implementation.

TypeScript
function describeExtensionsHostContract(
  name: string,
  makeHarness: ExtensionsHostHarnessFactory,
  capabilities: readonly ExtensionsHostCapability[],
): void

Parameters

Parameters
NameTypeDescription
namestring

The implementation's name, shown in the suite title.

makeHarnessExtensionsHostHarnessFactory

Builds a fresh host over a backend that does what it is given, once per test.

capabilitiesreadonly ExtensionsHostCapability[]

The optional members the host offers. Every other optional member must be undefined.

ui/src/extensions/testing/contract.ts:187

Constants#

CONTRACT_GOOD_KEYConstant#

The API key the backend's integrations accept.

TypeScript
const CONTRACT_GOOD_KEY = 'good-key'

ui/src/extensions/testing/contract.ts:105

CONTRACT_STOREConstant#

The store the storage tests read and write.

TypeScript
const CONTRACT_STORE: ExtensionStoreRef

ui/src/extensions/testing/contract.ts:103

Interfaces#

ExtensionsHostContractBackendInterface#

What the backend behind the host holds and does.

TypeScript
interface ExtensionsHostContractBackend

Properties

ExtensionsHostContractBackend properties
NameTypeDescription
callbacks{ 'badge.menu'?: (args: { target: BadgeTarget }) => readonly BadgeMenuItem[]; 'badge.run'?: (args: { actionId: string; cwd?: string; sessionId?: string; source: string; target: BadgeTarget }) => BadgeActionEffect; 'panel.action'?: (args: { actionId: string; context?: unknown; cwd: string; panelId: string; payload?: unknown }) => boolean; 'panel.load'?: (args: { context?: unknown; cwd: string; panelId: string }) => PanelContent; 'reference.resolve'?: (args: { key: string; providerId: string }) => ExtensionReferenceView | null; 'setting.action'?: (args: { key: string; pageId: string }) => { message?: string; patch?: Readonly<Record<string, string | number | boolean | readonly string[]>>; tone?: 'error' | 'success' | 'warn' | 'info' } | undefined; 'setting.status'?: (args: { key: string; pageId: string }) => { text: string; tone?: 'error' | 'muted' | 'success' | 'warn' } | undefined }

What each callback answers. A callback that throws answers failed with its message.

commandsreadonly ExtensionCommandWire[]

The commands. Running an unknown id answers false.

integrationsreadonly ExtensionIntegrationWire[]

The integrations. connect with the key CONTRACT_GOOD_KEY adds the account demo (the first connection becomes the default); any other key is refused (refused / invalid). disconnect removes one account, or all with none named; setDefault moves an account first and makes it the default. The list keeps the default first, the only one with isDefault, also as connection.

itemsreadonly ExtensionItem<keyof ExtensionWireMap>[]

The items there at the start.

rpcReadonly<Record<string, Readonly<Record<string, ContractRpcMethod>>>>

RPC methods, by contract then method.

settingsExtensionSettingsWire

The settings. The backend refuses a write to a locked key (refused / locked).

storeValueunknown

The stored value of CONTRACT_STORE.

ui/src/extensions/testing/contract.ts:44

ExtensionsHostContractControlInterface#

Drives the backend from outside.

TypeScript
interface ExtensionsHostContractControl

Properties

ExtensionsHostContractControl properties
NameTypeDescription
dialog(request: DialogRequest, ctx: { extensionId: string; sessionId?: string; signal?: AbortSignal }) => Promise<unknown>

An extension asked for a dialog routed to this client; resolves with the answer.

effect(effect: ExtensionUiEffect) => Promise<ExtensionUiEffectResult>

An extension's ctx.ui / ctx.composer call routed to this client; resolves with what the app settled.

ran() => readonly { args?: string; id: string; sessionId?: string }[]

The commands the backend ran.

readStore() => unknown

CONTRACT_STORE's value in the backend now.

remove(key: string) => void

An extension withdrew an item.

upsert(entry: ExtensionItem) => void

An extension added or changed an item.

writeStore(value: unknown) => void

Another client wrote CONTRACT_STORE.

ui/src/extensions/testing/contract.ts:67

ExtensionsHostHarnessInterface#

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

TypeScript
interface ExtensionsHostHarness

Properties

ExtensionsHostHarness properties
NameTypeDescription
controlExtensionsHostContractControl

Drives the backend the host talks to.

hostExtensionsHost

The host under test.

dispose?() => void

Tears the host and its backend down after the test.

ui/src/extensions/testing/contract.ts:88

Types#

ContractRpcMethodType#

A scripted RPC method: returns its output, or throws { type, message, data? } to answer that error.

TypeScript
type ContractRpcMethod = (input: unknown) => unknown

ui/src/extensions/testing/contract.ts:41

ExtensionsHostCapabilityType#

An optional ExtensionsHost member. settings.set is the settings' write.

TypeScript
type ExtensionsHostCapability =
  | 'invoke'
  | 'dialogs'
  | 'effects'
  | 'rpc'
  | 'storage'
  | 'settings'
  | 'settings.set'
  | 'integrations'
  | 'commands'

ui/src/extensions/testing/contract.ts:35

ExtensionsHostHarnessFactoryType#

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

TypeScript
type ExtensionsHostHarnessFactory = (backend: ExtensionsHostContractBackend) => ExtensionsHostHarness | Promise<ExtensionsHostHarness>

ui/src/extensions/testing/contract.ts:98