Types

MountTarget type # line 17287

Added in 2.1.275 · changed in 2.1.277

What $.ui.mount takes: whose elements the test will act on, the surface that draws, and the component instance the engine asks the plugins for.

The envelope a ui.render hook sees as e (surface, component, requestId, viewport, props) plus plugin. surface is never defaulted: one body run over several surfaces is what shows independence.

$.ui.mount({ plugin: 'notes', surface, component: 'Pane', props: PANE })

  export type MountTarget<P extends RenderSurface = RenderSurface, C extends RenderComponent = RenderComponent> = {
      /**
       * Whose elements the handle's acts address by bare `key`: the plugin
       * under test, usually. An act names another plugin to reach its element.
       */
      plugin: string;
      /**
       * What draws: its element table validates every tree the plugins
       * return, and every dispatch the handle raises carries it as `e.surface`.
       *
       * One of `terminal`, `desktop`, `vscode`, `mobile`.
       */
      surface: P;
      /**
       * Which component the engine asks the plugins to draw (`Pane`,
       * `AbovePrompt`, `ToolUse`, ...): what a `ui.render` matcher narrows on.
       */
      component: C;
      /**
       * The component's props, what the hook reads as `e.props`.
       */
      props: RenderPropsOf[C];
      /**
       * The instance drawn (a pane's id, a tool row's tool_use_id); one is
       * minted when absent. Two mounts of one component are two instances.
       */
      requestId?: string;
      /**
       * What the surface measured, as the hook reads it under `e.viewport`;
       * absent when the surface has not measured, as on `e`.
       *
       * Cells across and down in the surface's monospace metric and whether it
       * docks a pane. A `Client` in the drawing starts laid out at this size
       * (0 by 0 when absent) until the handle's `resize` lays its region out.
       */
      viewport?: RenderViewport;
  };

Negatable type # line 17328

Added in 2.1.271

A set of checks and, under not, the same set passing where they fail.

  export type Negatable<M> = M & {
      /**
       * The checks negated.
       */
      not: M;
  };

Plugin type # line 17342

Added in 2.1.271

Written inline in a test and loaded as a plugin folder is: its name, the tier it loads in (user when not given), and its hooks module's register.

register is written register(on) { ... } and is self-contained, as a module's is: it closes over nothing of the test file.

  export type Plugin = {
      name: string;
      tier?: PluginTier;
      register: Register;
  };

PluginTier type # line 17351

Added in 2.1.271

A tier a plugin loads in: every tier but the engine's own.

  export type PluginTier = Exclude<Tier, 'core'>;

PressTarget type # line 17357

Added in 2.1.271 · changed in 2.1.274, 2.1.277

What $.ui.press takes: the plugin whose ui.render hook drew the element, the key it gave it, the instance and surface when several, a link.

  export type PressTarget = {
      plugin: string;
      key: string;
      /**
       * Which instance holds it, when the plugin drew the key in several.
       */
      requestId?: string;
      /**
       * Which surface's drawing, when the key is drawn on more than one; the
       * press carries the surface of the drawing it lands in either way.
       */
      surface?: RenderSurface;
      /**
       * For a Markdown answering its links: which of them the press lands on.
       */
      link?: PressedLink;
  };

SelectTarget type # line 17379

Added in 2.1.280

What $.ui.select takes: the plugin whose hook drew the Select, its key, the picked option's value, instance and surface when several.

  export type SelectTarget = {
      plugin: string;
      key: string;
      /**
       * Which option is picked, by the `value` the Select listed it under.
       */
      value: string;
      /**
       * Which instance holds it, when the plugin drew the key in several.
       */
      requestId?: string;
      /**
       * Which surface's drawing, when the key is drawn on more than one; the
       * pick carries the surface of the drawing it lands in either way.
       */
      surface?: RenderSurface;
  };

test const # line 17408

Added in 2.1.271

One test: it passes when its body returns or resolves, and fails when it throws, rejects or outlasts its time (5000 ms, or timeoutMs).

The body gets the engine's $ and an on whose hooks sit beneath every plugin; plugins load inline plugins beside the one under test. A failure carries what the engine reported meanwhile: each hook it skipped, and why.

name

the test's name, led in its title by the describes around it

rest

the body, ($, on) => ..., or the options then the body

  export const test: (name: string, ...rest: TestRest) => void;

TestBody type # line 17418

Added in 2.1.271

A test: the engine's $, and on, a plugin's registrar, whose hooks sit beneath every plugin; beneath them the bottom hook throws, naming its event.

A test registers its hooks before its first call on $, which loads the plugins. Beneath $.state, a render's $.ui.invalidate and session.append the kit answers. A check that fails in a hook, or a refused answer, fails it.

  export type TestBody = ($: Engine, on: On) => unknown;

TestOptions type # line 17426

Added in 2.1.271 · changed in 2.1.284

What test takes beside its name: the inline plugins it loads beside the one under test, and how long it may run (5000 ms when not given).

Also the plugin under test's userConfig values.

  export type TestOptions = {
      plugins?: readonly Plugin[];
      timeoutMs?: number;
      /**
       * The plugin under test's `userConfig` values, standing as the ones
       * stored in settings.
       *
       * `register(on, options)` receives them as a load does: unlisted values
       * unset, defaults filled in, then validated, a bad required field failing
       * the load. Left out: the manifest's defaults. Inline plugins get none.
       *
       * @example
       * test('greets', { options: { greeting: 'yo' } }, body)
       */
      options?: PluginOptions;
  };

TestRest type # line 17446

Added in 2.1.271

What follows a test's name: its body, or its options then its body.

  export type TestRest = readonly [body: TestBody] | readonly [options: TestOptions, body: TestBody];

ThrowExpectation type # line 17452

Added in 2.1.271

What toThrow compares the thrown error with: a substring or pattern of its message, its class, a value carrying the whole message, or nothing.

  export type ThrowExpectation = string | RegExp | Constructor | WithMessage;

tier const # line 17460

Added in 2.1.271

Says which tier the plugin under test loads in, once, at the top of the file: prepend, user (when unsaid), append or builtin.

tier

the tier

  export const tier: (tier: PluginTier) => void;

WithMessage type # line 17465

Added in 2.1.271

An error-like value toThrow compares by its whole message.

  export type WithMessage = {
      message: string;
  };