tui-td 0.2.11 → 0.2.13

data/lib/tui_td/ansi_utils.rb

@@ -1,77 +1,7 @@
 # frozen_string_literal: true
 
-module TUITD
-  # Shared ANSI color constants and helpers.
-  # Used by Screenshot, HtmlRenderer, and other color-aware renderers.
-  module ANSIUtils
-    ANSI_RGB = {
-      "black" => [0x00, 0x00, 0x00],
-      "red" => [0xAA, 0x00, 0x00],
-      "green" => [0x00, 0xAA, 0x00],
-      "yellow" => [0xAA, 0x55, 0x00],
-      "blue" => [0x00, 0x00, 0xAA],
-      "magenta" => [0xAA, 0x00, 0xAA],
-      "cyan" => [0x00, 0xAA, 0xAA],
-      "white" => [0xAA, 0xAA, 0xAA],
-      "bright_black" => [0x55, 0x55, 0x55],
-      "bright_red" => [0xFF, 0x55, 0x55],
-      "bright_green" => [0x55, 0xFF, 0x55],
-      "bright_yellow" => [0xFF, 0xFF, 0x55],
-      "bright_blue" => [0x55, 0x55, 0xFF],
-      "bright_magenta" => [0xFF, 0x55, 0xFF],
-      "bright_cyan" => [0x55, 0xFF, 0xFF],
-      "bright_white" => [0xFF, 0xFF, 0xFF],
-    }.freeze
-
-    CUBE = [0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF].freeze
-
-    ANSI_INDEX = %w[
-      black red green yellow blue magenta cyan white
-      bright_black bright_red bright_green bright_yellow
-      bright_blue bright_magenta bright_cyan bright_white
-    ].freeze
-
-    DEFAULT_FG = [0xC0, 0xC0, 0xC0].freeze
-    DEFAULT_BG = [0x00, 0x00, 0x00].freeze
+require "tans-parser"
 
-    def resolve_color(name, fallback)
-      case name
-      when "default"
-        fallback
-      when /^#([0-9a-fA-F]{6})$/
-        [::Regexp.last_match(1)[0..1].to_i(16), ::Regexp.last_match(1)[2..3].to_i(16),
-         ::Regexp.last_match(1)[4..5].to_i(16),]
-      when /\Acolor(\d+)\z/
-        xterm_256(::Regexp.last_match(1).to_i)
-      when /\Abright_(.+)\z/
-        ANSI_RGB[name] || fallback
-      else # rubocop:disable Lint/DuplicateBranch
-        ANSI_RGB[name] || fallback
-      end
-    end
-
-    def xterm_256(index) # rubocop:disable Naming/VariableNumber
-      if index < 16
-        name = ANSI_INDEX[index]
-        ANSI_RGB[name] || DEFAULT_FG
-      elsif index < 232
-        r = CUBE[((index - 16) / 36) % 6]
-        g = CUBE[((index - 16) / 6) % 6]
-        b = CUBE[(index - 16) % 6]
-        [r, g, b]
-      else
-        v = 8 + ((index - 232) * 10)
-        [v, v, v]
-      end
-    end
-
-    def _dig(hash, *keys)
-      keys.each do |k|
-        return nil unless hash
-
-        hash = hash[k] || hash[k.to_s]
-      end
-      hash
-    end
-  end
+module TUITD
+  ANSIUtils = TansParser::ANSIUtils
 end

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

@@ -6,6 +6,7 @@
 require "pty"
 require "io/console"
 require "json"
+require "shellwords"
 
 module TUITD
   # Drives a TUI application in a pseudo-terminal (PTY).
@@ -20,15 +21,20 @@ module TUITD
   #   driver.close
   #
   class Driver
+    FORBIDDEN_ENV = %w[PATH LD_PRELOAD LD_LIBRARY_PATH DYLD_INSERT_LIBRARIES
+                       DYLD_FRAMEWORK_PATH RUBYOPT HOME RUBYLIB GEM_HOME GEM_PATH].freeze
+
     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
       @timeout = timeout
       @chdir = chdir
-      @env = env
+      @env = sanitize_env(env)
       @state = nil
       @stdin = nil
       @stdout = nil
@@ -37,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
@@ -46,7 +53,8 @@ module TUITD
       spawn_opts = {}
       spawn_opts[:chdir] = @chdir if @chdir
 
-      @stdout, @stdin, @pid = PTY.spawn(env, @command, spawn_opts)
+      cmd_args = Shellwords.shellsplit(@command)
+      @stdout, @stdin, @pid = PTY.spawn(env, *cmd_args, spawn_opts)
       @stdout.winsize = [@rows, @cols] # Set PTY window size for TUIs that check winsize
       @wait_thr = Process.detach(@pid)
 
@@ -87,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
 
@@ -97,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
@@ -106,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
@@ -220,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
 
@@ -228,7 +262,8 @@ module TUITD
           rescue IOError, Errno::EIO
             break
           end
-          sleep 0.05
+          adaptive_sleep(loop_count)
+          loop_count += 1
         end
       end
     end
@@ -246,17 +281,39 @@ module TUITD
       @reader_thread = nil
     end
 
+    def sanitize_env(env)
+      env.reject { |k, _| FORBIDDEN_ENV.include?(k.to_s.upcase) }
+    end
+
     def ensure_running!
       raise Error, "Driver not started. Call #start first." if @stdin.nil?
       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