> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Testing > Built-in PTY self-test and control socket for automated verification and scripting. ## 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. ```bash theme={null} 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** ```bash theme={null} $ monoterm test key @ Screen after '@': 0: FILES │... 9: │ ... │ ── Prompt ───────────── 10: │ ... │ Type, / for commands, Ctrl+J: newline 16: │ ... │ Enter:send Ctrl+J:newline Tab:accept Esc:cancel 27: 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. ```text theme={null} $ 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. ```bash theme={null} 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](/ai-clis/monoterm/overview#raw-socket-protocol-11-parsed-messages) before building directly on the socket. **Example: run a command and read output** ```bash theme={null} $ 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 |