tui-td 0.2.12 → 0.2.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98d74d9d7481eabaca77e302ae6e86e1c0467222ebeabb26320fc4668c96af72
-  data.tar.gz: a666b663abf34a08b08c31e57b0348ae00020f304a6296012a027a26fbbb69a9
+  metadata.gz: 81e8cf766200bdb7f86334be97036e68f36df7e352618e823185976ebb07a629
+  data.tar.gz: 1632047e8e7b668d0aee6fcf3b14ff16b01d5c23d4cca1f126315d6fe8c1606b
 SHA512:
-  metadata.gz: 22485763c32cac98cb98f8a2b4f2aaf8656c4955c97a28ff7cfdc3a3c2f82252c0b079c75630bb6d0e1ebd21a5c65d5f042be4c20e566502b6d747b88304a95d
-  data.tar.gz: e3d209ca2706c701efaf6e98af5d46af21ce7f1772aa0fe1a2ddbe9858442380f866883ac5c8948bb66d447843987e7ba7bfb77a6cc2aa08a6363d09deaa0320
+  metadata.gz: a0f08cd1cc35c05466f5f5b77f45f674635d390db8a68bf9a75e316e2cc70f681daf718211a8563b765ccbfe1b7689d38e28378311dc2ad9afa3bf57a946a172
+  data.tar.gz: 5f6385932f9c350c3186dfe44a3c47bc0c169c86189feb90c8a54dc6ddfdb54f0b97489ffe812da557cc2e6828b384b28cd81ca286be977221586c4f0788fe33

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # CHANGELOG
 
+## 0.2.14
+
+### Fixed
+
+- Tighten tans-parser dependency from `~> 0.1` to `~> 0.1.1` to ensure the required
+  Selector/Element classes are present (0.1.0 lacks them)
+
+## 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

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": {}}}
 ```
 

data/lib/tui_td/cli.rb

@@ -40,6 +40,7 @@ module TUITD
         opts.separator "Interactive commands (drive mode):"
         opts.separator "  state              Show terminal state as pretty JSON"
         opts.separator "  raw                Show raw ANSI output"
+        opts.separator "  elements           Show detected UI elements (buttons, dialogs, etc.)"
         opts.separator "  key <name>         Send keystroke (enter, tab, escape, up, down, left, right,"
         opts.separator "                     backspace, ctrl_c, ctrl_d)"
         opts.separator "  <text>             Send text to the TUI"
@@ -195,6 +196,14 @@ module TUITD
           elsif input == "exitstatus"
             status = driver.exitstatus
             puts status ? "Exit status: #{status}" : "Process still running"
+          elsif input == "elements"
+            state = State.new(driver.state_data)
+            selector = Selector.new(state)
+            puts "Buttons:    #{selector.buttons.map { |e| "#{e.text}@[#{e.row},#{e.col}]" }.join(", ")}"
+            puts "Checkboxes: #{selector.checkboxes.map { |e| "#{e.text} (#{e.checked ? "✓" : "☐"})" }.join(", ")}"
+            puts "Dialogs:    #{selector.dialogs.map { |e| "\"#{e.text}\" #{e.width}x#{e.height}" }.join(", ")}"
+            puts "Statusbars: #{selector.statusbars.map(&:text).join(", ")}"
+            puts "Progress:   #{selector.progress_bars.map(&:text).join(", ")}"
           elsif input.start_with?("key ")
             driver.send_keys(input.split(" ", 2).last.to_sym)
           else
@@ -410,6 +419,22 @@ module TUITD
           {"close": true}
               Close the driver session (force-kill if needed).
 
+          {"assert_button": "<text>"}
+              Find a button with the given text. Buttons are detected
+              by patterns like [ OK ], (Cancel), <Submit>.
+
+          {"assert_dialog": true}
+              Assert that at least one dialog (box-drawing region) is visible.
+
+          {"assert_checkbox": "<text>", "checked": true}
+              Find a checkbox with the given label text. Optional "checked"
+              (true/false) to match checked state. Detects [x], [*], [ ] at
+              line starts.
+
+          {"assert_role": ":button", "text": "OK"}
+              Generic role assertion. Accepts :button, :checkbox, :dialog,
+              :statusbar, :progress. Optional "text" filter.
+
         Example test file: examples/echo_test.json
       HELP
       exit 0
@@ -470,6 +495,32 @@ module TUITD
             Assert style attributes at [row, col] match the given hash.
             Usage: expect(state).to have_style.at(0, 0).with(bold: true)
 
+        Selector matchers (semantic UI element detection)
+        -------------------------------------------------
+
+        These matchers detect UI elements by their visual appearance:
+
+        have_button("OK")
+            Passes if a button with the given text is visible.
+            Detects [ OK ], (Cancel), <Submit> patterns.
+            Usage: expect(state).to have_button("OK")
+
+        have_dialog
+            Passes if a dialog (box-drawing character region) is visible.
+            Usage: expect(state).to have_dialog
+
+        have_checkbox("Enable").checked
+            Passes if a checkbox with the given label is visible.
+            Chain .checked to require the box to be checked.
+            Detects [x], [*], [ ] at line starts.
+            Usage: expect(state).to have_checkbox("Enable logging")
+            Usage: expect(state).to have_checkbox("Auto-save").checked
+
+        have_role(:button, text: "OK")
+            Generic role matcher. Accepts :button, :checkbox, :dialog,
+            :statusbar, :progress. Optional text: filter.
+            Usage: expect(state).to have_role(:statusbar)
+
         Driver matchers (work on TUITD::Driver, not State)
         --------------------------------------------------
 

data/lib/tui_td/driver.rb

@@ -26,7 +26,9 @@ module TUITD
 
     attr_reader :command, :state
 
-    def initialize(command, rows: 40, cols: 120, timeout: 30, chdir: nil, env: {})
+    MAX_BUFFER_SIZE = 10 * 1024 * 1024 # 10 MB ring buffer
+
+    def initialize(command, rows: 40, cols: 120, timeout: 30, chdir: nil, env: {}, poll_interval: nil)
       @command = command
       @rows = rows
       @cols = cols
@@ -41,6 +43,7 @@ module TUITD
       @output_mutex = Mutex.new
       @reader_thread = nil
       @reader_running = false
+      @poll_interval = poll_interval
     end
 
     # Start the TUI application in a PTY
@@ -92,9 +95,34 @@ module TUITD
       end
     end
 
+    # Wait until the predicate returns true for the current terminal state.
+    # Polls with adaptive intervals: 10ms → 25ms → 50ms → 100ms.
+    # Use a custom poll_interval to bypass adaptive behavior.
+    #
+    #   driver.wait_for { |state| state.find_text("Ready").any? }
+    #   driver.wait_for(timeout: 5) { |state| state.foreground_at(0, 0) == "green" }
+    #
+    def wait_for(timeout: nil, &predicate)
+      deadline = monotonic + (timeout || @timeout)
+      loop_count = 0
+      loop do
+        raise TimeoutError, "Timeout waiting for predicate" if monotonic > deadline
+
+        read_available!
+        refresh_state!
+        state_obj = State.new(@state)
+        break if predicate.call(state_obj)
+
+        adaptive_sleep(loop_count)
+        loop_count += 1
+      end
+      @state
+    end
+
     # Wait until output contains the given text
     def wait_for_text(text)
       deadline = monotonic + @timeout
+      loop_count = 0
       loop do
         raise TimeoutError, "Timeout waiting for: #{text.inspect}" if monotonic > deadline
 
@@ -102,7 +130,8 @@ module TUITD
         found = @output_mutex.synchronize { @output_buffer.include?(text) }
         break if found
 
-        sleep 0.05
+        adaptive_sleep(loop_count)
+        loop_count += 1
       end
       refresh_state!
     end
@@ -111,28 +140,27 @@ module TUITD
     def wait_for_stable(stable_ms: 300)
       deadline = monotonic + @timeout
       last_change = monotonic
-      last_grid = nil
+      last_buffer_size = @output_mutex.synchronize { @output_buffer.bytesize }
+      loop_count = 0
 
       loop do
         raise TimeoutError, "Timeout waiting for stable output" if monotonic > deadline
 
-        had_data = read_available!
+        read_available!
+        current_buffer_size = @output_mutex.synchronize { @output_buffer.bytesize }
         process_alive = process_alive?
 
-        if had_data
-          current_grid = parse_grid_snapshot
-          if current_grid != last_grid
-            last_grid = current_grid
-            last_change = monotonic
-          end
+        if current_buffer_size != last_buffer_size
+          last_buffer_size = current_buffer_size
+          last_change = monotonic
         elsif !process_alive
-          # Process exited and no more data — final state reached
           break
-        elsif last_grid && (monotonic - last_change) * 1000 >= stable_ms # rubocop:disable Lint/DuplicateBranch
+        elsif (monotonic - last_change) * 1000 >= stable_ms # rubocop:disable Lint/DuplicateBranch
           break
         end
 
-        sleep 0.05
+        adaptive_sleep(loop_count)
+        loop_count += 1
       end
       refresh_state!
     end
@@ -225,6 +253,7 @@ module TUITD
     def _start_reader_thread
       @reader_running = true
       @reader_thread = Thread.new do
+        loop_count = 0
         loop do
           break unless @reader_running
 
@@ -233,7 +262,8 @@ module TUITD
           rescue IOError, Errno::EIO
             break
           end
-          sleep 0.05
+          adaptive_sleep(loop_count)
+          loop_count += 1
         end
       end
     end
@@ -260,12 +290,30 @@ module TUITD
       raise Error, "Process exited (status: #{@wait_thr&.value&.exitstatus})" unless @wait_thr&.alive?
     end
 
+    def adaptive_sleep(loop_count)
+      interval = if @poll_interval
+                   @poll_interval
+                 elsif loop_count < 40   # ~0-2s: 10ms
+                   0.01
+                 elsif loop_count < 160  # ~2-5s: 25ms
+                   0.025
+                 elsif loop_count < 260  # ~5-10s: 50ms
+                   0.05
+                 else # 10s+: 100ms
+                   0.1
+                 end
+      sleep interval
+    end
+
     def read_available!
       return false unless @stdout
 
       data = @stdout.read_nonblock(4096)
 
-      @output_mutex.synchronize { @output_buffer << data }
+      @output_mutex.synchronize do
+        @output_buffer << data
+        @output_buffer = @output_buffer[-MAX_BUFFER_SIZE..] if @output_buffer.bytesize > MAX_BUFFER_SIZE
+      end
 
       respond_to_dsr if data.include?("\e[6n")
 

data/lib/tui_td/matchers.rb

@@ -2,36 +2,57 @@
 
 require "rspec/expectations"
 
-# RSpec matchers for TUITD::State objects.
+# RSpec matchers for TUITD::State and TUITD::Driver objects.
+#
+# When given a State, matchers check immediately.
+# When given a Driver, matchers auto-wait (up to 3 seconds) for the condition.
 #
 # Usage:
 #   require "tui_td/matchers"
 #
+#   # Immediate check on State
 #   state = TUITD::State.new(driver.state_data)
 #   expect(state).to have_text("Welcome")
-#   expect(state).to have_fg("cyan").at(0, 0)
+#
+#   # Auto-wait on Driver
+#   expect(driver).to have_text("Welcome")
 #
 module TUITD
   module Matchers
+    AUTO_WAIT_TIMEOUT = 3
+
+    def self.auto_wait(actual, timeout: AUTO_WAIT_TIMEOUT, &predicate)
+      if actual.respond_to?(:wait_for)
+        begin
+          actual.wait_for(timeout: timeout, &predicate)
+          true
+        rescue TUITD::TimeoutError
+          false
+        end
+      else
+        predicate.call(actual)
+      end
+    end
+
     RSpec::Matchers.define :have_text do |expected|
-      match do |state|
-        state.find_text(expected).any?
+      match do |actual|
+        Matchers.auto_wait(actual) { |s| s.find_text(expected).any? }
       end
 
       description { "have text #{expected.inspect}" }
-      failure_message { |_state| "expected terminal to contain #{expected.inspect}" }
-      failure_message_when_negated { |_state| "expected terminal NOT to contain #{expected.inspect}" }
+      failure_message { |_actual| "expected terminal to contain #{expected.inspect}" }
+      failure_message_when_negated { |_actual| "expected terminal NOT to contain #{expected.inspect}" }
     end
 
     RSpec::Matchers.define :have_regex do |pattern|
-      match do |state|
+      match do |actual|
         @regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
-        state.find_text(@regex).any?
+        Matchers.auto_wait(actual) { |s| s.find_text(@regex).any? }
       end
 
       description { "match regex #{pattern.inspect}" }
-      failure_message { |_state| "expected terminal to match #{pattern.inspect}" }
-      failure_message_when_negated { |_state| "expected terminal NOT to match #{pattern.inspect}" }
+      failure_message { |_actual| "expected terminal to match #{pattern.inspect}" }
+      failure_message_when_negated { |_actual| "expected terminal NOT to match #{pattern.inspect}" }
     end
 
     RSpec::Matchers.define :have_fg do |expected|
@@ -40,13 +61,15 @@ module TUITD
         @col = col
       end
 
-      match do |state|
-        @actual = state.foreground_at(@row, @col)
-        @actual == expected
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          @actual = s.foreground_at(@row, @col)
+          @actual == expected
+        end
       end
 
       description { "have foreground #{expected.inspect} at [#{@row},#{@col}]" }
-      failure_message do |_state|
+      failure_message do |_actual|
         "expected FG at [#{@row},#{@col}] to be #{expected.inspect}, but was #{@actual.inspect}"
       end
     end
@@ -57,13 +80,15 @@ module TUITD
         @col = col
       end
 
-      match do |state|
-        @actual = state.background_at(@row, @col)
-        @actual == expected
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          @actual = s.background_at(@row, @col)
+          @actual == expected
+        end
       end
 
       description { "have background #{expected.inspect} at [#{@row},#{@col}]" }
-      failure_message do |_state|
+      failure_message do |_actual|
         "expected BG at [#{@row},#{@col}] to be #{expected.inspect}, but was #{@actual.inspect}"
       end
     end
@@ -75,17 +100,19 @@ module TUITD
       end
       chain(:with) { |expected| @expected = expected }
 
-      match do |state|
-        @actual = state.style_at(@row, @col)
-        @expected ||= {}
-        @expected.all? { |k, v| @actual[k] == v }
+      match do |actual|
+        @expected_style = @expected || {}
+        Matchers.auto_wait(actual) do |s|
+          @actual = s.style_at(@row, @col)
+          @expected_style.all? { |k, v| @actual[k] == v }
+        end
       end
 
       description do
-        "have style #{@expected.inspect} at [#{@row},#{@col}]"
+        "have style #{@expected_style.inspect} at [#{@row},#{@col}]"
       end
-      failure_message do |_state|
-        "expected style at [#{@row},#{@col}] to be #{@expected.inspect}, but was #{@actual.inspect}"
+      failure_message do |_actual|
+        "expected style at [#{@row},#{@col}] to be #{@expected_style.inspect}, but was #{@actual.inspect}"
       end
     end
 
@@ -104,5 +131,84 @@ module TUITD
         "expected exit status not to be #{expected}"
       end
     end
+
+    # Selector-based matchers — work with both State and Driver (auto-wait)
+
+    RSpec::Matchers.define :have_button do |expected|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          Selector.new(s).get_by_text(expected).any? { |e| e.role == :button }
+        end
+      end
+
+      description { "have button #{expected.inspect}" }
+      failure_message { |_actual| "expected terminal to have a button #{expected.inspect}" }
+      failure_message_when_negated { |_actual| "expected terminal NOT to have a button #{expected.inspect}" }
+    end
+
+    RSpec::Matchers.define :have_dialog do
+      match do |actual|
+        Matchers.auto_wait(actual) { |s| Selector.new(s).dialogs.any? }
+      end
+
+      description { "have a dialog" }
+      failure_message { |_actual| "expected terminal to have a dialog" }
+      failure_message_when_negated { |_actual| "expected terminal NOT to have a dialog" }
+    end
+
+    RSpec::Matchers.define :have_checkbox do |expected|
+      chain(:checked) { @checked = true }
+
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          checkboxes = Selector.new(s).checkboxes
+          found = checkboxes.select { |e| e.text&.include?(expected) }
+          found = found.select(&:checked) if @checked
+          found.any?
+        end
+      end
+
+      description do
+        desc = "have checkbox #{expected.inspect}"
+        desc += " (checked)" if @checked
+        desc
+      end
+      failure_message do |_actual|
+        desc = "expected terminal to have checkbox #{expected.inspect}"
+        desc += " (checked)" if @checked
+        desc
+      end
+      failure_message_when_negated do |_actual|
+        desc = "expected terminal NOT to have checkbox #{expected.inspect}"
+        desc += " (checked)" if @checked
+        desc
+      end
+    end
+
+    RSpec::Matchers.define :have_role do |role, text: nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          elements = Selector.new(s).get_by_role(role)
+          elements = elements.select { |e| e.text&.include?(text) } if text
+          elements.any?
+        end
+      end
+
+      description do
+        desc = "have role :#{role}"
+        desc += " with text #{text.inspect}" if text
+        desc
+      end
+      failure_message do |_actual|
+        desc = "expected terminal to have a :#{role}"
+        desc += " with text #{text.inspect}" if text
+        desc
+      end
+      failure_message_when_negated do |_actual|
+        desc = "expected terminal NOT to have a :#{role}"
+        desc += " with text #{text.inspect}" if text
+        desc
+      end
+    end
   end
 end

data/lib/tui_td/mcp/server.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Layout/LineLength
+# rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/LineLength
 
 require "json"
 
@@ -284,6 +284,23 @@ module TUITD
                   required: ["pattern"],
                 },
               },
+              {
+                name: "tui_find_elements",
+                description: "Search for UI elements in the terminal state. Returns buttons, checkboxes, dialogs, statusbars, and progress bars detected by heuristic analysis. Optionally filter by role and/or text.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      description: "Filter by role: button, checkbox, dialog, statusbar, progress. Omit to return all.",
+                    },
+                    text: {
+                      type: "string",
+                      description: "Filter by visible text (partial match). Optional.",
+                    },
+                  },
+                },
+              },
               {
                 name: "tui_close",
                 description: "Close the TUI application and clean up the PTY session. Call this when finished.",
@@ -315,7 +332,8 @@ module TUITD
                  when "tui_wait_for_exit" then call_tui_wait_for_exit
                  when "tui_exit_status" then call_tui_exit_status
                  when "tui_find_text" then call_tui_find_text(args)
-                 when "tui_close"     then call_tui_close
+                 when "tui_find_elements" then call_tui_find_elements(args)
+                 when "tui_close" then call_tui_close
                  else
                    return error_response(id, -32_602, "Unknown tool: #{tool_name}")
                  end
@@ -488,6 +506,39 @@ module TUITD
         end
       end
 
+      def call_tui_find_elements(args)
+        ensure_driver!
+        state = TUITD::State.new(@driver.state_data)
+        selector = TUITD::Selector.new(state)
+
+        role = args["role"]&.to_sym
+        text = args["text"]
+
+        elements = if role
+                     selector.get_by_role(role)
+                   else
+                     selector.elements
+                   end
+        elements = elements.select { |e| e.text&.include?(text) } if text
+
+        if elements.empty?
+          desc = role ? "role :#{role}" : "any role"
+          desc += " with text #{text.inspect}" if text
+          "No elements found for #{desc}"
+        else
+          lines = ["Found #{elements.size} element(s):"]
+          elements.each do |el|
+            parts = ["  :#{el.role}"]
+            parts << el.text.inspect if el.text
+            parts << "at [#{el.row},#{el.col}]"
+            parts << "#{el.width}x#{el.height}"
+            parts << "(checked)" if el.checked
+            lines << parts.join(" ")
+          end
+          lines.join("\n")
+        end
+      end
+
       def call_tui_close
         @driver&.close
         @driver = nil
@@ -544,4 +595,4 @@ module TUITD
     end
   end
 end
-# rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Layout/LineLength
+# rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Layout/LineLength

data/lib/tui_td/selector.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "tans-parser"
+
+module TUITD
+  Selector = TansParser::Selector
+  Element = TansParser::Element
+
+  # Extend the aliased Selector with within scoping.
+  # within is a testing-specific pattern (scope queries to a dialog region)
+  # and therefore lives in tui-td rather than tans-parser.
+  Selector.class_eval do
+    # Return a new Selector whose elements are filtered to the given bounding box.
+    # Coordinates of returned elements are relative to the box origin.
+    def within(top_row, left_col, width, height)
+      scoped = @elements.select do |e|
+        e.row >= top_row && e.row < top_row + height &&
+          e.col >= left_col && e.col < left_col + width
+      end
+      scoped.each do |e|
+        e = e.dup
+        e.row -= top_row
+        e.col -= left_col
+      end
+      self.class.allocate.tap do |s|
+        s.instance_variable_set(:@state, @state)
+        s.instance_variable_set(:@elements, scoped)
+      end
+    end
+  end
+end

data/lib/tui_td/test_runner.rb

@@ -109,18 +109,30 @@ module TUITD
                 when "assert_style"
                   ensure_driver!(driver)
                   row, col = coords(step)
-                  state = State.new(driver.state_data)
-                  actual = state.style_at(row, col)
-                  expected = {}
-                  expected[:bold] = step[:bold] unless step[:bold].nil?
-                  expected[:italic] = step[:italic] unless step[:italic].nil?
-                  expected[:underline] = step[:underline] unless step[:underline].nil?
-                  match = expected.all? { |k, v| actual[k] == v }
+                  expected_style = {}
+                  expected_style[:bold] = step[:bold] unless step[:bold].nil?
+                  expected_style[:italic] = step[:italic] unless step[:italic].nil?
+                  expected_style[:underline] = step[:underline] unless step[:underline].nil?
+                  actual = nil
+                  match = begin
+                    driver.wait_for(timeout: 2) do |s|
+                      actual = s.style_at(row, col)
+                      expected_style.all? { |k, v| actual[k] == v }
+                    end
+                    true
+                  rescue TimeoutError
+                    false
+                  end
+                  actual ||= begin
+                    state = State.new(driver.state_data)
+                    state.style_at(row, col)
+                  end
                   if match
-                    Result.new(step: action, passed: true, message: "Style at [#{row},#{col}] matches #{expected}")
+                    Result.new(step: action, passed: true,
+                               message: "Style at [#{row},#{col}] matches #{expected_style}",)
                   else
                     Result.new(step: action, passed: false,
-                               message: "Style at [#{row},#{col}] is #{actual}, expected #{expected}",)
+                               message: "Style at [#{row},#{col}] is #{actual}, expected #{expected_style}",)
                   end
 
                 when "screenshot"
@@ -151,6 +163,19 @@ module TUITD
                     Result.new(step: action, passed: false, message: "Exit status #{actual}, expected #{expected}")
                   end
 
+                when "assert_button"
+                  check_role(driver, :button, value.to_s)
+
+                when "assert_dialog"
+                  check_role(driver, :dialog, nil)
+
+                when "assert_checkbox"
+                  check_role(driver, :checkbox, value.to_s, checked: step[:checked])
+
+                when "assert_role"
+                  role = step[:role]&.to_sym
+                  check_role(driver, role, value.to_s)
+
                 when "close"
                   driver&.close
                   driver = nil
@@ -199,6 +224,25 @@ module TUITD
 
     private
 
+    def check_role(driver, role, text, checked: nil)
+      ensure_driver!(driver)
+      state = State.new(driver.state_data)
+      selector = Selector.new(state)
+      elements = selector.get_by_role(role)
+      elements = elements.select { |e| e.text&.include?(text.to_s) } if text
+      elements = elements.select { |e| e.checked == checked } unless checked.nil?
+
+      action = "assert_#{role}"
+      if elements.any?
+        count = elements.size
+        desc = text ? "#{role} #{text.inspect}" : role.to_s
+        Result.new(step: action, passed: true, message: "Found #{count} #{desc} element(s)")
+      else
+        desc = text ? "#{role} with text #{text.inspect}" : role.to_s
+        Result.new(step: action, passed: false, message: "No #{desc} found")
+      end
+    end
+
     def safe_output_path(value, ext)
       default = File.join("/tmp", "tui_td_#{Time.now.to_i}.#{ext}")
       resolved = File.expand_path(value.is_a?(String) ? value : default)
@@ -223,7 +267,6 @@ module TUITD
 
     def check_text(driver, value, action)
       ensure_driver!(driver)
-      state = State.new(driver.state_data)
       text = value.to_s
 
       if action == "assert_regex"
@@ -236,7 +279,17 @@ module TUITD
         pattern = text
       end
 
-      found = state.find_text(pattern).any?
+      found = if action == "assert_not_text"
+                state = State.new(driver.state_data)
+                state.find_text(pattern).any?
+              else
+                begin
+                  driver.wait_for(timeout: 2) { |s| s.find_text(pattern).any? }
+                  true
+                rescue TimeoutError
+                  false
+                end
+              end
 
       case action
       when "assert_text"
@@ -266,15 +319,30 @@ module TUITD
       ensure_driver!(driver)
       row, col = coords(step)
       expected = step[:is] || step["is"]
-      state = State.new(driver.state_data)
       label = property == :fg ? "FG" : "BG"
-      actual = property == :fg ? state.foreground_at(row, col) : state.background_at(row, col)
 
-      if actual == expected
+      actual_val = nil
+      found = begin
+        driver.wait_for(timeout: 2) do |s|
+          actual_val = property == :fg ? s.foreground_at(row, col) : s.background_at(row, col)
+          actual_val == expected
+        end
+        true
+      rescue TimeoutError
+        # actual_val holds the last observed value
+        false
+      end
+
+      actual_val ||= begin
+        state = State.new(driver.state_data)
+        property == :fg ? state.foreground_at(row, col) : state.background_at(row, col)
+      end
+
+      if found
         Result.new(step: step.keys.first.to_s, passed: true, message: "#{label} at [#{row},#{col}] is #{expected}")
       else
         Result.new(step: step.keys.first.to_s, passed: false,
-                   message: "#{label} at [#{row},#{col}] is #{actual}, expected #{expected}",)
+                   message: "#{label} at [#{row},#{col}] is #{actual_val}, expected #{expected}",)
       end
     end
   end

data/lib/tui_td/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TUITD
-  VERSION = "0.2.12"
+  VERSION = "0.2.14"
 end

data/lib/tui_td.rb

@@ -16,6 +16,7 @@ require_relative "tui_td/state"
 require_relative "tui_td/screenshot"
 require_relative "tui_td/html_renderer"
 require_relative "tui_td/test_runner"
+require_relative "tui_td/selector"
 require_relative "tui_td/mcp/server"
 require_relative "tui_td/cli"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.2.14
 platform: ruby
 authors:
 - Haluk Durmus
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -173,6 +173,7 @@ files:
 - lib/tui_td/matchers.rb
 - lib/tui_td/mcp/server.rb
 - lib/tui_td/screenshot.rb
+- lib/tui_td/selector.rb
 - lib/tui_td/state.rb
 - lib/tui_td/test_runner.rb
 - lib/tui_td/unifont_glyphs.rb