@xincli/opentui-core 0.4.6

package/src/testing/test-renderer.ts

@@ -0,0 +1,375 @@
+import {
+  CliRenderer,
+  CliRenderEvents,
+  type CliRendererConfig,
+  type CliRendererExternalOutputEvent,
+  type CliRendererFrameEvent,
+} from "../renderer.js"
+import type { NativeSpanFeed } from "../NativeSpanFeed.js"
+import type { NativeRenderStats } from "../zig.js"
+import { createMockKeys } from "./mock-keys.js"
+import { createMockMouse } from "./mock-mouse.js"
+import { createTestStdin, createTestStdout } from "./test-streams.js"
+import type { CapturedFrame } from "../types.js"
+
+export interface TestRendererOptions extends CliRendererConfig {
+  width?: number
+  height?: number
+  kittyKeyboard?: boolean
+  otherModifiersMode?: boolean
+}
+export type TestRenderer = CliRenderer
+export type MockInput = ReturnType<typeof createMockKeys>
+export type MockMouse = ReturnType<typeof createMockMouse>
+
+type RendererFeedAccess = {
+  _feed?: NativeSpanFeed | null
+}
+
+export interface TestFlushOptions {
+  maxPasses?: number
+}
+
+export interface TestVisualIdleOptions {
+  quietFrames?: number
+  maxFrames?: number
+}
+
+export interface TestWaitForOptions {
+  maxPasses?: number
+}
+
+export interface TestExternalOutputCommit {
+  text: string
+  rows: string[]
+  width: number
+  height: number
+  rowColumns: number
+  startOnNewLine: boolean
+  trailingNewline: boolean
+}
+
+export interface TestExternalOutput {
+  take(): TestExternalOutputCommit[]
+  takeText(): string
+  clear(): void
+}
+
+export interface TestRendererSetup {
+  renderer: TestRenderer
+  mockInput: MockInput
+  mockMouse: MockMouse
+  renderOnce: () => Promise<void>
+  flush: (options?: TestFlushOptions) => Promise<void>
+  waitFor: (predicate: () => boolean | Promise<boolean>, options?: TestWaitForOptions) => Promise<void>
+  waitForFrame: (
+    predicate: (frame: string) => boolean | Promise<boolean>,
+    options?: TestWaitForOptions,
+  ) => Promise<string>
+  waitForVisualIdle: (options?: TestVisualIdleOptions) => Promise<void>
+  externalOutput: TestExternalOutput
+  getNativeStats: () => NativeRenderStats
+  captureCharFrame: () => string
+  captureSpans: () => CapturedFrame
+  resize: (width: number, height: number) => void
+}
+
+const decoder = new TextDecoder()
+const DEFAULT_MAX_PASSES = 20
+const DEFAULT_MAX_VISUAL_IDLE_FRAMES = 20
+const DEFAULT_QUIET_FRAMES = 1
+
+async function drainImmediateWork(): Promise<void> {
+  await Promise.resolve()
+  await new Promise<void>((resolve) => process.nextTick(resolve))
+  await Promise.resolve()
+}
+
+function normalizePositiveInteger(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return fallback
+  }
+
+  return Math.floor(value)
+}
+
+function createWaitError(renderer: TestRenderer, message: string, frame?: string): Error {
+  const stats = renderer.getStats()
+  const scheduler = renderer.getSchedulerState()
+  const details = [
+    message,
+    `frameId: ${renderer.frameId}`,
+    `nativeFrameCount: ${stats.nativeFrameCount}`,
+    `cellsUpdated: ${stats.cellsUpdated}`,
+    `isRunning: ${scheduler.isRunning}`,
+    `isRendering: ${scheduler.isRendering}`,
+    `hasScheduledRender: ${scheduler.hasScheduledRender}`,
+  ]
+
+  if (frame !== undefined) {
+    details.push(`lastFrame:\n${frame}`)
+  }
+
+  return new Error(details.join("\n"))
+}
+
+class TestExternalOutputRecorder implements TestExternalOutput {
+  private commits: TestExternalOutputCommit[] = []
+
+  constructor(renderer: TestRenderer) {
+    renderer.on(CliRenderEvents.EXTERNAL_OUTPUT, this.record)
+    renderer.once(CliRenderEvents.DESTROY, () => {
+      renderer.off(CliRenderEvents.EXTERNAL_OUTPUT, this.record)
+    })
+  }
+
+  private record = (event: CliRendererExternalOutputEvent): void => {
+    const raw = decoder.decode(event.snapshot.getRealCharBytes(false))
+    const rows = Array.from({ length: event.snapshot.height }, (_, index) =>
+      raw.slice(index * event.snapshot.width, (index + 1) * event.snapshot.width).trimEnd(),
+    )
+
+    this.commits.push({
+      text: rows.join("\n"),
+      rows,
+      width: event.snapshot.width,
+      height: event.snapshot.height,
+      rowColumns: event.rowColumns,
+      startOnNewLine: event.startOnNewLine,
+      trailingNewline: event.trailingNewline,
+    })
+  }
+
+  public take(): TestExternalOutputCommit[] {
+    const commits = this.commits
+    this.commits = []
+    return commits
+  }
+
+  public takeText(): string {
+    return this.take()
+      .flatMap((commit) => commit.rows)
+      .join("\n")
+  }
+
+  public clear(): void {
+    this.commits = []
+  }
+}
+
+function waitForNextFrameOrIdle(renderer: TestRenderer): Promise<CliRendererFrameEvent | null> {
+  const scheduler = renderer.getSchedulerState()
+  if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
+    return Promise.resolve(null)
+  }
+
+  return new Promise((resolve) => {
+    let settled = false
+
+    const cleanup = () => {
+      renderer.off(CliRenderEvents.FRAME, onFrame)
+      renderer.off(CliRenderEvents.DESTROY, onDestroy)
+    }
+
+    const finish = (event: CliRendererFrameEvent | null) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve(event)
+    }
+
+    const onFrame = (event: CliRendererFrameEvent) => {
+      finish(event)
+    }
+
+    const onDestroy = () => {
+      finish(null)
+    }
+
+    renderer.on(CliRenderEvents.FRAME, onFrame)
+    renderer.once(CliRenderEvents.DESTROY, onDestroy)
+
+    if (!scheduler.isRunning) {
+      renderer.idle().then(() => finish(null))
+    }
+  })
+}
+
+export async function createTestRenderer(options: TestRendererOptions): Promise<TestRendererSetup> {
+  // Convert legacy kittyKeyboard boolean to new format
+  const useKittyKeyboard = options.kittyKeyboard ? { events: true } : options.useKittyKeyboard
+
+  const renderer = await setupTestRenderer({
+    ...options,
+    useKittyKeyboard,
+    screenMode: options.screenMode ?? "main-screen",
+    footerHeight: options.footerHeight ?? 12,
+    consoleMode: options.consoleMode ?? "disabled",
+    externalOutputMode: options.externalOutputMode ?? "passthrough",
+  })
+  const externalOutput = new TestExternalOutputRecorder(renderer)
+
+  const mockInput = createMockKeys(renderer, {
+    kittyKeyboard: options.kittyKeyboard,
+    otherModifiersMode: options.otherModifiersMode,
+  })
+  const mockMouse = createMockMouse(renderer)
+
+  const renderOnce = async () => {
+    const feed = (renderer as unknown as RendererFeedAccess)._feed
+    if (feed?.isBackpressured()) {
+      await feed.idle()
+    }
+    //@ts-expect-error - this is a test renderer
+    await renderer.loop()
+  }
+
+  const captureCharFrame = () => {
+    const currentBuffer = renderer.currentRenderBuffer
+    const frameBytes = currentBuffer.getRealCharBytes(true)
+    return decoder.decode(frameBytes)
+  }
+
+  const waitForVisualIdle = async (waitOptions: TestVisualIdleOptions = {}): Promise<void> => {
+    const maxFrames = normalizePositiveInteger(waitOptions.maxFrames, DEFAULT_MAX_VISUAL_IDLE_FRAMES)
+    const quietFrames = normalizePositiveInteger(waitOptions.quietFrames, DEFAULT_QUIET_FRAMES)
+    let consecutiveQuietFrames = 0
+
+    for (let frame = 0; frame < maxFrames; frame++) {
+      await drainImmediateWork()
+
+      const scheduler = renderer.getSchedulerState()
+      if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
+        return
+      }
+
+      const event = await waitForNextFrameOrIdle(renderer)
+      if (!event) {
+        return
+      }
+
+      if (renderer.getNativeStats().cellsUpdated === 0) {
+        consecutiveQuietFrames++
+        if (consecutiveQuietFrames >= quietFrames) {
+          return
+        }
+      } else {
+        consecutiveQuietFrames = 0
+      }
+    }
+
+    await drainImmediateWork()
+    const scheduler = renderer.getSchedulerState()
+    if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
+      return
+    }
+
+    throw createWaitError(renderer, `Timed out waiting for visual idle after ${maxFrames} frames`)
+  }
+
+  const flush = async (flushOptions: TestFlushOptions = {}): Promise<void> => {
+    await waitForVisualIdle({ maxFrames: normalizePositiveInteger(flushOptions.maxPasses, DEFAULT_MAX_PASSES) })
+  }
+
+  const waitFor = async (
+    predicate: () => boolean | Promise<boolean>,
+    waitOptions: TestWaitForOptions = {},
+  ): Promise<void> => {
+    const maxPasses = normalizePositiveInteger(waitOptions.maxPasses, DEFAULT_MAX_PASSES)
+
+    for (let pass = 0; pass <= maxPasses; pass++) {
+      await drainImmediateWork()
+      if (await predicate()) {
+        return
+      }
+
+      if (pass === maxPasses) {
+        break
+      }
+
+      const scheduler = renderer.getSchedulerState()
+      if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
+        break
+      }
+
+      await waitForNextFrameOrIdle(renderer)
+    }
+
+    throw createWaitError(renderer, `Timed out waiting for predicate after ${maxPasses} passes`)
+  }
+
+  const waitForFrame = async (
+    predicate: (frame: string) => boolean | Promise<boolean>,
+    waitOptions: TestWaitForOptions = {},
+  ): Promise<string> => {
+    const maxPasses = normalizePositiveInteger(waitOptions.maxPasses, DEFAULT_MAX_PASSES)
+    let frame = captureCharFrame()
+
+    for (let pass = 0; pass <= maxPasses; pass++) {
+      await drainImmediateWork()
+      frame = captureCharFrame()
+      if (await predicate(frame)) {
+        return frame
+      }
+
+      if (pass === maxPasses) {
+        break
+      }
+
+      const scheduler = renderer.getSchedulerState()
+      if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
+        break
+      }
+
+      await waitForNextFrameOrIdle(renderer)
+    }
+
+    frame = captureCharFrame()
+    throw createWaitError(renderer, `Timed out waiting for frame predicate after ${maxPasses} passes`, frame)
+  }
+
+  return {
+    renderer,
+    mockInput,
+    mockMouse,
+    renderOnce,
+    flush,
+    waitFor,
+    waitForFrame,
+    waitForVisualIdle,
+    externalOutput,
+    getNativeStats: () => renderer.getNativeStats(),
+    captureCharFrame,
+    captureSpans: () => {
+      const currentBuffer = renderer.currentRenderBuffer
+      const lines = currentBuffer.getSpanLines()
+      const cursorState = renderer.getCursorState()
+      return {
+        cols: currentBuffer.width,
+        rows: currentBuffer.height,
+        cursor: [cursorState.x, cursorState.y] as [number, number],
+        lines,
+      }
+    },
+    resize: (width: number, height: number) => {
+      //@ts-expect-error - this is a test renderer
+      renderer.processResize(width, height)
+    },
+  }
+}
+
+async function setupTestRenderer(config: TestRendererOptions) {
+  const stdin = config.stdin || createTestStdin()
+  const width = config.width || config.stdout?.columns || process.stdout.columns || 80
+  const height = config.height || config.stdout?.rows || process.stdout.rows || 24
+  const stdout = config.stdout || createTestStdout(width, height)
+
+  // Direct construction skips setupTerminal(); native bytes are routed to an
+  // explicit memory destination so tests do not depend on process stdout or feed
+  // backpressure behavior. CliRenderer still owns native renderer creation and
+  // applies the same useThread defaults as production construction.
+  return new CliRenderer(stdin, stdout, width, height, {
+    ...config,
+    bufferedOutput: config.bufferedOutput ?? "memory",
+  })
+}

package/src/testing/test-renderer.wait.test.ts

@@ -0,0 +1,278 @@
+import { afterEach, expect, spyOn, test } from "bun:test"
+import { CliRenderEvents } from "../renderer.js"
+import { TextRenderable } from "../renderables/Text.js"
+import { ManualClock } from "./manual-clock.js"
+import { createTestRenderer, type TestRendererSetup } from "./test-renderer.js"
+
+let setup: TestRendererSetup | null = null
+
+async function drainImmediateWork(): Promise<void> {
+  await Promise.resolve()
+  await new Promise<void>((resolve) => process.nextTick(resolve))
+  await Promise.resolve()
+}
+
+afterEach(() => {
+  setup?.renderer.destroy()
+  setup = null
+})
+
+test("flush waits for scheduled render work without forcing an extra frame", async () => {
+  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
+
+  const text = new TextRenderable(setup.renderer, {
+    content: "abc",
+    width: 3,
+    height: 1,
+  })
+  setup.renderer.root.add(text)
+
+  await setup.flush({ maxPasses: 1 })
+
+  const renderedStats = setup.getNativeStats()
+  expect(renderedStats.nativeFrameCount).toBe(1)
+  expect(renderedStats.cellsUpdated).toBeGreaterThanOrEqual(3)
+
+  await setup.flush()
+
+  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
+})
+
+test("waitForFrame observes text from a scheduled render", async () => {
+  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
+
+  const text = new TextRenderable(setup.renderer, {
+    content: "hello",
+    width: 5,
+    height: 1,
+  })
+  setup.renderer.root.add(text)
+
+  const frame = await setup.waitForFrame((value) => value.includes("hello"), { maxPasses: 1 })
+
+  expect(frame).toContain("hello")
+  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
+})
+
+test("waitFor observes predicate changes after scheduled work", async () => {
+  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
+
+  const text = new TextRenderable(setup.renderer, {
+    content: "ready",
+    width: 5,
+    height: 1,
+  })
+  setup.renderer.root.add(text)
+
+  await setup.waitFor(() => setup!.getNativeStats().nativeFrameCount > 0, { maxPasses: 1 })
+
+  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
+})
+
+test("renderer does not build frame event stats when no frame listener is registered", async () => {
+  setup = await createTestRenderer({ width: 10, height: 4, useThread: false })
+
+  const getStats = spyOn(setup.renderer, "getStats")
+
+  const text = new TextRenderable(setup.renderer, {
+    content: "quiet",
+    width: 5,
+    height: 1,
+  })
+  setup.renderer.root.add(text)
+
+  await setup.renderOnce()
+
+  expect(getStats).not.toHaveBeenCalled()
+  getStats.mockRestore()
+})
+
+test("renderer emits frame event without building stats when a frame listener is registered", async () => {
+  setup = await createTestRenderer({ width: 10, height: 4, useThread: false })
+
+  const getStats = spyOn(setup.renderer, "getStats")
+  let frameEventCount = 0
+  let frameEvent: unknown
+  setup.renderer.on(CliRenderEvents.FRAME, (event) => {
+    frameEventCount++
+    frameEvent = event
+  })
+
+  const text = new TextRenderable(setup.renderer, {
+    content: "event",
+    width: 5,
+    height: 1,
+  })
+  setup.renderer.root.add(text)
+
+  await setup.renderOnce()
+
+  expect(frameEventCount).toBe(1)
+  expect(frameEvent).toEqual({ frameId: setup.renderer.frameId })
+  expect(getStats).not.toHaveBeenCalled()
+  getStats.mockRestore()
+})
+
+test("waitForFrame fails instead of rendering when no work is pending", async () => {
+  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
+
+  await expect(setup.waitForFrame((frame) => frame.includes("missing"), { maxPasses: 2 })).rejects.toThrow(
+    "hasScheduledRender: false",
+  )
+
+  expect(setup.getNativeStats().nativeFrameCount).toBe(0)
+})
+
+test("waitForVisualIdle observes a naturally emitted zero-cell live frame", async () => {
+  const clock = new ManualClock()
+  setup = await createTestRenderer({
+    width: 10,
+    height: 4,
+    useThread: false,
+    clock,
+    maxFps: Number.POSITIVE_INFINITY,
+    targetFps: Number.POSITIVE_INFINITY,
+  })
+
+  const text = new TextRenderable(setup.renderer, {
+    content: "live",
+    width: 4,
+    height: 1,
+  })
+  setup.renderer.root.add(text)
+  setup.renderer.start()
+
+  await drainImmediateWork()
+  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
+
+  const idle = setup.waitForVisualIdle({ maxFrames: 2 })
+  await drainImmediateWork()
+  clock.advance(1)
+  await idle
+
+  const stats = setup.getNativeStats()
+  expect(stats.nativeFrameCount).toBe(2)
+  expect(stats.cellsUpdated).toBe(0)
+
+  setup.renderer.stop()
+})
+
+test("externalOutput records writeToScrollback commits without consuming native queue", async () => {
+  setup = await createTestRenderer({
+    width: 10,
+    height: 6,
+    screenMode: "split-footer",
+    footerHeight: 3,
+    externalOutputMode: "capture-stdout",
+    consoleMode: "disabled",
+    useThread: false,
+    maxFps: Number.POSITIVE_INFINITY,
+  })
+
+  setup.renderer.writeToScrollback((ctx) => {
+    const root = new TextRenderable(ctx.renderContext, {
+      content: "hello\nworld",
+      width: 5,
+      height: 2,
+    })
+
+    return {
+      root,
+      width: 5,
+      height: 2,
+      trailingNewline: false,
+    }
+  })
+
+  const commits = setup.externalOutput.take()
+
+  expect(commits).toHaveLength(1)
+  expect(commits[0]).toMatchObject({
+    text: "hello\nworld",
+    rows: ["hello", "world"],
+    width: 5,
+    height: 2,
+    rowColumns: 5,
+    startOnNewLine: true,
+    trailingNewline: false,
+  })
+  expect((setup.renderer as any).externalOutputQueue.size).toBe(1)
+
+  await setup.renderOnce()
+
+  expect((setup.renderer as any).externalOutputQueue.size).toBe(0)
+  expect(setup.externalOutput.take()).toEqual([])
+})
+
+test("externalOutput records scrollback surface commits", async () => {
+  setup = await createTestRenderer({
+    width: 10,
+    height: 6,
+    screenMode: "split-footer",
+    footerHeight: 3,
+    externalOutputMode: "capture-stdout",
+    consoleMode: "disabled",
+    useThread: false,
+  })
+
+  const surface = setup.renderer.createScrollbackSurface()
+  const text = new TextRenderable(surface.renderContext, {
+    content: "surface",
+    width: 7,
+    height: 1,
+  })
+
+  surface.root.add(text)
+  surface.render()
+  surface.commitRows(0, 1, { trailingNewline: false })
+
+  const commits = setup.externalOutput.take()
+
+  expect(commits).toHaveLength(1)
+  expect(commits[0]).toMatchObject({
+    text: "surface",
+    rows: ["surface"],
+    width: 10,
+    height: 1,
+    rowColumns: 10,
+    startOnNewLine: true,
+    trailingNewline: false,
+  })
+})
+
+test("externalOutput records captured stdout in FIFO order", async () => {
+  setup = await createTestRenderer({
+    width: 10,
+    height: 6,
+    screenMode: "split-footer",
+    footerHeight: 3,
+    externalOutputMode: "capture-stdout",
+    consoleMode: "disabled",
+    useThread: false,
+  })
+
+  setup.renderer.writeToScrollback((ctx) => {
+    const root = new TextRenderable(ctx.renderContext, {
+      content: "api",
+      width: 3,
+      height: 1,
+    })
+
+    return {
+      root,
+      width: 3,
+      height: 1,
+    }
+  })
+  ;(setup.renderer as any).stdout.write("out-1\n\nout-2")
+
+  const commits = setup.externalOutput.take()
+
+  expect(commits.map((commit) => commit.text)).toEqual(["api", "out-1", "", "out-2"])
+  expect(commits.map((commit) => commit.startOnNewLine)).toEqual([true, false, false, false])
+  expect(commits.map((commit) => commit.trailingNewline)).toEqual([true, true, true, false])
+
+  ;(setup.renderer as any).stdout.write("again")
+  expect(setup.externalOutput.takeText()).toBe("again")
+  expect(setup.externalOutput.take()).toEqual([])
+})

package/src/testing/test-streams.ts

@@ -0,0 +1,31 @@
+import { Readable, Writable } from "stream"
+
+export class TestWriteStream extends Writable {
+  public readonly isTTY = true
+  public readonly columns: number
+  public readonly rows: number
+
+  constructor(columns = 80, rows = 24) {
+    super()
+    this.columns = columns
+    this.rows = rows
+  }
+
+  override _write(_chunk: any, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    callback()
+  }
+
+  getColorDepth(): number {
+    return 24
+  }
+}
+
+export type TestStdout = TestWriteStream & NodeJS.WriteStream
+
+export function createTestStdin(): NodeJS.ReadStream {
+  return new Readable({ read() {} }) as NodeJS.ReadStream
+}
+
+export function createTestStdout(columns = 80, rows = 24): NodeJS.WriteStream {
+  return new TestWriteStream(columns, rows) as TestStdout
+}

package/src/testing.ts

@@ -0,0 +1,9 @@
+// Testing utilities module exports
+export * from "./testing/test-renderer.js"
+export * from "./testing/mock-keys.js"
+export * from "./testing/mock-mouse.js"
+export * from "./testing/mock-tree-sitter-client.js"
+export * from "./testing/terminal-capabilities.js"
+export * from "./testing/spy.js"
+export { ManualClock } from "./testing/manual-clock.js"
+export { TestRecorder, type RecordedFrame } from "./testing/test-recorder.js"