PTY Integration Testing Guide

December 22, 2025 · View on GitHub

This guide shows how to exercise the portable-pty powered terminal path so you can verify command execution, transcript capture, and TUI rendering end-to-end.

Prerequisites

  1. Install the project dependencies: 
    rustup show # ensures the pinned toolchain is active
  2. Export at least one supported API key before launching the TUI (Gemini, OpenAI, Anthropic). For example: 
    export GEMINI_API_KEY="your_api_key"
  3. Make sure you are in the repository root (vtcode/).

Automated Verification

Run the focused PTY smoke tests directly:

cargo test --test pty_tests

To execute the same checks plus external tool availability in one pass, use the helper script:

scripts/test_pty_tools.sh

The script runs the PTY tests and prints the captured log if any PTY assertion fails.

Manual TUI Walkthrough

  1. Build and launch the interactive client in debug mode (fast incremental rebuilds):

    scripts/run-debug.sh

    The script compiles the binary and starts vtcode chat with debug flags enabled. If you need to override the workspace directory, set WORKSPACE=/path/to/project before running the script.

  2. Once the TUI loads, open the command palette by typing the slash command:

    /command sh -c "printf 'hello from portable-pty' && sleep 1"

    The agent routes the request through run_pty_cmd, which now uses the shared PtyManager backend.

  3. Watch the transcript pane: you should see the command summary, streamed PTY output (including ANSI sequences), and the final exit status. Resize the terminal window to confirm portable-pty propagates the new dimensions without breaking the screen buffer.

  4. To inspect the preserved output after the command completes, open the transcript detail view (Tab → select the latest run_pty_cmd entry). The scrollback includes the multi-line PTY output exactly as captured by the parser.

Troubleshooting

  • Timeouts – Increase command_timeout_seconds in vtcode.toml under [pty] if long-running commands exceed the default limit.
  • Terminal size issues – Adjust [pty] default_rows and default_cols in vtcode.toml, then relaunch the agent so the PTY environment variables reflect the new size.
  • Windows hosts – No additional setup is required; portable-pty selects the ConPTY backend automatically when available.

Following these steps exercises the entire PTY stack—from command preparation through portable-pty execution and transcript rendering—so you can confirm the integration behaves as expected.