Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/core-concepts/testing.mdx

View on GitHub
---
title: Testing
description: Test renderers, input, mouse, and frame output
order: 12
skill:
  entry: true
  intents: [testing, test-renderer, snapshots, frames]
---

# Testing

`@opentui/core/testing` provides a real `CliRenderer` backed by native in-memory output, plus deterministic input, mouse, clock, capability, highlighting, spy, and frame-recording helpers. It does not write to the host terminal by default.

## Test renderer

```typescript
import { createTestRenderer } from "@opentui/core/testing"
import { Text } from "@opentui/core"

const setup = await createTestRenderer({ width: 40, height: 10 })

try {
  setup.renderer.root.add(Text({ content: "Hello" }))
  await setup.renderOnce()

  console.log(setup.captureCharFrame())
} finally {
  setup.renderer.destroy()
}
```

`createTestRenderer(options)` requires an options object. `TestRendererOptions` extends `CliRendererConfig` and adds `width`, `height`, `kittyKeyboard`, and `otherModifiersMode`.

### Setup semantics and defaults

The helper constructs `CliRenderer` directly instead of calling `createCliRenderer()`/`setupTerminal()`. It therefore skips host-terminal raw mode and terminal setup while still creating the native renderer and applying its normal thread defaults.

| Setting              | Test default                                                                       |
| -------------------- | ---------------------------------------------------------------------------------- |
| `screenMode`         | `"main-screen"`                                                                    |
| `footerHeight`       | `12`                                                                               |
| `consoleMode`        | `"disabled"`                                                                       |
| `externalOutputMode` | `"passthrough"`                                                                    |
| `bufferedOutput`     | `"memory"`                                                                         |
| width                | `options.width`, custom `stdout.columns`, host `process.stdout.columns`, then `80` |
| height               | `options.height`, custom `stdout.rows`, host `process.stdout.rows`, then `24`      |

The legacy `kittyKeyboard: true` option maps to `useKittyKeyboard: { events: true }` and configures the mock key encoder. `otherModifiersMode` enables modifyOtherKeys-style sequences only when Kitty mode is off; Kitty mode takes precedence.

Tests own cleanup. Always call `setup.renderer.destroy()` in `finally` or test teardown. Use `createCliRenderer()` with custom `stdin`/`stdout` when the test must exercise the real output transport; the test renderer's default native destination is memory even when stream objects are supplied.

### Returned setup

| Member                              | Behavior                                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
| `renderer`                          | The `CliRenderer` instance (`TestRenderer` is a type alias)                                    |
| `mockInput`                         | Keyboard driver created by `createMockKeys()`                                                  |
| `mockMouse`                         | SGR mouse driver created by `createMockMouse()`                                                |
| `renderOnce()`                      | Wait for feed backpressure if present, then run one renderer loop pass                         |
| `flush(options?)`                   | Wait for visual idle; `maxPasses` defaults to `20`                                             |
| `waitFor(predicate, options?)`      | Retry a sync/async predicate for up to `maxPasses` (default `20`) while rendering can progress |
| `waitForFrame(predicate, options?)` | Retry against captured text and return the matching frame; default `maxPasses` is `20`         |
| `waitForVisualIdle(options?)`       | Wait for quiet native frames; defaults to `quietFrames: 1`, `maxFrames: 20`                    |
| `captureCharFrame()`                | Decode the current character buffer as text                                                    |
| `captureSpans()`                    | Return `{ cols, rows, cursor: [x, y], lines }` with styled spans                               |
| `externalOutput`                    | Recorder for split-footer external-output commits                                              |
| `getNativeStats()`                  | Return the current native render stats                                                         |
| `resize(width, height)`             | Invoke the renderer's test resize path                                                         |

Invalid/non-positive wait limits use their defaults; finite positive values are floored. Timeout errors include frame and scheduler diagnostics, and `waitForFrame()` also includes its last captured frame.

### Waiting for observable output

Use `renderOnce()` for explicitly controlled single-pass tests. Use `waitForFrame()` when application work schedules rendering asynchronously:

```typescript
const setup = await createTestRenderer({ width: 30, height: 5 })

try {
  setup.renderer.root.add(Text({ content: "Ready" }))

  const frame = await setup.waitForFrame((value) => value.includes("Ready"))
  console.log(frame)
} finally {
  setup.renderer.destroy()
}
```

`waitForVisualIdle()` considers a rendered frame quiet when native `cellsUpdated` is zero. It also returns when the scheduler has no running, rendering, or scheduled work. `flush()` is a convenience wrapper over this behavior.

### Styled frames

`captureCharFrame()` is convenient for snapshots and text assertions. `captureSpans()` preserves the current buffer dimensions, cursor coordinates, and each line's styled spans:

```typescript
const setup = await createTestRenderer({ width: 20, height: 4 })

try {
  setup.renderer.root.add(Text({ content: "Status", fg: "#22c55e" }))
  await setup.renderOnce()

  const captured = setup.captureSpans()
  console.log(captured.cols, captured.rows, captured.cursor, captured.lines)
} finally {
  setup.renderer.destroy()
}
```

### External output

The setup listens for `external_output` events and stores commits containing `text`, `rows`, snapshot `width`/`height`, `rowColumns`, `startOnNewLine`, and `trailingNewline`.

| Method                      | Behavior                                              |
| --------------------------- | ----------------------------------------------------- |
| `externalOutput.take()`     | Return all commits and clear the recorder             |
| `externalOutput.takeText()` | Consume all commits and join their rows with newlines |
| `externalOutput.clear()`    | Discard all commits                                   |

## Keyboard input

`createTestRenderer()` exposes its configured keyboard driver as `mockInput`. `createMockKeys(renderer, options?)` is also exported for an existing renderer.

```typescript
import { InputRenderable } from "@opentui/core"
import { KeyCodes, createTestRenderer } from "@opentui/core/testing"

const setup = await createTestRenderer({ width: 30, height: 4 })

try {
  const input = new InputRenderable(setup.renderer, { width: 20 })
  setup.renderer.root.add(input)
  input.focus()

  await setup.mockInput.typeText("hello")
  setup.mockInput.pressKey(KeyCodes.ARROW_LEFT)
  setup.mockInput.pressBackspace()
  await setup.renderOnce()
} finally {
  setup.renderer.destroy()
}
```

Keyboard methods:

| Method                              | Behavior                                       |
| ----------------------------------- | ---------------------------------------------- |
| `pressKey(key, modifiers?)`         | Emit one key synchronously                     |
| `pressKeys(keys, delayMs = 0)`      | Emit several keys, optionally delayed          |
| `typeText(text, delayMs = 0)`       | Emit the text one character at a time          |
| `pressEnter(modifiers?)`            | Emit return                                    |
| `pressEscape(modifiers?)`           | Emit escape                                    |
| `pressTab(modifiers?)`              | Emit tab; Shift+Tab uses the back-tab sequence |
| `pressBackspace(modifiers?)`        | Emit backspace                                 |
| `pressArrow(direction, modifiers?)` | Emit `"up"`, `"down"`, `"left"`, or `"right"`  |
| `pressCtrlC()`                      | Emit Ctrl+C                                    |
| `pasteBracketedText(text)`          | Emit bracketed-paste start, content, and end   |

Modifiers are `shift`, `ctrl`, `meta`, `super`, and `hyper`. `KeyCodes` contains return, linefeed, tab, backspace, delete, home/end, escape, four arrows, and F1-F12 sequences. `KeyInput` accepts a raw string or a `KeyCodes` key name. `pasteBytes(text)` is also exported for tests that need UTF-8 bytes without emitting input.

## Mouse input

`mockMouse` emits SGR mouse sequences through renderer stdin using zero-based test coordinates. `createMockMouse(renderer)` is also public.

```typescript
const setup = await createTestRenderer({ width: 40, height: 10 })

try {
  await setup.mockMouse.click(4, 2)
  await setup.mockMouse.drag(4, 2, 20, 6)
  await setup.mockMouse.scroll(20, 6, "down")

  console.log(setup.mockMouse.getCurrentPosition())
  console.log(setup.mockMouse.getPressedButtons())
} finally {
  setup.renderer.destroy()
}
```

Public operations are `moveTo`, `click`, `doubleClick`, `pressDown`, `release`, `drag`, `scroll`, `getCurrentPosition`, `getPressedButtons`, and low-level `emitMouseEvent`. Click, double-click, and drag default to 10 ms delays; drag emits five interpolated movement steps. Other operations default to no delay.

`MouseButtons` exports `LEFT` (0), `MIDDLE` (1), `RIGHT` (2), and wheel codes `WHEEL_UP` through `WHEEL_RIGHT` (64-67). Mouse modifiers are `shift`, `alt`, and `ctrl`.

## Terminal capabilities

Build a complete `TerminalCapabilities` fixture with partial overrides:

```typescript
import { createTerminalCapabilities, createTestRenderer, setRendererCapabilities } from "@opentui/core/testing"

const capabilities = createTerminalCapabilities({
  rgb: true,
  kitty_keyboard: true,
  terminal: { name: "test-terminal", version: "1" },
})

const setup = await createTestRenderer({ width: 20, height: 4 })

try {
  setRendererCapabilities(setup.renderer, capabilities)
} finally {
  setup.renderer.destroy()
}
```

The baseline has feature booleans disabled, `unicode: "unicode"`, `osc52_support: "unknown"`, `multiplexer: "none"`, `remote: false`, and empty terminal name/version with `from_xtversion: false`. `setRendererCapabilities()` replaces the test renderer's capability state and returns the complete object.

## ManualClock

`ManualClock` implements OpenTUI's clock interface without wall-clock waits. It starts at zero and supports `now`, `setTime`, timeout/interval scheduling and clearing, `advance`, and `runAll`.

```typescript
const { ManualClock } = await import("@opentui/core/testing")

const clock = new ManualClock()
let fired = false

clock.setTimeout(() => {
  fired = true
}, 100)

clock.advance(99)
console.log(fired) // false
clock.advance(1)
console.log(fired) // true
```

Times and delays are floored; negative delays advance by zero. Timers at the same timestamp fire in registration order. `setTime()` runs due timers when moving forward and directly changes time when moving backward. Use `runAll()` only when scheduled work is finite; a live interval continually reschedules itself.

## MockTreeSitterClient

`MockTreeSitterClient` subclasses `TreeSitterClient` without starting a worker. `highlightOnce()` remains pending until manually resolved or until an optional clock-backed auto-resolution timeout fires.

```typescript
const { MockTreeSitterClient } = await import("@opentui/core/testing")

const client = new MockTreeSitterClient()
client.setMockResult({ highlights: [[0, 5, "keyword"]] })

const pending = client.highlightOnce("const", "typescript")
client.resolveHighlightOnce()

try {
  console.log(await pending)
} finally {
  await client.destroy()
}
```

Public controls are `setMockResult`, `resolveHighlightOnce(index = 0)`, `resolveAllHighlightOnce`, and `isHighlighting`. `destroy()` resolves all pending highlights before normal client cleanup. Constructor options are `autoResolveTimeout` and `clock`.

## Spy

`createSpy()` returns a callable that records argument arrays:

```typescript
const { createSpy } = await import("@opentui/core/testing")

const spy = createSpy()
spy("saved", 3)

console.log(spy.calls)
console.log(spy.callCount())
console.log(spy.calledWith("saved", 3))
spy.reset()
```

`calledWith()` compares recorded and expected arguments through `JSON.stringify`; it is a small callback spy, not a test-framework mock replacement.

## TestRecorder

`TestRecorder` listens to renderer `frame` events and captures the character buffer after each native pass.

```typescript
import { Text } from "@opentui/core"
import { TestRecorder, createTestRenderer } from "@opentui/core/testing"

const setup = await createTestRenderer({ width: 20, height: 4 })
const recorder = new TestRecorder(setup.renderer, {
  recordBuffers: { fg: true, attributes: true },
})

try {
  recorder.rec()
  setup.renderer.root.add(Text({ content: "Recorded" }))
  await setup.renderOnce()
  recorder.stop()

  console.log(recorder.recordedFrames)
} finally {
  recorder.stop()
  setup.renderer.destroy()
}
```

`rec()` starts a new recording, clears previous frames, resets numbering to zero, and records a start timestamp. `stop()` detaches the listener. `clear()` empties frames and resets numbering. `recordedFrames` returns an array copy and `isRecording` reports current state.

Each exported `RecordedFrame` contains `frame`, elapsed `timestamp`, zero-based `frameNumber`, and optional copied buffers. Constructor options accept `recordBuffers: { fg?, bg?, attributes? }` and an injectable `now()` function. The barrel exports `TestRecorder` and `RecordedFrame`; the recorder's supporting option/buffer interfaces are not separate exports from `@opentui/core/testing`.

## Public export inventory

`@opentui/core/testing` exports:

- Renderer: `createTestRenderer` and the `TestRendererOptions`, `TestRenderer`, `TestRendererSetup`, `MockInput`, `MockMouse`, wait-option, and external-output types.
- Keyboard: `createMockKeys`, `pasteBytes`, `KeyCodes`, `KeyInput`, and `MockKeysOptions`.
- Mouse: `createMockMouse`, `MouseButtons`, `MouseButton`, `MousePosition`, `MouseModifiers`, `MouseEventType`, and `MouseEventOptions`.
- Tree-sitter: `MockTreeSitterClient`.
- Capabilities: `createTerminalCapabilities`, `setRendererCapabilities`, and `TerminalCapabilitiesOverrides`.
- General helpers: `createSpy`, `ManualClock`, `TestRecorder`, and `RecordedFrame`.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall