Tuistory 是一款基於終端機的類似 Playwright 的測試工具，非常有用。

最近經常使用 Vibe coding 來開發 TUI 工具，作為動作確認的工具，我使用了 tuistory，覺得非常方便，因此想介紹給大家。

tuistory 是什麼工具

簡單來說，它是 Terminal 版本的 Playwright。

擁有類似於 playwright-cli 和 agent-browser 的介面，可以啟動和操作虛擬終端機，並獲取內容。

$ tuistory launch "nvim" -s nvim --cols 80 --rows 40
Session "nvim" started

$ tuistory -s nvim snapshot --trim
buffers

                                     __
        ___     ___    ___   __  __ /\_\    ___ ___
       / _ `\  / __`\ / __`\/\ \/\ \\/\ \  / __` __`\
      /\ \/\ \/\  __//\ \_\ \ \ \_/ |\ \ \/\ \/\ \/\ \
      \ \_\ \_\ \____\ \____/\ \___/  \ \_\ \_\ \_\ \_\
       \/_/\/_/\/____/\/___/  \/__/    \/_/\/_/\/_/\/_/

   [e] 新檔案                                                               •

   最近打開的文件 /Users/tomoya/.ghq/github.com/tomoasleep/navigator.nvim

   [0]    .envrc
   [1]    AGENTS.md
   [2]    denops/navigator/action.ts
   [3]    denops/navigator/ui.ts
   [4]    .gitignore

   最近打開的文件

   [10]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/lsp.lua
   [11]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/git-gem.lua
   [12]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/config/init.lu
   [13]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/config/lsp-col
   [14]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/config/airline
   [15]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/start.lua
   [16]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/yoda.lua
   [17]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/plugins.lua
   [18]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/lua/core.lua
   [19]    ~/.ghq/github.com/tomoasleep/dotfiles/config/nvim/init.vim

   [q] 離開
~
~
~
~
 NORMAL  [Scratch][-]                         alp…   [unix]  30% ㏑:10/33≡ ℅ :5

$ tuistory -s nvim press e i
OK
$ tuistory -s nvim type 'Hello, world!'
OK
$ tuistory -s nvim snapshot --trim
 [No Name]+                                                             buffers
  1 Hello, world!                                                             •
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
 INSERT  [No Name][+]                               [unix]  100% ㏑: 1/1≡ ℅ :14
-- INSERT -

Node.js 的介面也有提供

除了 CLI 以外，還提供了 Node.js 的介面。（* 可以在 Bun 等環境中運行）

import { launchTerminal } from 'tuistory'

const session = await launchTerminal({
  command: 'my-cli',
  args: ['--flag'],
  cols: 120,
  rows: 36,
  cwd: '/path/to/dir',
  env: { MY_VAR: 'value' },
})

// observe
const text = await session.text()               // 獲取完整終端機文本
const text = await session.text({ trimEnd: true }) // 去除結尾空白
const bold = await session.text({ only: { bold: true } }) // 風格過濾

// act
await session.type('hello world')               // 一個字母一個字母的輸入
await session.press('enter')                    // 單個鍵
await session.press(['ctrl', 'c'])              // 鍵盤組合
await session.click('Submit')                   // 點擊文字

// wait
await session.waitForText('Ready', { timeout: 10000 })
await session.waitForText(/Loading\.\.\./, { timeout: 5000 })

// 截圖為圖片
const data = session.getTerminalData()
const { renderTerminalToImage } = await import('ghostty-opentui/image')
const image = await renderTerminalToImage(data, { format: 'jpeg', devicePixelRatio: 2 })

// 清理
session.close()

來自: https://github.com/remorses/tuistory/blob/main/SKILL.md#jsts-api-library

這在實際編寫 E2E 測試時非常有效。我自己也利用這個工具來測試 TUI 工具。