# Termless

> Headless terminal testing

Terminal apps are hard to test — no DOM to inspect, just invisible escape sequences. Termless gives you a real terminal emulator in-process with full access to cells, colors, cursor, and modes. Like Playwright, but for terminals.

## Table of Contents

### Concepts

- [Concepts Overview](/concepts/overview.md): The termless mental model — three domain objects (Backend, Terminal, Recording) and four verbs (record, view, play, compare).
- [Backend](/concepts/backend.md): A Backend is a VT-emulator implementation — the engine that parses escape sequences into a terminal buffer.
- [TestTerminal](/concepts/terminal.md): A TestTerminal is a live session — a Backend plus an optional PTY, a buffer, and a readable, queryable API.
- [Recording](/concepts/recording.md): A Recording is a captured terminal session — a timeline of commands, I/O, and frames, serializable to the .tape, .cast, and .tty/.ttyz formats.

### Guide

- [Getting Started](/guide/getting-started.md): Install Termless and write your first headless terminal test in under 5 minutes with Vitest.
- [Terminal Buffer Model](/guide/terminal-model.md): Understand how Termless models terminal buffers -- cells, rows, scrollback, and the difference between screen and buffer regions.

### Testing

- [Writing Tests](/guide/writing-tests.md): Learn how to write headless terminal tests with Termless -- feed input, assert on screen state, colors, cursor, and more.
- [Screenshots](/guide/screenshots.md): Generate SVG and PNG screenshots from terminal state via native canvas (@napi-rs/canvas + ghostty-web) with resvg as a cross-platform fallback.
- [Best Practices](/guide/best-practices.md): Tips for writing reliable, fast, and maintainable terminal tests with Termless -- in-memory vs PTY, timeouts, and determinism.

### Backends

- [Backend Capabilities](/guide/backends.md): Compare Termless backends -- xterm.js, Ghostty, vterm.js, vt100, Alacritty, WezTerm, and more. Feature matrix and selection guide.
- [Multi-Backend Testing](/guide/multi-backend.md): Write tests once and run them against multiple terminal emulator backends to catch cross-platform rendering differences.
- [Cross-Backend Conformance](/advanced/compat-matrix.md): Verify that all 10 Termless backends produce identical results for the same VT100/ECMA-48 sequences. Find and fix emulator bugs.
- [Terminal Census](/census.md): Comprehensive census of terminal emulator capabilities powered by Termless backends and published at terminfo.dev.

### Recording

- [Recording Sessions](/guide/recording-sessions.md): Record terminal sessions, play them back, animate them as GIF/SVG/APNG, and compare across backends.
- [Tracing Visual Bugs](/guide/tracing-visual-bugs.md): Capture every render-relevant frame of a terminal session and scrub them to find exactly where a TUI rendering bug appears.
- [Web Player](/guide/web-player.md): Embed .cast and .tape terminal playback in browser docs with @termless/web-player and xterm.js.

### Reference

- [CLI Reference](/reference/cli.md): The Termless CLI — the four recording-domain verbs (record, view, play, compare) plus the config and diagnostic surfaces.
- [MCP Reference](/reference/mcp.md): The Termless MCP server — terminal-session tools for AI agents, mapped to the record / view recording-domain verbs.

### Recording Formats

- [Recording Formats](/reference/formats.md): The on-disk formats a Recording serializes to — .tape, .cast, and .tty/.ttyz.
- [.tape Format Reference](/reference/formats/tape.md): Complete reference for the .tape recording format -- commands, settings, duration syntax, and examples.
- [.cast Format Reference](/reference/formats/asciicast.md): Read, write, and convert asciicast v2 recordings for asciinema compatibility.
- [.tty / .ttyz Format Reference](/reference/formats/tty.md): One recording format, two encodings — the live bundle directory and the sealed archive — read by one encoding-blind reader.
- [Journal Replay Reference](/reference/formats/journal.md): Replay a recorded terminal-session journal through any Termless terminal or backend for deterministic recording, conformance, and visual fixtures.

### API Reference

- [Terminal API](/api/terminal.md): API reference for createTerminal -- options, PTY spawning, region selectors, screenshots, and the full TestTerminal interface.
- [TerminalBackend API](/api/backend.md): API reference for the TerminalBackend interface -- the contract every Termless backend implements for terminal emulation.
- [Cell, Cursor & Colors API](/api/cell.md): API reference for Cell, Cursor, CursorStyle, Color, UnderlineStyle, and other terminal cell types in Termless.
- [State Digest API](/api/state-digest.md): terminalStateDigest and diffTerminalStates — one serializable "same terminal state" vocabulary for equivalence assertions across backends.
- [Vitest Matchers API](/api/matchers.md): Complete reference for Termless Vitest matchers -- text, style, color, cursor, and snapshot assertions for terminal testing.

### Matcher Reference

- [Matcher Reference](/matchers.md): Complete reference for all Termless Vitest matchers
- [toHaveAttrs](/matchers/to-have-attrs.md): Assert multiple cell attributes at once with partial matching
- [toHaveCursor](/matchers/to-have-cursor.md): Assert multiple cursor properties at once with partial matching
- [toContainText](/matchers/to-contain-text.md): Assert that a terminal region contains the expected text substring
- [toContainOutput](/matchers/to-contain-output.md): Assert that the raw terminal output stream contains expected bytes
- [toHaveText](/matchers/to-have-text.md): Assert that a terminal region's text matches exactly after trimming
- [toMatchLines](/matchers/to-match-lines.md): Assert that a terminal region's lines match an expected array
- [toBeBold](/matchers/to-be-bold.md): Assert that a terminal cell has bold styling
- [toBeItalic](/matchers/to-be-italic.md): Assert that a terminal cell has italic styling
- [toBeDim](/matchers/to-be-dim.md): Assert that a terminal cell has dim (faint) styling
- [toBeStrikethrough](/matchers/to-be-strikethrough.md): Assert that a terminal cell has strikethrough styling
- [toBeInverse](/matchers/to-be-inverse.md): Assert that a terminal cell has inverse (reverse video) styling
- [toBeWide](/matchers/to-be-wide.md): Assert that a terminal cell contains a double-width character
- [toHaveUnderline](/matchers/to-have-underline.md): Assert that a terminal cell has underline styling with optional style check
- [toHaveFg](/matchers/to-have-fg.md): Assert that a terminal cell has a specific foreground color
- [toHaveBg](/matchers/to-have-bg.md): Assert that a terminal cell has a specific background color
- [toHaveCursorAt](/matchers/to-have-cursor-at.md): Assert that the terminal cursor is at a specific position
- [toHaveCursorStyle](/matchers/to-have-cursor-style.md): Assert that the terminal cursor has a specific shape
- [toHaveCursorVisible](/matchers/to-have-cursor-visible.md): Assert that the terminal cursor is visible
- [toHaveCursorHidden](/matchers/to-have-cursor-hidden.md): Assert that the terminal cursor is hidden
- [toBeInMode](/matchers/to-be-in-mode.md): Assert that a specific terminal mode is enabled
- [toHaveTitle](/matchers/to-have-title.md): Assert that the terminal has a specific title
- [toHaveScrollbackLines](/matchers/to-have-scrollback-lines.md): Assert that the scrollback buffer has a specific number of lines
- [toBeAtBottomOfScrollback](/matchers/to-be-at-bottom-of-scrollback.md): Assert that the viewport is at the bottom of scrollback
- [toHaveClipboardText](/matchers/to-have-clipboard-text.md): Assert that the terminal has captured specific clipboard text via OSC 52
- [toMatchTerminalSnapshot](/matchers/to-match-terminal-snapshot.md): Match terminal content against a Vitest snapshot
- [toMatchSvgSnapshot](/matchers/to-match-svg-snapshot.md): Match terminal SVG screenshot against a Vitest snapshot

### Advanced

- [Silvery Integration](/advanced/silvery-integration.md): How Termless augments Silvery's virtual buffer tests -- leveraging headless terminals for end-to-end TUI component testing.
- [Conformance Corpus](/advanced/conformance-corpus.md): How Termless mines upstream terminal test suites into engine-agnostic conformance cases and runs them differentially against every backend.
- [The Terminal Runtime Boundary](/advanced/terminal-runtime-boundary.md)
- [Terminal Emulator Differences](/emulator-differences.md): Known behavioral divergences between terminal emulators discovered through cross-backend testing with Termless.

### More

- [Recipes](/guide/recipes.md): Real-world Termless testing patterns for Go, Rust, Python TUI apps, CI integration, and visual regression testing.
- [FAQ](/guide/faq.md): Frequently asked questions about Termless -- backends, CI, Windows support, Jest compatibility, debugging, and mouse events.
- [Comparison](/guide/comparison.md): How Termless compares to pexpect, expect, Playwright, and other terminal testing approaches -- structured state vs byte streams.
- [Why Termless?](/why.md): Terminal apps are hard to test. Termless gives you structured access to terminal state -- cells, colors, cursor, scrollback -- like Playwright but for TUIs.

### Other

- [Contributing](/CONTRIBUTING.md): How to contribute to Termless -- setup, development workflow, testing, and pull request guidelines.