tuistory

Playwright for terminal user interfaces. Write end-to-end tests for CLI and TUI applications.

tuistory has 2 modes:

1. CLI — the tuistory shell command. Launch terminal sessions, type text, press keys, take text snapshots or image screenshots. Sessions run in a background daemon and persist across commands.
2. JS/TS API — import { launchTerminal } from 'tuistory'. Use programmatically in test files (vitest, bun:test) to write Playwright-style tests with inline snapshots.

CLI usage

REQUIREMENT: You MUST run tuistory --help before using the CLI. The CLI evolves and the help output is the source of truth for available commands, options, and syntax. Always check it first.

Install globally or use npx/bunx:

# global
bun add -g tuistory
npm install -g tuistory

# or without installing
npx tuistory --help
bunx tuistory --help

CLI quick reference

tuistory launch <command> -s <name> [--cols N] [--rows N] [--env KEY=VAL]
tuistory -s <name> snapshot --trim
tuistory -s <name> screenshot -o image.jpg --pixel-ratio 2
tuistory -s <name> type "text"
tuistory -s <name> press enter
tuistory -s <name> press ctrl c
tuistory -s <name> click "Submit"
tuistory -s <name> wait "pattern" --timeout 10000
tuistory -s <name> wait "/regex/" --timeout 10000
tuistory -s <name> scroll down 5
tuistory -s <name> resize 120 40
tuistory -s <name> close
tuistory sessions
tuistory daemon-stop

Always run snapshot --trim after every action to see the current terminal state.

Screenshot for agent bots

Capture terminal as an image to upload to users (Discord, Slack, web UIs). Use --pixel-ratio 2 for sharp images on social media and messaging apps:

tuistory -s myapp screenshot -o /tmp/terminal.jpg --pixel-ratio 2
# then upload /tmp/terminal.jpg to the user

JS/TS API (library)

bun add tuistory    # or npm install tuistory

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()               // full terminal text
const text = await session.text({ trimEnd: true }) // trimmed
const bold = await session.text({ only: { bold: true } }) // style filter

// act
await session.type('hello world')               // type character by character
await session.press('enter')                    // single key
await session.press(['ctrl', 'c'])              // key chord
await session.click('Submit')                   // click on text

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

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

// cleanup
session.close()

Writing tests with vitest

tuistory is like Playwright but for CLIs. The workflow is: observe (snapshot with inline snapshot), act (type/press/click), observe again. Build tests progressively.

Step 1: Launch and observe

Start with an empty inline snapshot. Run with --update / -u to fill it in.

import { test, expect } from 'vitest'
import { launchTerminal } from 'tuistory'

test('my CLI shows help', async () => {
  const session = await launchTerminal({
    command: 'my-cli',
    args: ['--help'],
    cols: 120,
    rows: 36,
  })

  const text = await session.text({ trimEnd: true })
  expect(text).toMatchInlineSnapshot()
  // ^ run `vitest --run -u` to fill this in, then read the file to see what it captured

  session.close()
}, 10000)

Step 2: Interact and observe again

Add actions and more snapshots incrementally:

test('bash interaction', async () => {
  const session = await launchTerminal({
    command: 'bash',
    args: ['--norc', '--noprofile'],
    cols: 60,
    rows: 10,
    env: { PS1: '$ ', HOME: '/tmp', PATH: process.env.PATH },
  })

  // observe initial state
  const initial = await session.text({ trimEnd: true })
  expect(initial).toMatchInlineSnapshot()

  // act
  await session.type('echo "hello world"')
  await session.press('enter')

  // wait + observe
  const output = await session.waitForText('hello world')
  expect(output).toMatchInlineSnapshot()

  // cleanup
  await session.type('exit')
  await session.press('enter')
  session.close()
}, 10000)

Step 3: Run with -u, read back, iterate

# fill in snapshots
vitest --run -u

# read the test file to see captured terminal output
# adjust assertions, add more interactions, repeat

This observe-act-observe loop lets you progressively explore any TUI. Each inline snapshot captures the exact terminal state, making tests readable and easy to update.

Testing a TUI app (e.g. opencode, claude)

test('opencode shows welcome', async () => {
  const session = await launchTerminal({
    command: 'opencode',
    cols: 150,
    rows: 45,
  })

  await session.waitForText('switch agent', { timeout: 15000 })
  await session.type('hello from tuistory')

  const text = await session.text({ timeout: 1000 })
  expect(text).toMatchInlineSnapshot()

  // navigate menus
  await session.press(['ctrl', 'p'])
  const commands = await session.waitForText('Commands', { timeout: 5000 })
  expect(commands).toMatchInlineSnapshot()

  await session.press('esc')
  session.close()
}, 30000)

Testing a Node.js debugger

test('node debugger inspect variables', async () => {
  const session = await launchTerminal({
    command: 'node',
    args: ['inspect', 'app.js'],
    cols: 150,
    rows: 45,
  })

  await session.waitForText('Break on start', { timeout: 10000 })
  await session.type('cont')
  await session.press('enter')
  await session.waitForText('break in', { timeout: 5000 })

  const snapshot = await session.text({ trimEnd: true })
  expect(snapshot).toMatchInlineSnapshot()

  session.close()
}, 30000)

Tips

• Always set a timeout on waitForText for async operations
• Use trimEnd: true in session.text() to avoid trailing whitespace in snapshots
• Set waitForData: false for interactive commands that don't produce output immediately (like cat)
• Use regex in waitForText for dynamic content: await session.waitForText(/version \d+/)
• Close sessions in test teardown to avoid leaked processes
• Use --cols and --rows to control terminal size — affects TUI layout