io.github.HurleySk/can-see

Launch a CLI app in a virtual terminal. IMPORTANT: You MUST call

Capture the terminal as a PNG image

Capture a specific rectangular area of the visible terminal as a PNG image

Find text in the viewport and capture the surrounding area as a PNG. Searches visible viewport only (single-line match, returns first match top-to-bottom).

Snapshot current terminal state for later diff comparison (screenshot also auto-captures a baseline)

Compare current terminal state against the baseline, return PNG with changed cells highlighted in red

Query character, colors, and text attributes at a specific cell or range of cells

Read text that has scrolled above the visible terminal viewport

Begin capturing terminal frames for an animated GIF (frames captured on output, not fixed interval)

Stop recording and return the captured frames as an animated GIF. If the GIF exceeds the inline size limit (~4MB), frames are automatically trimmed. If still too large, the GIF is saved to a temp file and the path is returned. Use outputPath to always save to a specific file.

Read the terminal buffer as plain text (for programmatic assertions instead of visual screenshots)

Wait until specific text appears in the terminal buffer (replaces sleep-and-screenshot polling)

Wait until terminal output has been stable for a given duration. Use idleMs (default) for apps that stop producing output, or stableMs for apps with constant output like timers/spinners — stableMs compares buffer content instead of tracking raw PTY data.

Wait until a specific color appears at a position (or anywhere in the viewport)

Wait until the process exits and return its exit code and signal

Send keystrokes to the app (e.g.,

Type a string of text into the app

Get the current process status — use to distinguish

List all active terminal sessions

Kill the app and clean up the session

Kill all active sessions at once. Useful for cleanup between test runs or when sessions may have been orphaned.