Raxol.Headless (Raxol v2.6.0)

Manages headless Raxol application sessions for non-interactive use.

Starts TEA apps in :agent environment (no terminal driver, no IO output) and provides functions to inspect screen state, send keystrokes, and read the application model. Designed for use via Tidewave project_eval or programmatic testing.

Usage

# Start a session from a module
{:ok, :demo} = Raxol.Headless.start(RaxolDemo, id: :demo)

# Start from an example script (compiles module, skips boot code)
{:ok, :demo} = Raxol.Headless.start("examples/demo.exs", id: :demo)

# Take a text screenshot
{:ok, text} = Raxol.Headless.screenshot(:demo)

# Send a key and see the result
{:ok, text} = Raxol.Headless.send_key_and_screenshot(:demo, :tab)

# Inspect the model
{:ok, model} = Raxol.Headless.get_model(:demo)

# Stop
:ok = Raxol.Headless.stop(:demo)

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_buffer(id)

Returns the raw screen buffer for the session's current frame.

get_model(id)

Returns the application model from the session's dispatcher.

list()

Lists all active sessions. Returns [] if the Headless server is not running.

screenshot(id)

Takes a text screenshot of the session's current screen.

send_key(id, key, opts \\ [])

Sends a key event to the session's dispatcher.

send_key_and_screenshot(id, key, opts \\ [])

Sends a key and returns a screenshot after waiting for re-render.

start(module_or_path, opts \\ [])

Starts a headless session.

start_link(opts \\ [])

Starts the Headless session manager.

stop(id)

Stops a headless session.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_buffer(id)

@spec get_buffer(atom()) :: {:ok, map()} | {:error, term()}

Returns the raw screen buffer for the session's current frame.

Unlike screenshot/1, which returns a text capture, this returns the Raxol.Core.Buffer itself, preserving per-cell style for downstream rendering targets such as the LiveView-to-video pipeline.

get_model(id)

@spec get_model(atom()) :: {:ok, term()} | {:error, term()}

Returns the application model from the session's dispatcher.

list()

@spec list() :: [atom()]

Lists all active sessions. Returns [] if the Headless server is not running.

screenshot(id)

@spec screenshot(atom()) :: {:ok, String.t()} | {:error, term()}

Takes a text screenshot of the session's current screen.

send_key(id, key, opts \\ [])

@spec send_key(atom(), String.t() | atom(), keyword()) :: :ok | {:error, term()}

Sends a key event to the session's dispatcher.

send_key_and_screenshot(id, key, opts \\ [])

@spec send_key_and_screenshot(atom(), String.t() | atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Sends a key and returns a screenshot after waiting for re-render.

Options

:wait_ms - Milliseconds to wait for dispatch processing (default: 50)
All key modifier options (:ctrl, :alt, :shift)

start(module_or_path, opts \\ [])

@spec start(
  module() | String.t(),
  keyword()
) :: {:ok, atom()} | {:error, term()}

Starts a headless session.

First argument is either a module atom or a file path string. When given a path, the file is compiled and the first module defined with a view/1 function is used.

Options

:id - Session identifier (default: module name as atom)
:width - Screen width (default: 120)
:height - Screen height (default: 40)

start_link(opts \\ [])

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

Starts the Headless session manager.

stop(id)

@spec stop(atom()) :: :ok | {:error, term()}

Stops a headless session.