terminal-capture

Terminal Capture — CLI Terminal Screenshot Automation

Drive terminal interactions and screenshots via TypeScript configuration, used for visual verification during PR reviews.

Prerequisites

Ensure the following dependencies are installed before running:

npm install       # Install project dependencies.
npx playwright install chromium   # Install Playwright browser (skip in CI: see note below)

CI / verify context: when QWEN_VERIFY_CHROMIUM=1 is set, the browser is already installed and PLAYWRIGHT_BROWSERS_PATH points at it. Do not run playwright install — it downloads ~170 MB and fails on system deps the agent user cannot install.

Architecture

node-pty (pseudo-terminal)
  → ANSI byte stream
  → xterm.js (Playwright headless)
  → Screenshot

Core files:

• integration-tests/terminal-capture/terminal-capture.ts Low-level PTY, xterm.js, and Playwright engine.
• integration-tests/terminal-capture/scenario-runner.ts Scenario executor for config, interactions, and screenshots.
• integration-tests/terminal-capture/run.ts CLI entry point for batch scenario runs.
• integration-tests/terminal-capture/scenarios/*.ts Scenario configuration files.

Quick Start

1. Write Scenario Configuration

Create a .ts file under integration-tests/terminal-capture/scenarios/:

import type { ScenarioConfig } from '../scenario-runner.js';

export default {
  name: '/about',
  spawn: ['node', 'dist/cli.js', '--yolo'],
  // cwd is relative to this config file's location.
  terminal: { title: 'qwen-code', cwd: '../../..' },
  flow: [
    { type: 'Hi, can you help me understand this codebase?' },
    { type: '/about' },
  ],
} satisfies ScenarioConfig;

2. Run

# Single scenario
npx tsx integration-tests/terminal-capture/run.ts \
  integration-tests/terminal-capture/scenarios/about.ts

# Batch (entire directory)
npx tsx integration-tests/terminal-capture/run.ts \
  integration-tests/terminal-capture/scenarios/