cline CLI 的 OpenTUI 测试实践：终端 UI 无头渲染、快照与交互测试指南

本文以 cline 仓库内置的 OpenTUI 测试参考文档（.agents/skills/opentui/references/testing/REFERENCE.md）为主体，系统讲解如何对基于 OpenTUI 构建的终端用户界面（TUI）进行无头渲染测试、快照测试与交互测试。读完本文，你将掌握 createTestRenderer 与 testRender 两套测试工具的完整用法、React/Solid 两套绑定层的测试差异，以及 cline CLI 在真实项目中如何配合 Mock 单测与 PTY 端到端测试来验证 TUI 行为。

总览：OpenTUI 测试体系的三块基石

OpenTUI 为终端界面测试提供了三类能力：

• Test Renderer（无头渲染器）：不依赖真实终端即可创建渲染器实例，在测试中挂载组件；
• Snapshot Testing（快照测试）：把渲染结果捕获为纯文本帧，验证视觉输出；
• Interaction Testing（交互测试）：模拟按键输入、焦点切换，验证组件对用户操作的响应。

这份参考文档的适用场景是：当你需要为 TUI 编写快照测试、交互测试或基于渲染器的回归检查时查阅。

在 cline 仓库中，CLI 应用的交互式 TUI 正是构建在 OpenTUI 之上——apps/cli/package.json 中固定依赖了 @opentui/core: 0.4.3 与 @opentui/react: 0.4.3，因此本文的方法可以直接迁移到该应用的组件测试中。

测试环境搭建

测试运行器

参考文档以 Bun 内置测试运行器为基础：

import { test, expect, beforeEach, afterEach } from "bun:test"

创建无头测试渲染器

通过 @opentui/core/testing 子路径导出创建测试渲染器：

import { createTestRenderer } from "@opentui/core/testing"

const testSetup = await createTestRenderer({
  width: 80,     // 终端宽度
  height: 24,    // 终端高度
})

width / height 定义了虚拟终端的可视区域尺寸，直接影响换行、裁剪与快照内容，后文"陷阱"一节会说明为何要保持尺寸一致。

核心测试：从基础渲染到快照

基础渲染测试

最直接的测试方式：创建渲染器、挂载一个 TextRenderable、渲染一帧、断言捕获的字符帧包含预期文本：

import { test, expect } from "bun:test"
import { createTestRenderer } from "@opentui/core/testing"
import { TextRenderable } from "@opentui/core"

test("renders text", async () => {
  const testSetup = await createTestRenderer({
    width: 40,
    height: 10,
  })

  const text = new TextRenderable(testSetup.renderer, {
    id: "greeting",
    content: "Hello, World!",
  })

  testSetup.renderer.root.add(text)
  await testSetup.renderOnce()

  expect(testSetup.captureCharFrame()).toContain("Hello, World!")
})

从源码结构看，captureCharFrame() 返回的是纯文本帧而非原始 ANSI 字节流，这使得断言可以用 toContain、toMatchSnapshot() 等常规匹配器完成，而无需解析转义序列。

快照测试

对 BoxRenderable 等带边框的容器做快照，验证完整视觉布局：

import { test, expect, afterEach } from "bun:test"
import { createTestRenderer } from "@opentui/core/testing"
import { BoxRenderable, TextRenderable } from "@opentui/core"

let testSetup: Awaited<ReturnType<typeof createTestRenderer>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("component matches snapshot", async () => {
  testSetup = await createTestRenderer({
    width: 40,
    height: 10,
  })

  const box = new BoxRenderable(testSetup.renderer, {
    id: "box",
    border: true,
    width: 20,
    height: 5,
  })
  box.add(new TextRenderable(testSetup.renderer, {
    content: "Content",
  }))

  testSetup.renderer.root.add(box)
  await testSetup.renderOnce()

  expect(testSetup.captureCharFrame()).toMatchSnapshot()
})

React 绑定层测试

testRender 工具

React 侧通过 @opentui/react/test-utils 子路径导出提供内置的 testRender 工具：

import { testRender } from "@opentui/react/test-utils"

该工具一次完成四件事：

• 创建无头测试渲染器；
• 自动配置 React 的 Act 环境（保证状态更新的时序正确）；
• 在销毁时自动执行 React 根卸载；
• 返回与 Core 侧一致的测试 setup 对象，API 无缝衔接。

基础组件测试

import { test, expect } from "bun:test"
import { testRender } from "@opentui/react/test-utils"

function Greeting({ name }: { name: string }) {
  return <text>Hello, {name}!</text>
}

test("Greeting renders name", async () => {
  const testSetup = await testRender(
    <Greeting name="World" />,
    { width: 80, height: 24 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  expect(frame).toContain("Hello, World!")
})

React 快照测试

import { test, expect, afterEach } from "bun:test"
import { testRender } from "@opentui/react/test-utils"

let testSetup: Awaited<ReturnType<typeof testRender>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("component matches snapshot", async () => {
  testSetup = await testRender(
    <box style={{ width: 20, height: 5, border: true }}>
      <text>Content</text>
    </box>,
    { width: 25, height: 8 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  expect(frame).toMatchSnapshot()
})

状态测试

对依赖 useState 的组件，先验证初始渲染值，再在后续用例中模拟状态变更：

import { test, expect, afterEach } from "bun:test"
import { useState } from "react"
import { testRender } from "@opentui/react/test-utils"

let testSetup: Awaited<ReturnType<typeof testRender>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

function Counter() {
  const [count, setCount] = useState(0)
  return (
    <box>
      <text>Count: {count}</text>
    </box>
  )
}

test("Counter shows initial value", async () => {
  testSetup = await testRender(
    <Counter />,
    { width: 20, height: 5 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  expect(frame).toContain("Count: 0")
})

生命周期管理模式（Setup/Teardown）

在 describe 块内用 beforeEach/afterEach 管理渲染器生命周期，避免用例之间相互污染：

import { describe, test, expect, beforeEach, afterEach } from "bun:test"
import { testRender } from "@opentui/react/test-utils"

let testSetup: Awaited<ReturnType<typeof testRender>>

describe("MyComponent", () => {
  beforeEach(async () => {
    if (testSetup) {
      testSetup.renderer.destroy()
    }
  })

  afterEach(() => {
    if (testSetup) {
      testSetup.renderer.destroy()
    }
  })

  test("renders correctly", async () => {
    testSetup = await testRender(<MyComponent />, {
      width: 40,
      height: 10,
    })

    await testSetup.renderOnce()
    const frame = testSetup.captureCharFrame()
    expect(frame).toMatchSnapshot()
  })
})

testRender 返回对象

testRender 返回的 setup 对象包含以下属性：

属性	类型	说明
renderer	Renderer	无头渲染器实例
renderOnce	() => Promise<void>	触发一次渲染循环
captureCharFrame	() => string	将当前输出捕获为文本
resize	(width, height) => void	调整虚拟终端尺寸

这套 API 与 Core 侧 createTestRenderer 的返回对象一致，因此 React、Solid、Core 三种测试代码可以互相平移。

Solid 绑定层测试

testRender 工具

Solid 侧的 testRender 直接从主包导出：

import { testRender } from "@opentui/solid"

关键差异：与 React 不同，Solid 的 testRender 接收的是函数组件（而非 JSX 元素），调用方式见下。

基础组件测试

import { test, expect } from "bun:test"
import { testRender } from "@opentui/solid"

function Greeting(props: { name: string }) {
  return <text>Hello, {props.name}!</text>
}

test("Greeting renders name", async () => {
  const testSetup = await testRender(
    () => <Greeting name="World" />,
    { width: 80, height: 24 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  expect(frame).toContain("Hello, World!")
})

Solid 快照测试

import { test, expect, afterEach } from "bun:test"
import { testRender } from "@opentui/solid"

let testSetup: Awaited<ReturnType<typeof testRender>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("component matches snapshot", async () => {
  testSetup = await testRender(
    () => (
      <box style={{ width: 20, height: 5, border: true }}>
        <text>Content</text>
      </box>
    ),
    { width: 25, height: 8 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  expect(frame).toMatchSnapshot()
})

快照格式与更新

快照以纯文本形式记录终端渲染结果，例如：

┌──────────────────┐
│ Hello, World!    │
│                  │
└──────────────────┘

当组件布局发生预期内的变化后，用以下命令重新生成快照：

bun test --update-snapshots

交互测试：模拟按键与焦点

模拟按键

无头渲染器暴露了 keyInput 事件源，直接向其中发射 keypress 事件即可模拟用户按键：

import { test, expect, afterEach } from "bun:test"
import { createTestRenderer } from "@opentui/core/testing"

let testSetup: Awaited<ReturnType<typeof createTestRenderer>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("responds to keyboard", async () => {
  testSetup = await createTestRenderer({
    width: 40,
    height: 10,
  })

  // 创建响应按键的组件
  // ...

  // 模拟按键
  testSetup.renderer.keyInput.emit("keypress", {
    name: "enter",
    sequence: "\r",
    ctrl: false,
    shift: false,
    meta: false,
    option: false,
    eventType: "press",
    repeated: false,
  })

  // 按键后再渲染一帧
  await testSetup.renderOnce()

  expect(testSetup.captureCharFrame()).toContain("Selected")
})

事件负载中 name（键名）、sequence（原始字节序列）、修饰键布尔值（ctrl/shift/meta/option）与真实终端上报结构一致，因此测试中构造的按键与真实输入行为等价。

焦点测试

直接调用组件的 focus() 并断言焦点状态，验证焦点管理与输入组件的行为：

import { test, expect, afterEach } from "bun:test"
import { createTestRenderer } from "@opentui/core/testing"
import { InputRenderable } from "@opentui/core"

let testSetup: Awaited<ReturnType<typeof createTestRenderer>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("input receives focus", async () => {
  testSetup = await createTestRenderer({
    width: 40,
    height: 10,
  })

  const input = new InputRenderable(testSetup.renderer, {
    id: "test-input",
    placeholder: "Type here",
  })
  testSetup.renderer.root.add(input)

  input.focus()

  expect(input.isFocused()).toBe(true)
})

测试组织

文件结构约定

测试文件与被测模块就近放置：

src/
├── components/
│   ├── Button.tsx
│   └── Button.test.tsx
├── hooks/
│   ├── useCounter.ts
│   └── useCounter.test.ts
└── test-utils.tsx

常用运行命令

# 运行全部测试
bun test

# 运行指定测试文件
bun test src/components/Button.test.tsx

# 按名称过滤
bun test --filter "Button"

# 监听模式
bun test --watch

常用测试模式

条件渲染测试（React）

分别渲染不同 props 组合，断言各状态下帧内容：

import { test, expect, afterEach } from "bun:test"
import { testRender } from "@opentui/react/test-utils"

let testSetup: Awaited<ReturnType<typeof testRender>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("shows loading state", async () => {
  testSetup = await testRender(
    <DataLoader loading={true} />,
    { width: 40, height: 10 }
  )

  await testSetup.renderOnce()
  expect(testSetup.captureCharFrame()).toContain("Loading...")
})

test("shows data when loaded", async () => {
  testSetup = await testRender(
    <DataLoader loading={false} data={["Item 1", "Item 2"]} />,
    { width: 40, height: 10 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()
  expect(frame).toContain("Item 1")
  expect(frame).toContain("Item 2")
})

列表渲染测试

对列表组件逐元素断言，保证每一项都参与渲染：

test("renders all items", async () => {
  const items = ["Apple", "Banana", "Cherry"]

  testSetup = await testRender(
    <ItemList items={items} />,
    { width: 40, height: 10 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  items.forEach(item => {
    expect(frame).toContain(item)
  })
})

布局快照测试

布局类测试建议使用更大的视口，避免小尺寸下换行/裁剪干扰断言：

test("matches layout snapshot", async () => {
  testSetup = await testRender(
    <AppLayout />,
    { width: 120, height: 40 }  // 更大的视口
  )

  await testSetup.renderOnce()
  expect(testSetup.captureCharFrame()).toMatchSnapshot()
})

调试测试

打印帧输出

断言失败时最快的定位手段是把帧内容打印出来，直观查看渲染结果：

import { testRender } from "@opentui/react/test-utils"

test("debug output", async () => {
  const testSetup = await testRender(
    <MyComponent />,
    { width: 40, height: 10 }
  )

  await testSetup.renderOnce()
  const frame = testSetup.captureCharFrame()

  // 打印查看实际渲染内容
  console.log(frame)

  expect(frame).toContain("expected")
})

详细输出模式

bun test --verbose

陷阱（Gotchas）

异步渲染：先 renderOnce 再断言

testRender / createTestRenderer 完成后渲染尚未发生，必须在捕获帧之前显式调用 renderOnce()：

const testSetup = await testRender(<MyComponent />, { width: 40, height: 10 })
await testSetup.renderOnce()  // 捕获帧之前必须执行
const frame = testSetup.captureCharFrame()

测试隔离与清理：每个用例后销毁渲染器

渲染器持有终端资源，不销毁会造成资源泄漏并可能影响后续用例。参考文档的固定做法是把 testSetup 提升到模块作用域，在 afterEach 中统一销毁：

import { afterEach } from "bun:test"

let testSetup: Awaited<ReturnType<typeof testRender>>

afterEach(() => {
  if (testSetup) {
    testSetup.renderer.destroy()
  }
})

test("test 1", async () => {
  testSetup = await testRender(<Component1 />, { width: 40, height: 10 })
  // ...
})

test("test 2", async () => {
  testSetup = await testRender(<Component2 />, { width: 40, height: 10 })
  // ...
})

快照尺寸要稳定

同一组件的快照对 width/height 敏感（边框位置、换行点都会变），建议全项目统一一套标准尺寸：

const testSetup = await createTestRenderer({
  width: 80,   // 标准宽度
  height: 24,  // 标准高度
})

在包目录下运行测试

面向具体包的测试应从包目录内运行，而不是仓库根目录：

cd packages/core
bun test

# 包级测试不要在仓库根目录运行

cline 仓库中的实战印证：Mock 单测 + PTY 端到端测试

参考文档描述的是 OpenTUI 包内"无头渲染器"这一层单测手段；在 cline 仓库中，构建于 OpenTUI 之上的 CLI 应用（apps/cli 依赖 @opentui/core 与 @opentui/react 0.4.3）则展示了两种互补的落地方式，恰好与本文的方法论形成完整闭环。

方式一：单测中 Mock 渲染器，验证生命周期

在 apps/cli/src/tui/index.test.ts 中，测试并不真正启动无头渲染器，而是用 vi.mock 替换 @opentui/core 的 createCliRenderer 与 @opentui/react 的 createRoot（约第 25-31 行），构造带 destroy、on、setTerminalTitle 等桩方法的 rendererMock。这样可以在不触碰终端的情况下断言关键生命周期行为，例如"React 根创建失败时必须销毁渲染器"这类资源回收逻辑。这印证了参考文档中 renderer.destroy() 语义的重要性——销毁路径本身就是被测对象。

方式二：PTY 端到端测试，验证真实屏幕内容

对需要整体验证交互流程的场景，apps/cli/src/cli.tuistory.e2e.test.ts 采用了另一条路线：通过 tuistory 在真实 PTY 中拉起 CLI 进程，以 Ghostty 终端模拟器承载，用 session.waitForText("What can I do for you?") 等待画面出现（见第 98-102 行的 waitForChatView），断言的是"用户实际看到的屏幕状态"而非原始字节流。该文件的注释特别指出：无头快照关注的是渲染帧，而 PTY 快照能捕捉覆盖层弹窗等真实呈现差异——两类测试各有所据，不可互相替代。

该端到端套件还包含与参考文档"测试隔离"原则一致的清理逻辑（第 104-120 行）：afterEach 中先发送两次 ctrl+c 让 TUI 干净退出，再关闭 session、移除临时 HOME/数据目录，避免测试之间状态串扰。其运行配置见 apps/cli/vitest.tuistory.e2e.config.ts：按 src/**/*.tuistory.e2e.test.ts 模式单独纳入、超时放宽到 60 秒。

从源码结构看，clines CLI 的测试体系可以归纳为三层：

1. 组件层：按参考文档所述，用无头渲染器 / testRender 做帧级断言与快照；
2. 入口层：Mock 掉 @opentui/core 渲染器，单测入口的创建/销毁生命周期；
3. 端到端层：真实 PTY 中驱动完整 CLI，断言屏幕可见内容。

延伸阅读

• OpenTUI 核心 API 参考 — createTestRenderer 与 renderable 类详解
• React 配置参考 — React 绑定层的测试相关配置
• Solid 配置参考 — Solid 绑定层的测试相关配置
• 键盘事件参考 — 测试中模拟按键事件的完整键位模型
• cline CLI 开发指南 — cline CLI 应用的本地开发与测试说明