Testing

Testing & Automation

MonoTerm has two interfaces for automation: test for UI verification and ctl for controlling a running instance. Both are currently available on macOS and Linux only. The interactive MonoTerm TUI also ships for Windows, but Windows ctl and test return a non-zero error until named-pipe and ConPTY transports are implemented.

monoterm test

monoterm test spawns a fresh MonoTerm in a real pseudo-terminal and sends keystrokes through the same path as a human typing. It does not require a human to operate the terminal.

monoterm test                 # run all 28 checks
monoterm test auto            # explicit alias for the full suite
monoterm test all             # another full-suite alias
monoterm test spawn           # spawn and show the initial screen
monoterm test run             # alias for spawn
monoterm test key @           # send @ and show the resulting screen
monoterm test key tab         # send Tab
monoterm test key ctrl+b      # send Ctrl+B
monoterm test key hello       # type text
monoterm test mouse           # inject SGR right-click bytes
monoterm test help            # list test commands and aliases

test key recognizes @, tab, esc, enter, j, k, arrow keys, ctrl+b, and arbitrary text. It is a one-event screen probe, not the complete suite. Example: verify prompt box opens

$ monoterm test key @

Screen after '@':
 FILES                       │...
│ ...                         │     ── Prompt ─────────────
│ ...                         │       Type, / for commands, Ctrl+J: newline
│ ...                         │       Enter:send  Ctrl+J:newline  Tab:accept  Esc:cancel
 Tab:files                   │

The files shown on the left depend on the test process’s working directory; the stable proof is the tree, prompt, and focus/action hints.

Complete automated suite

The default, auto, and all forms run 28 checks across 16 ordered sections:

Section	What it proves
Startup	Sidebar and initial shell tab render.
Shell	A usable shell prompt appears.
Prompt Box (`@`)	Prompt overlay and `FILES` tree appear.
Tab to tree	Focus reaches the tree and its insertion hint appears.
Tree search	Typed text filters the tree.
Tab back to prompt	Focus returns to prompt input.
Type in prompt	Text lands in the prompt and not in the tree query.
Esc close	The prompt overlay closes.
Sidebar toggle	`Ctrl+B` hides and restores the sidebar.
New Tab dialog	`Ctrl+T` opens the Where selector.
Cancel dialog	`Esc` closes the selector.
`ctl status`	The live control socket returns valid status and dimensions.
`ctl tab-list`	The tab response includes a session identity.
`ctl write echo`	Socket-level text reaches the PTY and rendered screen.
`ctl subscribe-pty`	Subscription acknowledgement and PTY data both arrive.
Spotlight palette	`Ctrl+K` opens, filters to `/tabs`, and closes.

The harness polls for the required UI state within a bounded timeout. It does not accept a single fixed-delay snapshot, which could capture a partially drawn prompt or autocomplete redraw.

$ monoterm test

--- 1. Startup ---
  PASS  TABS sidebar
  PASS  shell tab listed

...

--- 16. Spotlight palette ---
  PASS  palette opens
  PASS  filter shows /tabs
  PASS  palette dismissed

==================
28/28 passed

Mouse pipeline probe

monoterm test mouse injects SGR right-click sequences into the test PTY and passes only when MonoTerm parses those bytes and renders its menu. A pass proves the MonoTerm parser/rendering path; it does not prove that a particular host terminal forwards mouse events.

monoterm ctl

monoterm ctl controls the newest live MonoTerm instance through a newline-delimited JSON Unix socket. It cleans sockets whose owning process has exited. These commands bypass MonoTerm keybindings and operate at the PTY layer.

monoterm ctl help                # command reference
monoterm ctl status              # dimensions, tabs, socket identity
monoterm ctl tabs                # list labels and active marker
monoterm ctl read                # read from the last % prompt match
monoterm ctl read error          # read from the last query match
monoterm ctl run 'ls -la'        # send command plus Enter
monoterm ctl write 'partial'     # send raw text without Enter
monoterm ctl ctrl-c              # send Ctrl+C

The socket is ~/Library/Application Support/Monolex/runtime/sockets/monoterm/control-{PID}.sock. ctl read defaults to %, which matches the default zsh prompt; pass '$' for a typical bash prompt or supply another query. ctl tabs is a tab-label view. In 0.4.17, its per-row sessionId repeats the active session ID; raw session-list owns the real session inventory. The raw parser also accepts 11 messages, but tab-new, tab-switch, and tab-close currently fail closed, while simulate-key executes only PTY mappings and selected non-blocking actions. See the raw protocol table before building directly on the socket. Example: run a command and read output

$ monoterm ctl run 'echo hello'
ok

$ monoterm ctl read hello
hello
macbook@NIIA ~ %

When to use which

	`test`	`ctl`
Target	New instance	Running instance
Input layer	Real crossterm key events, plus selected socket/stream probes	Direct PTY socket commands
Best for	UI and integration verification	Shell automation and current-screen inspection
Side effects	Creates and closes a test instance	Reads or mutates the selected live instance
Platform	macOS and Linux	macOS and Linux

Get Started

Articles

So Anthropic

User Guide

Philosophy

Applied Philosophy

Architecture

Gestalt Color

Transparency

Terminal Core

Features

VariableMD

Research

CodexMono

OpenCLIs

vpncli

MonoSurf

AI-CLIs

Testing & Automation

monoterm test

Complete automated suite

Mouse pipeline probe

monoterm ctl

When to use which

​Testing & Automation

​monoterm test

​Complete automated suite

​Mouse pipeline probe

​monoterm ctl

​When to use which

Testing & Automation

monoterm test

Complete automated suite

Mouse pipeline probe

monoterm ctl

When to use which