Matcher Reference

Termless provides 25 custom Vitest matchers for terminal assertions. All matchers support .not negation.

import "@termless/test/matchers" // Auto-registers all matchers

Composable Matchers

Assert multiple properties at once with partial matching. These are the recommended API.

• toHaveAttrs - Assert cell attributes (bold, italic, fg, bg, etc.)
• toHaveCursor - Assert cursor properties (position, visibility, style)

Text Matchers

Work on Region (screen, scrollback, row, range).

• toContainText - Assert region contains text substring
• toHaveText - Assert exact text match (after trimming)
• toMatchLines - Assert multi-line content

Raw Output Matchers

Work on RawOutput via term.output for protocol bytes before terminal parsing.

• toContainOutput - Assert raw output contains text or protocol bytes

Style Matchers prefer toHaveAttrs

Work on Cell via term.cell(row, col). Prefer toHaveAttrs for new code.

• toBeBold - Assert bold styling
• toBeItalic - Assert italic styling
• toBeDim - Assert dim/faint styling
• toBeStrikethrough - Assert strikethrough
• toBeInverse - Assert inverse/reverse video
• toBeWide - Assert double-width character
• toHaveUnderline - Assert underline with optional style
• toHaveFg - Assert foreground color
• toHaveBg - Assert background color

Cursor Matchers prefer toHaveCursor

Work on Terminal (the terminal itself). Prefer toHaveCursor for new code.

• toHaveCursorAt - Assert cursor position
• toHaveCursorStyle - Assert cursor shape
• toHaveCursorVisible - Assert cursor is visible
• toHaveCursorHidden - Assert cursor is hidden

Terminal State Matchers

Work on Terminal (the terminal itself).

• toBeInMode - Assert terminal mode is enabled
• toHaveTitle - Assert terminal title
• toHaveScrollbackLines - Assert scrollback line count
• toBeAtBottomOfScrollback - Assert no scroll offset
• toHaveClipboardText - Assert OSC 52 clipboard content

Snapshot Matchers

Work on Terminal (the terminal itself).

• toMatchTerminalSnapshot - Match against Vitest snapshot
• toMatchSvgSnapshot - Match SVG screenshot against snapshot