Ghostty.Test (Ghostty v0.4.0)

ExUnit helpers for terminal-oriented tests.

These helpers keep Ghostty.Terminal focused on the core emulator API while making test code concise for common tasks: render iodata, inspect plain/HTML snapshots, assert visible text, and encode keyboard input.

Import this module in tests:

import Ghostty.Test

{:ok, term} = term(cols: 80, rows: 24)
write(term, ["Hello", "

"])

assert_text(term, "Hello")

Summary

Types

snapshot_source()

terminal()

Functions

assert_cell(term, position, grapheme, opts \\ [])

Asserts a cell's grapheme and optional style properties.

assert_html(term, expected)

Asserts against an HTML snapshot.

assert_snap(source, path, opts \\ [])

Asserts a snapshot against a fixture file.

assert_text(source, expected)

Asserts that a terminal/text snapshot includes a string or matches a regex.

assert_vt(term, expected)

Asserts against a VT snapshot.

cell(term, arg)

Returns the cell at {x, y} using zero-based coordinates.

cells(term)

Returns terminal cells.

event(key, opts \\ [])

Builds a Ghostty.KeyEvent with defaults for tests.

html(term)

Shortcut for an HTML snapshot.

key(term, event_or_key, opts \\ [])

Encodes a key event through Ghostty's terminal encoder.

key_bytes(event_or_key, opts \\ [])

Encodes a key event using a short-lived terminal.

lines(term, lines)

Writes lines separated with CRLF and returns the terminal.

plain(term)

Shortcut for a plain-text snapshot.

refute_html(term, expected)

Refutes against an HTML snapshot.

refute_text(source, expected)

Refutes that a terminal/text snapshot includes a string or matches a regex.

refute_vt(term, expected)

Refutes against a VT snapshot.

snap(term, format \\ :plain)

Returns a terminal snapshot. Defaults to :plain.

term(opts \\ [])

Starts a Ghostty.Terminal for tests.

vt(term)

Shortcut for a VT snapshot.

write(term, data)

Writes iodata to the terminal and returns the terminal.

write_key(term, key_or_event, opts \\ [])

Encodes a key and writes the resulting bytes to the terminal.

Types

snapshot_source()

@type snapshot_source() :: terminal() | binary()

terminal()

@type terminal() :: GenServer.server()

Functions

assert_cell(term, position, grapheme, opts \\ [])

@spec assert_cell(
  terminal(),
  {non_neg_integer(), non_neg_integer()},
  binary(),
  keyword()
) :: terminal()

Asserts a cell's grapheme and optional style properties.

assert_html(term, expected)

@spec assert_html(terminal(), String.t() | Regex.t()) :: terminal()

Asserts against an HTML snapshot.

assert_snap(source, path, opts \\ [])

@spec assert_snap(snapshot_source(), Path.t(), keyword()) :: snapshot_source()

Asserts a snapshot against a fixture file.

Set UPDATE_GHOSTTY_SNAPSHOTS=1 to rewrite fixtures.

assert_text(source, expected)

@spec assert_text(snapshot_source(), String.t() | Regex.t()) :: snapshot_source()

Asserts that a terminal/text snapshot includes a string or matches a regex.

assert_vt(term, expected)

@spec assert_vt(terminal(), String.t() | Regex.t()) :: terminal()

Asserts against a VT snapshot.

cell(term, arg)

@spec cell(
  terminal(),
  {non_neg_integer(), non_neg_integer()}
) :: Ghostty.Terminal.cell()

Returns the cell at {x, y} using zero-based coordinates.

cells(term)

@spec cells(terminal()) :: [[Ghostty.Terminal.cell()]]

Returns terminal cells.

event(key, opts \\ [])

@spec event(
  Ghostty.KeyEvent.key(),
  keyword()
) :: Ghostty.KeyEvent.t()

Builds a Ghostty.KeyEvent with defaults for tests.

html(term)

@spec html(terminal()) :: binary()

Shortcut for an HTML snapshot.

key(term, event_or_key, opts \\ [])

@spec key(terminal(), Ghostty.KeyEvent.key() | Ghostty.KeyEvent.t(), keyword()) ::
  {:ok, binary()} | :none

Encodes a key event through Ghostty's terminal encoder.

key_bytes(event_or_key, opts \\ [])

@spec key_bytes(
  Ghostty.KeyEvent.key() | Ghostty.KeyEvent.t(),
  keyword()
) :: binary() | :none

Encodes a key event using a short-lived terminal.

lines(term, lines)

@spec lines(terminal(), [iodata()]) :: terminal()

Writes lines separated with CRLF and returns the terminal.

plain(term)

@spec plain(terminal()) :: binary()

Shortcut for a plain-text snapshot.

refute_html(term, expected)

@spec refute_html(terminal(), String.t() | Regex.t()) :: terminal()

Refutes against an HTML snapshot.

refute_text(source, expected)

@spec refute_text(snapshot_source(), String.t() | Regex.t()) :: snapshot_source()

Refutes that a terminal/text snapshot includes a string or matches a regex.

refute_vt(term, expected)

@spec refute_vt(terminal(), String.t() | Regex.t()) :: terminal()

Refutes against a VT snapshot.

snap(term, format \\ :plain)

@spec snap(terminal(), Ghostty.Terminal.format()) :: binary()

Returns a terminal snapshot. Defaults to :plain.

term(opts \\ [])

@spec term(keyword()) :: GenServer.on_start()

Starts a Ghostty.Terminal for tests.

vt(term)

@spec vt(terminal()) :: binary()

Shortcut for a VT snapshot.

write(term, data)

@spec write(terminal(), iodata()) :: terminal()

Writes iodata to the terminal and returns the terminal.

write_key(term, key_or_event, opts \\ [])

@spec write_key(terminal(), Ghostty.KeyEvent.key() | Ghostty.KeyEvent.t(), keyword()) ::
  terminal()

Encodes a key and writes the resulting bytes to the terminal.