tui-td 0.2.11 → 0.2.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07ef26981840d9171eb2082a6c638c6f43869c05ffdb11c7fff857b058ce87e7
-  data.tar.gz: 47d8dd453c1a393ad2f838b67226f92d50b97d5647fb775e36e95f9e381105e9
+  metadata.gz: 88f553e060b5f2836421a48eadf8aa6b0341974e7081f7e9dd98e024b0665a59
+  data.tar.gz: ddd0b1fd0f0666382b8f8d1fb9cb8b170cef2829299685da4a56d51d4cfc7945
 SHA512:
-  metadata.gz: 94ce617f9370428126bf1b565ca67787a455f6d64cd6273fc69c2cecc83ca293b07272cf3f227787ba4e56ae4bf914447752689115979d1d19863fd5d1e17545
-  data.tar.gz: fdc72eaff712400c026469730cce5fe88daf65b2cca7fa25a071d79a1a2d53b648f5cd80dc8f2b11fe952ce1c9b4aeed9dde5e372715c22d877487d1db25cb52
+  metadata.gz: 5d478553f03b514f380d46c6aff519d3f6aec2f44dcd790ab51a162eca9cba8e73b136f79ebdf72cecaa7f66c9939fcb028edf80c1d904c00efb026ec0b92fa2
+  data.tar.gz: d16aef5de09e4be72370113d5ec06ecebc6a3ec2ceda55837bf61ade4953906ec500513f24d3eef0127a8aa6a2919339660b922615f26c4b01848c496c6ff359

data/CHANGELOG.md

@@ -1,6 +1,52 @@
 # CHANGELOG
 
-# CHANGELOG
+## 0.2.13
+
+### Added
+
+- Auto-wait mechanisms: `Driver#wait_for(predicate)` with adaptive polling (10ms → 100ms),
+  auto-wait on RSpec matchers (3s timeout when given a Driver), auto-wait on JSON test
+  assertions (2s per-check timeout)
+- Semantic selectors: `Element` struct and `Selector` class with heuristic role detection
+  for buttons, checkboxes, dialogs, statusbars, and progress bars
+- RSpec matchers: `have_button`, `have_dialog`, `have_checkbox`, `have_role`
+- JSON test steps: `assert_button`, `assert_dialog`, `assert_checkbox`, `assert_role`
+- `within` scoping for filtering elements by bounding box
+- `poll_interval` parameter on Driver for configurable polling speed
+
+### Changed
+
+- `wait_for_stable` uses buffer-size tracking instead of full grid parse for performance
+- Output buffer capped at 10 MB (ring buffer) to prevent unbounded memory growth
+- Delegate `Selector` and `Element` to tans-parser 0.1.1
+
+### Documentation
+
+- Add CONTRIBUTING.md with development setup, code quality, and PR workflow
+- Add docs/quick_start.md with 2-minute getting-started tutorial
+- Add docs/faq.md covering 8 common troubleshooting topics
+- Add whiptail dialog example (`examples/whiptail_dialog.json`)
+- Update CLI help (`tui-td help test`, `tui-td help rspec`) with new steps and matchers
+
+## 0.2.12
+
+### Security
+
+- Command injection prevention: use Shellwords.shellsplit + array form of PTY.spawn
+- Environment variable sanitization: block dangerous vars (PATH, LD_PRELOAD, etc.)
+- Path traversal prevention: validate output paths for screenshot/HTML
+- ReDoS prevention: add regex timeout in find_text
+
+### Fixed
+
+- ANSI erase operations (ED/EL) now reset all cell attributes (fg, bg, bold, italic,
+  underline), not just the character — colors and styles no longer leak across lines
+
+### Architecture
+
+- Extract ANSIParser, ANSIUtils, and State into standalone tans-parser gem (v0.1.0)
+- Add tans-parser as a runtime dependency (~>0.1)
+- Replace extracted unit tests with forwarder integration smoke tests
 
 ## 0.2.11
 

data/README.md

@@ -1,13 +1,22 @@
 # TUI Test Drive
 
-Testing framework for Terminal User Interfaces (TUIs) with MCP support.
+[![Gem Version](https://badge.fury.io/rb/tui-td.svg)](https://rubygems.org/gems/tui-td)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
-**tui-td** lets you:
-1. Start a TUI application in a virtual terminal (PTY)
-2. See the output — as structured JSON, plain text, PNG screenshots, or HTML renders
-3. Send input — keystrokes, text, control sequences
-4. Analyze output — find text, check colors, detect cursor position
-5. Loop — adjust and retest without manual intervention
+Testing framework for Terminal User Interfaces (TUIs). Start a TUI in a PTY, send input, analyze output — as structured JSON, plain text, PNG screenshots, or HTML renders. Includes an MCP server for AI-driven testing, auto-wait RSpec matchers, and semantic selectors.
+
+> New to tui-td? Jump to [Quick Start](docs/quick_start.md).
+
+**What tui-td gives you:**
+
+1. **Start any TUI** in a virtual terminal (PTY) with `Driver` or JSON test plans
+2. **Auto-wait assertions** — matchers automatically retry until the condition is met or timeout
+3. **Semantic selectors** — `get_by_role(:button)`, `get_by_role(:dialog)`, `within { }` scoping
+4. **Multiple output formats** — structured JSON, plain text, PNG screenshots, HTML renders
+5. **JSON test runner** — language-agnostic, 15+ step types, CI-friendly
+6. **RSpec matchers** — `have_text`, `have_fg`, `have_button`, `have_dialog`, and more
+7. **MCP server** — AI agents can drive TUIs via JSON-RPC over stdio
+8. **Pure Ruby rendering** — embedded Spleen font + 2766 Unifont glyphs, no native deps required
 
 ## Installation
 
@@ -83,6 +92,7 @@ Examples:
 Interactive commands (drive mode):
   state              Show terminal state as pretty JSON
   raw                Show raw ANSI output
+  elements           Show detected UI elements (buttons, dialogs, etc.)
   key <name>         Send keystroke (enter, tab, escape, up, down, left, right,
                      backspace, ctrl_c, ctrl_d)
   <text>             Send text to the TUI
@@ -273,6 +283,10 @@ tui-td test examples/echo_test.json
 | `assert_exit` | `N` | Assert the process exit code equals N |
 | `screenshot` | `"path"` | Save PNG screenshot |
 | `html` | `"path"` | Save HTML render for browser viewing |
+| `assert_button` | `"text"` | Assert a button with given text is visible (`[ OK ]`, `(Cancel)`, `<Submit>`) |
+| `assert_dialog` | — | Assert a dialog (box-drawing region) is visible |
+| `assert_checkbox` | `"label", "checked": true` | Assert a checkbox with given label (and optionally checked state) |
+| `assert_role` | `":button", "text": "OK"` | Generic role assertion (`:button`, `:checkbox`, `:dialog`, `:statusbar`, `:progress`) |
 | `close` | — | Close the TUI |
 
 Example with `html` step for before/after snapshots:
@@ -347,6 +361,10 @@ end
 | `have_fg("color").at(row, col)` | Assert foreground color at position |
 | `have_bg("color").at(row, col)` | Assert background color at position |
 | `have_style.at(row, col).with(bold: true, ...)` | Assert cell style |
+| `have_button("OK")` | Assert a button with given text is visible |
+| `have_dialog` | Assert a dialog (box-drawing region) is visible |
+| `have_checkbox("Label").checked` | Assert a checkbox with given label (chain `.checked`) |
+| `have_role(:button, text: "OK")` | Generic role assertion with optional text filter |
 | `have_exit_status(N)` | Assert the driver process exit status equals N |
 
 ## MCP Server — AI Integration
@@ -373,6 +391,7 @@ tui-td serve
 | `tui_wait_for_exit` | Wait until the TUI process exits. Returns exit status. |
 | `tui_exit_status` | Get the exit status code (nil if still running). |
 | `tui_find_text` | Search for text or regex in terminal state. Returns positions of all matches. |
+| `tui_find_elements` | Detect UI elements (buttons, checkboxes, dialogs, etc.) with optional role/text filters. |
 | `tui_close` | Close the TUI and clean up. |
 
 ### MCP configuration
@@ -419,10 +438,13 @@ Add to your MCP client configuration:
 // 8. Search for text in the terminal
 {"method": "tools/call", "params": {"name": "tui_find_text", "arguments": {"pattern": "error|fail"}}}
 
-// 9. Check exit status (or wait for exit)
+// 9. Find UI elements by role
+{"method": "tools/call", "params": {"name": "tui_find_elements", "arguments": {"role": "button"}}}
+
+// 10. Check exit status (or wait for exit)
 {"method": "tools/call", "params": {"name": "tui_exit_status", "arguments": {}}}
 
-// 10. Clean up
+// 11. Clean up
 {"method": "tools/call", "params": {"name": "tui_close", "arguments": {}}}
 ```