# Termless Headless terminal testing library. Like Playwright, but for terminal apps. Terminal apps are hard to test because the terminal is a black box — you can see text on screen but can't programmatically inspect colors, cursor position, scrollback history, terminal modes, or cell attributes. Termless opens up the entire terminal buffer for structured testing, and runs the same tests against multiple terminal emulators to catch cross-terminal compatibility issues. Two audiences use termless. Most people are here to **test a TUI app** — that's the Playwright-for-terminals pitch above, and it stays the headline. A second, growing audience builds **terminal emulators** and uses termless's differential conformance corpus to grade a new backend against the field; see [Conformance corpus](#conformance-corpus). Built alongside [silvery](https://silvery.dev), a React TUI framework, but works with any terminal app. ![Termless rendered terminal screenshot](docs/public/screenshots/build-pipeline.svg) - **Full terminal internals** -- access scrollback, cursor state, cell colors, terminal modes, alt screen, resize behavior — everything that's invisible to string matching - **Cross-terminal conformance** -- run the same tests against 12 backends — xterm.js, Ghostty, Ghostty (native), Alacritty, WezTerm, vt100, vt100-rust, vt220, vterm.js, libvterm, Kitty, and Peekaboo — to find where terminals disagree - **Composable region selectors** -- `term.screen`, `term.scrollback`, `term.cell(r, c)`, `term.row(n)` for precise assertions - **21+ Vitest matchers** -- text, cell style, cursor, mode, scrollback, and snapshot matchers - **SVG & PNG screenshots** -- fast default renderers (PNG via optional `@resvg/resvg-js`), plus optional Playwright/Chromium rendering for browser-shaped text - **PTY support** -- spawn real processes, send keypresses, wait for output - **Fast** -- typically under 1ms per unit-style test (in-memory backend, no PTY). No Chromium, no subprocesses - **Recording & Playback** -- record terminal sessions as `.tape` files, play back as GIF, animated SVG, APNG, or asciicast. Cross-terminal comparison in one command - **Automation tooling** -- `termless record` / `termless play` for scripting, plus an optional MCP server for AI agents ## Quick Start > Install from npm; a git install resolves the TypeScript source and runs only under Bun. ```typescript import { createTerminal } from "@termless/core" import { createXtermBackend } from "@termless/xtermjs" const GREEN = (s: string) => `\x1b[38;2;0;255;0m${s}\x1b[0m` const term = createTerminal({ backend: createXtermBackend(), cols: 80, rows: 24 }) term.feed(GREEN("● API online")) // String matching sees text. termless sees everything. term.screen.getText() // "● API online" term.cell(0, 0).fg // { r: 0, g: 255, b: 0 } — the color getText() can't see await term.close() ``` ### Spawn a real process ```typescript const term = createTerminal({ backend: createXtermBackend(), cols: 120, rows: 40 }) await term.spawn(["my-tui-app"]) await term.waitFor("ready>") // Keyboard input term.press("ArrowDown") term.type("search query") // Mouse input term.click(10, 5) // click at column 10, row 5 await term.dblclick(10, 5) // double-click (async — two clicks with delay) term.click(10, 5, { ctrl: true }) // ctrl+click // Region selectors — inspect specific parts of the terminal console.log(term.screen.getText()) // visible area console.log(term.scrollback.getText()) // history above screen console.log(term.row(0).getText()) // first row console.log(term.lastRow().getText()) // last row console.log(term.out.getText()) // raw output bytes, including OSC/APC/CSI protocols const svg = term.screenshotSvg() const png = await term.screenshot() // auto-picker: native canvas (@napi-rs/canvas + ghostty-web) with resvg fallback const canvasPng = await term.screenshotCanvasPng() // explicit native-canvas (requires @termless/ghostty) const resvgPng = await term.screenshotPng() // explicit resvg (requires @resvg/resvg-js) await term.close() ``` ### Write tests ```typescript import { test, expect } from "vitest" import { createTestTerminal } from "@termless/test" // ANSI helpers — real apps use silvery or chalk, these are just for test data const BOLD = (s: string) => `\x1b[1m${s}\x1b[0m` const GREEN = (s: string) => `\x1b[38;2;0;255;0m${s}\x1b[0m` test("inspect what string matching can't see", () => { // Creates an xterm.js terminal by default. Ghostty, Alacritty, WezTerm, vt100, // and Peekaboo backends are also available — see Multi-Backend Testing below. const term = createTestTerminal({ cols: 40, rows: 3 }) // Simulate a build pipeline — 4 lines overflow a 3-row terminal term.feed("Step 1: install\r\n") term.feed(`Step 2: ${GREEN("build ok")}\r\n`) term.feed(`Step 3: ${BOLD("test")}\r\n`) term.feed("Step 4: deploy") // Region selectors — screen, scrollback, buffer expect(term.scrollback).toContainText("install") // scrolled off, still in history expect(term.screen).toContainText("deploy") // visible area expect(term.buffer).toContainText("install") // everything (scrollback + screen) expect(term.row(0)).toHaveText("Step 2: build ok") // specific row // Cell styles — colors that getText() can't see expect(term.cell(0, 8)).toHaveFg("#00ff00") // "build ok" is green expect(term.cell(1, 8)).toBeBold() // "test" is bold // Scroll up, then assert on viewport term.backend.scrollViewport(1) expect(term.viewport).toContainText("install") // Resize — verify content survives term.resize(20, 3) expect(term.screen).toContainText("deploy") // Terminal state — window title, cursor, modes term.feed("\x1b]2;Build Pipeline\x07") // OSC 2 — set window title expect(term).toHaveTitle("Build Pipeline") expect(term).toHaveCursorAt(14, 2) // after "Step 4: deploy" expect(term).toBeInMode("autoWrap") // default mode expect(term).not.toBeInMode("altScreen") // not in alternate screen }) ``` None of this is possible with `expect(output).toContain("text")`. String matching can't see colors, can't inspect scrollback, can't verify cursor position, can't test resize behavior, and can't query terminal capabilities. Termless gives you the full terminal state machine. **Cross-terminal differences are real.** Emoji width, color palette mapping, scroll region behavior, key encoding, Kitty keyboard protocol support, and hyperlink handling all differ between terminals. Run the same test against xterm.js and Ghostty and you'll find them. The `cross-backend.test.ts` suite runs 120+ conformance tests across all backends, catching differences automatically in CI. ## Region Selectors The composable API separates **where** to look from **what** to assert: ```typescript // Region selectors (getter properties — no parens) term.screen // the rows x cols visible area term.scrollback // history above screen term.buffer // everything (scrollback + screen) term.viewport // current scroll position view // Region selectors (methods with args) term.row(n) // screen row (negative from bottom) term.cell(row, col) // single cell term.range(r1, c1, r2, c2) // rectangular region term.firstRow() // first screen row term.lastRow() // last screen row ``` Then assert using the appropriate matchers for each view type: ```typescript // Text matchers work on Region (screen, scrollback, buffer, viewport, row, range) expect(term.screen).toContainText("Hello") expect(term.row(0)).toHaveText("Title") expect(term.screen).toMatchLines(["Line 1", "Line 2"]) // Style matchers work on CellView expect(term.cell(0, 0)).toBeBold() expect(term.cell(0, 0)).toHaveFg("#ff0000") expect(term.cell(2, 5)).toHaveUnderline("curly") // Terminal matchers work on the terminal itself expect(term).toHaveCursorAt(5, 0) expect(term).toBeInMode("altScreen") expect(term).toHaveTitle("My App") // Raw output matchers work on term.out for protocol bytes that do not render await expect(term.out).toContainOutput("\x1b_G", { timeout: 5000 }) ``` ## Matchers Reference ### Text Matchers (on Region / Row) | Matcher | Description | | ----------------------- | -------------------------------------------------------- | | `toContainText(text)` | Region contains text as substring | | `toHaveText(text)` | Region text matches exactly (trimmed) | | `toMatchLines(lines[])` | Lines match expected array (trailing whitespace trimmed) | ### Raw Output Matchers (on RawOutput) Use `term.out` when you need the literal output stream before terminal parsing, such as Kitty graphics APC packets, OSC clipboard/title sequences, CSI mode toggles, or other protocols that may leave no visible cells. | Matcher | Description | | ----------------------- | ----------------------------------------------------------- | | `toContainOutput(text)` | Raw output stream contains text/protocol bytes as substring | ```typescript term.feed("\x1b_Ga=p,i=7;payload\x1b\\") await expect(term.out).toContainOutput("\x1b_Ga=p", { timeout: 5000 }) term.out.clear() // useful before asserting cleanup/delete protocol output ``` ### Cell Style Matchers (on CellView) | Matcher | Description | | ------------------------- | --------------------------------------------------------------------------------------------- | | `toBeBold()` | Cell is bold | | `toBeItalic()` | Cell is italic | | `toBeFaint()` | Cell is faint/dim | | `toBeStrikethrough()` | Cell has strikethrough | | `toBeInverse()` | Cell has inverse video | | `toBeWide()` | Cell is double-width (CJK, emoji) | | `toHaveUnderline(style?)` | Cell has underline; optional style: `"single"`, `"double"`, `"curly"`, `"dotted"`, `"dashed"` | | `toHaveFg(color)` | Foreground color (`"#rrggbb"` or `{ r, g, b }`) | | `toHaveBg(color)` | Background color (`"#rrggbb"` or `{ r, g, b }`) | ### Terminal Matchers (on Terminal) | Matcher | Description | | ---------------------------- | ------------------------------------------------ | | `toHaveCursorAt(x, y)` | Cursor at position | | `toHaveCursorVisible()` | Cursor is visible | | `toHaveCursorHidden()` | Cursor is hidden | | `toHaveCursorStyle(style)` | Cursor style: `"block"`, `"underline"`, `"beam"` | | `toBeInMode(mode)` | Terminal mode is enabled | | `toHaveTitle(title)` | OSC 2 title matches | | `toHaveScrollbackLines(n)` | Scrollback has N total lines | | `toBeAtBottomOfScrollback()` | Viewport at bottom (no scroll offset) | | `toMatchTerminalSnapshot()` | Vitest snapshot of terminal state | ## Installation ```bash npm install -D @termless/test # Vitest matchers + fixtures (bundles default xterm.js fixture) npm install -D @resvg/resvg-js # Optional: PNG screenshot support npm install -D playwright # Optional: browser-shaped PNG screenshots npx playwright install chromium # Optional: Chromium binary for browser-shaped PNG screenshots npm install node-pty # Optional: PTY support on Node.js (not needed on Bun) ``` ### Available Backends Every backend implements the same `TerminalBackend` interface — write tests once, run against any: | Backend | Engine | What It Is | Type | Default | | -------------- | ----------------------- | ---------------------------------------------------------------------------------------- | ------ | ------- | | **xtermjs** | @xterm/headless 6.0 | The terminal emulator inside VS Code. Most battle-tested. | JS | Yes | | **ghostty** | ghostty-web 0.4 | Ghostty's GPU-accelerated VT parser via WASM. Best standards compliance, Kitty keyboard. | WASM | Yes | | **vt100** | (built-in) | Pure TypeScript, zero dependencies. Lightning fast, great for CI. | JS | Yes | | **alacritty** | alacritty_terminal 0.25 | Alacritty's Rust VT parser via napi-rs. Strong reflow. | Native | No | | **wezterm** | wezterm-term | WezTerm's parser — broadest feature set: sixel, semantic prompts. | Native | No | | **peekaboo** | (OS automation) | Launches a real terminal app, captures via OS accessibility APIs. macOS only. | OS | No | | **vt100-rust** | vt100 0.15 (Rust) | Reference Rust implementation — cross-validates the TS vt100 backend. | Native | No | | **libvterm** | libvterm (neovim) | Neovim's C VT parser via WASM. Different implementation = different bugs found. | WASM | No | | **kitty** | kitty (C, GPL source) | Kitty's parser built from source. Only backend with Kitty graphics protocol. | Native | No | See the [Backend Capability Matrix](https://termless.dev/guide/backends) for detailed per-backend features, limitations, and usage examples (factory function + string name). Ghostty's `getUnhandledSequences()` reports OSC command numbers from its engine warnings, without payloads, and shares their `clearWarnings()` lifetime. ### Backend Management Termless includes a Playwright-inspired CLI for managing backends. `backends.json` pins all versions — upgrade termless, upgrade all backends: ```bash bunx termless backends # List all backends and install status bunx termless backends install # Install default backends (xtermjs, ghostty, vt100) bunx termless backends install ghostty alacritty # Install specific backends bunx termless doctor # Health check all installed backends bunx termless backends update # Check upstream for newer versions ``` ### Terminal Census Run standardized probes against all backends to generate a capability matrix: ```bash bun census ``` See the full interactive matrix at [terminfo.dev](https://terminfo.dev). ### Programmatic Backend Selection Two ways to choose a backend: ```typescript // 1. Factory function (explicit import, sync) import { createXtermBackend } from "@termless/xtermjs" const term = createTerminal({ backend: createXtermBackend(), cols: 80, rows: 24 }) // 2. By name (async — handles WASM init, native loading) import { backend } from "@termless/core" const b = await backend("ghostty") const term = createTerminal({ backend: b, cols: 80, rows: 24 }) ``` ## Runtime Compatibility Termless works on both **Bun** (>=1.0) and **Node.js** (>=23.6). | Feature | Bun | Node.js | | --------------------------------------- | --------------------- | ------------------- | | Pure backends (xtermjs, ghostty, vt100) | Built-in | Built-in | | PTY spawn (`terminal.spawn()`) | Built-in (native PTY) | Requires `node-pty` | | SVG screenshots | Built-in | Built-in | | PNG screenshots | `@resvg/resvg-js` | `@resvg/resvg-js` | | Playwright PNG screenshots | `playwright` | `playwright` | | Peekaboo (OS automation) | macOS only | macOS only | | napi-rs backends (alacritty, wezterm) | Needs Rust build | Needs Rust build | On Node.js, PTY support requires `node-pty` as an optional peer dependency. If not installed, `terminal.spawn()` throws a clear error with installation instructions. All other features (feeding data, backends, screenshots, matchers) work without it. ## Which Package Do I Need? | You want to... | Install | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | Test a terminal UI in Vitest | `@termless/test` (bundles the default xterm.js fixture) | | Use the core Terminal API without test matchers | `@termless/core` + a backend (`@termless/xtermjs`, etc.) | | Test against Ghostty's VT parser | `@termless/ghostty` | | Test with a zero-dependency emulator | `@termless/vt100` | | Take SVG/PNG screenshots | Built into `@termless/core` (PNG needs `@resvg/resvg-js`; browser-shaped PNG needs `playwright`) | | Spawn and test real processes via PTY | Built into `@termless/core` (used via any backend) | | Automate a real terminal app (OS-level) | `@termless/peekaboo` | | Embed `.cast` / `.tape` playback in browser docs | `@termless/web-player` | | Use the CLI or MCP server | `@termless/cli` | Most test suites start with `@termless/test`. Add backend packages for multi-backend testing, `@termless/peekaboo` for real terminal automation, or `@termless/web-player` when publishing recordings in browser docs. `@termless/web-player/browser` creates a player synchronously. Browser bundlers use the static xterm.js entry; Node and Bun load xterm.js on the first call that needs a default terminal. Importing the entry or passing an existing `terminal` does not load xterm.js in Node or Bun. Creating a default terminal still requires a browser DOM. With a DOM shim under Bun, xterm.js can retain a process listener even after player disposal; import-only checks do not establish natural process exit after default-terminal creation. ## Multi-Backend Testing Test your TUI against multiple terminal emulators with a single test suite. Write tests once, configure backends via vitest workspace: ```typescript // vitest.workspace.ts — add as many backends as you want export default [ { test: { name: "xterm", setupFiles: ["./test/setup-xterm.ts"] } }, { test: { name: "ghostty", setupFiles: ["./test/setup-ghostty.ts"] } }, { test: { name: "vt100", setupFiles: ["./test/setup-vt100.ts"] } }, // Also available: alacritty, wezterm (require Rust build), peekaboo (OS-level) ] ``` ```typescript // test/setup-xterm.ts // test/setup-ghostty.ts import { createXtermBackend } import { createGhosttyBackend } from "@termless/xtermjs" from "@termless/ghostty" globalThis.createBackend = globalThis.createBackend = () => createXtermBackend() () => createGhosttyBackend() // test/setup-vt100.ts — pure TypeScript, zero native deps import { createVt100Backend } from "@termless/vt100" globalThis.createBackend = () => createVt100Backend() ``` Your tests use `globalThis.createBackend()` and run against every configured backend automatically. `vitest` runs the entire test suite once per workspace entry — same tests, different terminal emulators. See [docs/guide/multi-backend.md](docs/guide/multi-backend.md). ## Cross-Backend Conformance All backends are tested for conformance via `cross-backend.test.ts` — text rendering, SGR styles, cursor positioning, modes, scrollback, capabilities, key encoding, unicode, and cross-backend output comparison. Run with: ```bash bun vitest run tests/cross-backend.test.ts ``` ## Conformance corpus Testing _your_ app across backends (above) asks whether your output holds steady. The conformance corpus asks the opposite question: is the **backend itself** correct? The differential runner takes cases mined from other engines' own test suites and runs each one against every registered backend, diffing the resulting terminal state — a divergence is either a bug or a documented, ledgered gap. Today that's two borrowed suites, both MIT: [Ghostty](https://github.com/ghostty-org/ghostty)'s inline Zig unit tests (24 mechanically-converted cases) and [neovim's libvterm](https://github.com/neovim/libvterm) reference test suite (128 cases). License policy is strict: only MIT/Apache/BSD-family suites get mirrored into `raw/`; a GPL suite (kitty, esctest, VTE) is never vendored and never line-ported into a case — the only legal paths are a side-by-side oracle backend or clean-room re-authoring from the spec. Engine gaps are data, not red tests. `known-gaps.json` maps `::::` to a reason, and the ledger ratchets both ways: an un-ledgered failure fails the build (regression or new case), and a ledgered gap that starts passing _also_ fails, until someone removes the entry. **Grading your own backend:** implement `TerminalBackend`, add a `[name, factory]` entry next to the existing ones in `tests/corpus-conformance.test.ts`, and run the corpus test. A consumable entry point via `@termless/test` — so grading a backend doesn't require patching termless's own test file — is planned, no date yet. The full contract (case schema, suite directory shape, growth triggers) is [`corpus/README.md`](corpus/README.md); the narrative version is on the [docs site](https://termless.dev/advanced/conformance-corpus). ## How it connects Termless is the **read** end of a terminal stack. One kind of thing arrives — timestamped bytes — and every feature above is a different question asked of the same fold of those bytes into a screen. ```text bytes in term.feed(…) · term.spawn(…) · a recording read off disk ↓ backend one TerminalBackend folds bytes into cells, cursor, modes ↓ Terminal the read contract — screen · scrollback · buffer · viewport · row · cell ↓ out assert (matchers) · render (SVG/PNG) · re-emit (.tty, .cast, .tape) ``` Read each arrow as _hands bytes to_, never as _depends on_. Termless sits downstream of whatever produced the bytes and is never a dependency of it — see the runtime boundary note at the bottom of this file. **The three inlets are one inlet.** `term.feed()` in a unit test, `term.spawn()` against a real process, and a recording replayed off disk all arrive at the backend the same way: ordered byte writes, nothing else. A recording is exactly that sequence made durable — `IoEvent { at, direction, data }` on a monotonic microsecond clock. That is not a convenience; it is what lets an assertion you wrote against a live terminal run unchanged against a stored one, and the reverse. **An external recorder can hand you a session without a dependency edge.** `replayJournal(input, target)` folds a session journal into anything shaped like a terminal (`TestTerminal` and `TerminalBackend` both qualify), and its input types are **structural** — deliberately no import of the package that produced the journal. Producers convert their own journal into that shape; termless stays standalone. Same discipline as the `.tty` format itself: a shared wire contract, not a shared library. **Waiting for the screen to say something is a predicate over that fold.** Every text and terminal matcher takes `{ timeout }` and re-reads until it holds: ```typescript await expect(term.screen).toContainText("ready>", { timeout: 15000 }) ``` Because the fold is identical whether the frames arrive live or from a file, **a check like that can be unit-tested against a recording** — record the session once, then develop the predicate offline against fixed bytes instead of against a flaky live process. The ergonomic layer for _live_ reads is **specified but not built**. [`docs/reference/formats/tty.md`](docs/reference/formats/tty.md) § "Session access" names the vocabulary a live reader conforms to — a widened frame element (`{ t_us, dir: "in" | "out" | "err" | "resize", data }`), an opaque read cursor, a `SessionClose` tombstone, and `follow: false | true` for halt-at-end versus park-past-end. `termless/session` is reserved for that reader and does not exist yet. Today, live reads are what you build yourself on `term.spawn()` and the timeout matchers. **The format is the boundary, so nothing needs our code to watch our recordings.** `.tty` (live bundle directory) and `.ttyz` (sealed ZIP archive) are one format in two encodings behind one encoding-blind reader; codecs go out to `.cast` (symmetric asciicast v2), `.tape`, and ttyrec (import-only). `termless play` reads one and renders it through an ordinary backend — no privileged path — and [`@termless/web-player`](packages/web-player) plays one in a browser. Anything that can read the format is a player. **Grading an engine is the same read again.** The [conformance corpus](#conformance-corpus) above drives every backend through the ordinary `TerminalBackend` seam — there is no test-only door into any emulator, so a passing grade is evidence about the code that ships. ### Published shape, and the backend-arity rule The bare `termless` package is a re-export facade over `@termless/core` — nothing moved, and it adds no engine. What it adds is a name for each layer above, at its own subpath: | Subpath | What it is | | ------------------- | -------------------------------------------------------------- | | `termless` | the curated top — `createTerminal` and the common driving path | | `termless/contract` | `Terminal`, `TerminalBackend`, and the region view types | | `termless/fmt` | the `.tty` / `.ttyz` container — read/write, pack/unpack | | `termless/rec` | `Recording`, codecs, and journal replay | | `termless/backends` | backend selection by name — install, build, resolve | The first four are engine-agnostic by construction: nothing in them can name, select, or install a specific terminal emulator. `termless/backends` is the **only** home of plurality, which makes the arity rule physical in the import path rather than a convention anyone has to remember — _if you never import `termless/backends`, you never have more than one engine._ ## Packages | Package | Description | | ------------------------------------------- | ------------------------------------------------------------------- | | [termless](.) | Core: Terminal, PTY, SVG/PNG screenshots, key mapping, region views | | [@termless/xtermjs](packages/xtermjs) | xterm.js backend (`@xterm/headless`) | | [@termless/ghostty](packages/ghostty) | Ghostty backend (`ghostty-web` WASM) | | [@termless/vt100](packages/vt100) | Pure TypeScript VT100 emulator (zero native deps) | | [@termless/alacritty](packages/alacritty) | Alacritty backend (`alacritty_terminal` via napi-rs) | | [@termless/wezterm](packages/wezterm) | WezTerm backend (`wezterm-term` via napi-rs) | | [@termless/peekaboo](packages/peekaboo) | OS-level terminal automation (xterm.js + real app) | | [@termless/web-player](packages/web-player) | Browser xterm.js player for `.cast` / `.tape` playback | | [@termless/vt100-rust](packages/vt100-rust) | Rust vt100 crate via napi-rs (reference implementation) | | [@termless/libvterm](packages/libvterm) | neovim's libvterm via Emscripten WASM | | [@termless/kitty](packages/kitty) | Kitty VT parser built from GPL source (not distributed) | | [@termless/test](packages/viterm) | Vitest matchers, fixtures, and snapshot serializer | | [@termless/cli](packages/cli) | CLI (`termless record`, `termless play`) + MCP server | ## How Termless Compares Termless is the **only** headless terminal testing library that supports multi-backend testing with composable matchers: | Feature | Termless | Playwright + xterm.js | TUI Test | ttytest2 | pexpect | Textual | Ink | | ------------------------- | ---------------------------------------- | ----------------------- | ---------------- | ------------ | ------- | ------- | --- | | **Terminal internals** | ✅ scrollback, cursor, modes, cell attrs | ⚠️ xterm.js buffer only | ❌ | ❌ | ❌ | ⚠️ | ❌ | | **Multi-backend** | ✅ 12 backends | ❌ xterm.js only | ❌ xterm.js only | ❌ tmux only | ❌ | ❌ | ❌ | | **Composable selectors** | ✅ 8 types | ❌ | ❌ | ❌ | ❌ | ⚠️ | ❌ | | **Visual matchers** | ✅ 21+ | ❌ DIY | ⚠️ | ❌ | ❌ | ⚠️ | ❌ | | **Protocol capabilities** | ✅ Kitty, sixel, OSC 8, reflow | ❌ xterm.js subset | ❌ | ❌ | ❌ | ❌ | ❌ | | **SVG & PNG screenshots** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | **No browser required** | ✅ optional for browser PNG | ❌ needs Chromium | ✅ | ✅ | ✅ | ✅ | ✅ | | **Framework-agnostic** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | **TypeScript** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ## Documentation **[Full documentation site](https://termless.dev/)** - [Getting Started](https://termless.dev/guide/getting-started) -- install, first test, run it - [Writing Tests](https://termless.dev/guide/writing-tests) -- matchers, fixtures, assertion patterns - [Screenshots](https://termless.dev/guide/screenshots) -- SVG & PNG screenshots, themes, custom fonts - [Best Practices](https://termless.dev/guide/best-practices) -- avoiding flaky tests, PTY timing, selectors - [Multi-Backend Testing](https://termless.dev/guide/multi-backend) -- test against any backend - [Backend Capabilities](https://termless.dev/guide/backends) -- which backends support what - [Recording & Playback](https://termless.dev/guide/recording-sessions) -- record, play, GIF/SVG/APNG output - [Tape Format](https://termless.dev/reference/formats/tape) -- `.tape` file reference - [Asciicast v2](https://termless.dev/reference/formats/asciicast) -- asciinema compatibility - [CLI & MCP](https://termless.dev/reference/cli) -- CLI usage and MCP server - **API Reference**: [Terminal](https://termless.dev/api/terminal) | [Backend](https://termless.dev/api/backend) | [Cell & Types](https://termless.dev/api/cell) | [Matchers](https://termless.dev/api/matchers) ## Recording & Playback Record terminal sessions and play them back as animated output -- no ffmpeg, no Chromium: ```bash # Record a command to a tape file termless record -o demo.tape -- ls -la # Play back as an animated GIF termless play -o demo.gif demo.tape # Play a native bundle/archive: prefer non-empty commands, else disclose io termless play demo.ttyz termless play --source=io demo.tty # Cross-terminal comparison termless play -b vterm,ghostty --compare side-by-side demo.tape # Scripted recording with inline tape commands termless rec -t 'Type "hello"\nEnter\nScreenshot' -- bash # Record to asciicast format termless record -o demo.cast -- my-app ``` Output formats: GIF, animated SVG, APNG, PNG, asciicast v2 -- all pure JS, no ffmpeg. See the [Recording & Playback docs](https://termless.dev/guide/recording-sessions) for full details. ## CLI & MCP Server For scripting and AI agents, `@termless/cli` provides recording, playback, and an MCP server: ```bash # Record and play terminal sessions termless record -o demo.tape -- ls -la termless play -o demo.gif demo.tape # Capture mode: run command, press keys, take screenshot termless record --keys j,j,Enter -o /tmp/out.svg -- bun km view /path # MCP server for AI agents (Claude Code, etc.) termless mcp ``` See the [CLI & MCP docs](https://termless.dev/reference/cli) for full options. ## See Also **[silvery](https://silvery.dev)** -- if Termless is for _testing_ terminal apps, silvery is for _building_ them. A React TUI framework that fully leverages modern terminal features (truecolor, Kitty keyboard protocol, mouse events, images, scroll regions) and generates all the ANSI codes automatically. Write terminal UIs in familiar React/JSX — silvery handles the terminal complexity. Use `@termless/test` to verify your silvery app renders correctly across terminals. ## License MIT > **Runtime boundary:** Termless is TEST/DEV infrastructure — recording, > replay, conformance, and visual fixtures. It is never a Hab runtime > dependency; runtime terminal persistence lives in km's terminal-session > substrate, which Termless consumes through structurally-typed journal > fixtures (see src/recording/journal-replay.ts).