tui-td 0.2.14 → 0.2.19

data/lib/tui_td/matchers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/ModuleLength, Metrics/BlockLength, Metrics/ParameterLists, Layout/LineLength
+
 require "rspec/expectations"
 
 # RSpec matchers for TUITD::State and TUITD::Driver objects.
@@ -137,7 +139,7 @@ module TUITD
     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 }
+          Selector.new(s).button(text: expected)
         end
       end
 
@@ -158,50 +160,59 @@ module TUITD
 
     RSpec::Matchers.define :have_checkbox do |expected|
       chain(:checked) { @checked = true }
+      chain(:unchecked) { @checked = false }
 
       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?
+          filters = { text: expected }
+          filters[:checked] = @checked unless @checked.nil?
+          Selector.new(s).checkbox(**filters)
         end
       end
 
       description do
         desc = "have checkbox #{expected.inspect}"
-        desc += " (checked)" if @checked
+        desc += " (checked)" if @checked == true
+        desc += " (unchecked)" if @checked == false
         desc
       end
       failure_message do |_actual|
         desc = "expected terminal to have checkbox #{expected.inspect}"
-        desc += " (checked)" if @checked
+        desc += " (checked)" if @checked == true
+        desc += " (unchecked)" if @checked == false
         desc
       end
       failure_message_when_negated do |_actual|
         desc = "expected terminal NOT to have checkbox #{expected.inspect}"
-        desc += " (checked)" if @checked
+        desc += " (checked)" if @checked == true
+        desc += " (unchecked)" if @checked == false
         desc
       end
     end
 
-    RSpec::Matchers.define :have_role do |role, text: nil|
+    RSpec::Matchers.define :have_role do |role, text: nil, checked: nil, disabled: 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?
+          filters = {}
+          filters[:text] = text if text
+          filters[:checked] = checked unless checked.nil?
+          filters[:disabled] = disabled unless disabled.nil?
+          Selector.new(s).get_by_role(role, **filters).any?
         end
       end
 
       description do
         desc = "have role :#{role}"
         desc += " with text #{text.inspect}" if text
+        desc += " (checked)" if checked == true
+        desc += " (disabled)" if disabled == true
         desc
       end
       failure_message do |_actual|
         desc = "expected terminal to have a :#{role}"
         desc += " with text #{text.inspect}" if text
+        desc += " (checked)" if checked == true
+        desc += " (disabled)" if disabled == true
         desc
       end
       failure_message_when_negated do |_actual|
@@ -210,5 +221,240 @@ module TUITD
         desc
       end
     end
+
+    # New role matchers (tans-parser 0.1.2)
+
+    RSpec::Matchers.define :have_input do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).input(text: expected)
+          else
+            Selector.new(s).inputs.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have input #{expected.inspect}" : "have an input field"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have an input #{expected.inspect}" : "expected terminal to have an input field"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have an input #{expected.inspect}" : "expected terminal NOT to have an input field"
+      end
+    end
+
+    RSpec::Matchers.define :have_label do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).label(text: expected)
+          else
+            Selector.new(s).labels.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have label #{expected.inspect}" : "have a label"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a label #{expected.inspect}" : "expected terminal to have a label"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a label #{expected.inspect}" : "expected terminal NOT to have a label"
+      end
+    end
+
+    RSpec::Matchers.define :have_menu do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).menu(text: expected)
+          else
+            Selector.new(s).menus.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have menu #{expected.inspect}" : "have a menu"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a menu #{expected.inspect}" : "expected terminal to have a menu"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a menu #{expected.inspect}" : "expected terminal NOT to have a menu"
+      end
+    end
+
+    RSpec::Matchers.define :have_tab do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).tab(text: expected)
+          else
+            Selector.new(s).tabs.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have tab #{expected.inspect}" : "have a tab"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a tab #{expected.inspect}" : "expected terminal to have a tab"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a tab #{expected.inspect}" : "expected terminal NOT to have a tab"
+      end
+    end
+
+    RSpec::Matchers.define :have_statusbar do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).statusbar(text: expected)
+          else
+            Selector.new(s).statusbars.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have status bar #{expected.inspect}" : "have a status bar"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a status bar #{expected.inspect}" : "expected terminal to have a status bar"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a status bar #{expected.inspect}" : "expected terminal NOT to have a status bar"
+      end
+    end
+
+    RSpec::Matchers.define :have_progress_bar do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).progress_bar(text: expected)
+          else
+            Selector.new(s).progress_bars.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have progress bar #{expected.inspect}" : "have a progress bar"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a progress bar #{expected.inspect}" : "expected terminal to have a progress bar"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a progress bar #{expected.inspect}" : "expected terminal NOT to have a progress bar"
+      end
+    end
+
+    # Snapshot comparison matcher — works with both State and Driver (auto-wait).
+    # Snapshot comparison matcher — supports both named (disk-based) and
+    # legacy in-memory State objects.
+    #
+    # Named snapshots (recommended):
+    #   expect(driver).to match_snapshot("login_screen")
+    #   expect(driver).to match_snapshot("login", type: :all, wait: true)
+    #
+    # First run creates the snapshot, subsequent runs compare.
+    # UPDATE_SNAPSHOTS=1 overwrites all snapshots.
+    #
+    # Legacy (backward compatible):
+    #   pre = driver.snapshot
+    #   expect(driver).to match_snapshot(pre, chars_only: true)
+    #
+    RSpec::Matchers.define :match_snapshot do |ref, type: nil, wait: false, chars_only: nil, ignore_rows: nil, region: nil|
+      match do |actual|
+        # Normalize type: backward compat for chars_only parameter
+        effective_type = type
+        if effective_type.nil? && !chars_only.nil?
+          effective_type = chars_only ? :text : :full
+        end
+        effective_type ||= :text
+
+        @snapshot_name = nil
+        @diff_result = nil
+
+        # Legacy path: snapshot_ref is a State object (responds to diff)
+        if ref.respond_to?(:diff)
+          Matchers.auto_wait(actual) do |s|
+            chars = effective_type == :text
+            diffs = ref.diff(s, chars_only: chars)
+            diffs.select! { |d| Array(region).include?(d[:row]) } if region
+            diffs.reject! { |d| Array(ignore_rows).include?(d[:row]) } if ignore_rows
+            @diff_result = diffs
+            @diff_result.empty?
+          end
+        else
+          # Named snapshot path
+          @snapshot_name = ref.to_s
+          snap = Snapshot.new(@snapshot_name, type: effective_type)
+
+          # Get state_data from actual
+          if wait && actual.respond_to?(:wait_for_stable)
+            begin
+              actual.wait_for_stable
+            rescue StandardError
+              nil
+            end
+          end
+          state_data = if actual.respond_to?(:state_data)
+                         actual.state_data
+                       elsif actual.respond_to?(:to_h)
+                         actual.to_h
+                       else
+                         actual
+                       end
+
+          if TUITD.configuration.update_snapshots?
+            snap.save(state_data)
+            true
+          elsif !snap.exists?
+            snap.save(state_data)
+            @diff_result = TUITD::Snapshot::ComparisonResult.new(passed: true, diff_count: 0, type: effective_type,
+                                                                 message: "Snapshot '#{@snapshot_name}' created (#{effective_type})",)
+            true
+          else
+            @diff_result = snap.compare(state_data, ignore_rows: ignore_rows, region: region)
+            @diff_result.passed?
+          end
+        end
+      end
+
+      description do
+        if @snapshot_name
+          "match snapshot #{@snapshot_name.inspect} (type: #{effective_type})"
+        else
+          desc = "match snapshot"
+          desc << " (chars only)" if effective_type == :text
+          desc
+        end
+      end
+
+      failure_message do |_actual|
+        if @snapshot_name
+          "Snapshot #{@snapshot_name.inspect} does not match.\n#{@diff_result&.message}"
+        else
+          "expected terminal to match snapshot"
+        end
+      end
+
+      failure_message_when_negated do |_actual|
+        if @snapshot_name
+          "expected snapshot #{@snapshot_name.inspect} NOT to match, but it did."
+        else
+          "expected terminal NOT to match snapshot, but it did."
+        end
+      end
+    end
   end
 end
+# rubocop:enable Metrics/ModuleLength, Metrics/BlockLength, Metrics/ParameterLists, Layout/LineLength

data/lib/tui_td/mcp/server.rb

@@ -272,7 +272,7 @@ module TUITD
               },
               {
                 name: "tui_find_text",
-                description: "Search for text or regex pattern in the current terminal state. Returns positions of all matches with surrounding context.",
+                description: "Search for text or regex pattern in the current terminal state. Returns positions of all matches with surrounding context. Supports match modes: partial (default, substring), exact (whole row), regex (Ruby regex).",
                 inputSchema: {
                   type: "object",
                   properties: {
@@ -280,25 +280,148 @@ module TUITD
                       type: "string",
                       description: "Text or regex pattern to search for (e.g., 'error', 'ERROR|FAIL')",
                     },
+                    match: {
+                      type: "string",
+                      enum: %w[partial exact regex],
+                      description: "Match mode: partial (substring), exact (whole row match), regex (Ruby regex). Default: partial.",
+                    },
                   },
                   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.",
+                description: "Search for UI elements in the terminal state. Returns buttons, checkboxes, dialogs, statusbars, progress bars, inputs, labels, menus, and tabs detected by heuristic analysis. Optionally filter by role, text, checked, and/or disabled state.",
                 inputSchema: {
                   type: "object",
                   properties: {
                     role: {
                       type: "string",
-                      description: "Filter by role: button, checkbox, dialog, statusbar, progress. Omit to return all.",
+                      description: "Filter by role: button, checkbox, dialog, statusbar, progress, input, label, menu, tab. Omit to return all.",
                     },
                     text: {
                       type: "string",
                       description: "Filter by visible text (partial match). Optional.",
                     },
+                    checked: {
+                      type: "boolean",
+                      description: "Filter by checked state (checkboxes). Optional.",
+                    },
+                    disabled: {
+                      type: "boolean",
+                      description: "Filter by disabled state. Optional.",
+                    },
+                  },
+                },
+              },
+              {
+                name: "tui_element_actions",
+                description: "Get action hashes for a detected UI element. Returns click/type/press_key actions that can be used to interact with the element via tui_send/tui_send_key.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      description: "Element role: button, checkbox, dialog, statusbar, progress, input, label, menu, tab",
+                    },
+                    text: {
+                      type: "string",
+                      description: "Filter by visible text (partial match). Optional.",
+                    },
+                  },
+                  required: ["role"],
+                },
+              },
+              {
+                name: "tui_diff",
+                description: "Compare the current terminal state against a previous state. Returns cell-level differences. Use chars_only: true to ignore color/style changes.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    snapshot: {
+                      type: "object",
+                      description: "A previously saved state snapshot (from tui_state or a prior capture). Must include size, cursor, and rows keys.",
+                    },
+                    chars_only: {
+                      type: "boolean",
+                      description: "If true, only compare character differences (ignore color/style). Default: false.",
+                    },
+                  },
+                  required: ["snapshot"],
+                },
+              },
+              {
+                name: "tui_annotate_element",
+                description: "Manually register a UI element at a specific region. The annotation is picked up by tui_find_elements for subsequent queries.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    role: {
+                      type: "string",
+                      description: "Element role (e.g., button, dialog, statusbar, progress, input, label, menu, tab).",
+                    },
+                    row: {
+                      type: "integer",
+                      description: "Top row of the element.",
+                    },
+                    col: {
+                      type: "integer",
+                      description: "Left column of the element.",
+                    },
+                    width: {
+                      type: "integer",
+                      description: "Width in columns (default: 1).",
+                      default: 1,
+                    },
+                    height: {
+                      type: "integer",
+                      description: "Height in rows (default: 1).",
+                      default: 1,
+                    },
+                    text: {
+                      type: "string",
+                      description: "Visible text label for the element.",
+                    },
+                  },
+                  required: %w[role row col],
+                },
+              },
+              {
+                name: "tui_save_snapshot",
+                description: "Save the current terminal state as a named snapshot to disk. Used to create golden masters for snapshot testing.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Snapshot name (e.g., 'login_screen'). Saved as <name>.json in the snapshot directory.",
+                    },
+                    type: {
+                      type: "string",
+                      enum: %w[text full png html all],
+                      description: "Snapshot type. text=chars_only (default), full=chars+colors, png=screenshot, html=render, all=all formats.",
+                    },
                   },
+                  required: ["name"],
+                },
+              },
+              {
+                name: "tui_assert_snapshot",
+                description: "Assert the current terminal state matches a named snapshot on disk. On first run, creates the snapshot automatically. Set UPDATE_SNAPSHOTS=1 to force update all snapshots.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Snapshot name to compare against.",
+                    },
+                    type: {
+                      type: "string",
+                      enum: %w[text full png html all],
+                      description: "Snapshot type. Default: text.",
+                    },
+                  },
+                  required: ["name"],
                 },
               },
               {
@@ -333,6 +456,11 @@ module TUITD
                  when "tui_exit_status" then call_tui_exit_status
                  when "tui_find_text" then call_tui_find_text(args)
                  when "tui_find_elements" then call_tui_find_elements(args)
+                 when "tui_element_actions" then call_tui_element_actions(args)
+                 when "tui_diff" then call_tui_diff(args)
+                 when "tui_annotate_element" then call_tui_annotate_element(args)
+                 when "tui_save_snapshot" then call_tui_save_snapshot(args)
+                 when "tui_assert_snapshot" then call_tui_assert_snapshot(args)
                  when "tui_close" then call_tui_close
                  else
                    return error_response(id, -32_602, "Unknown tool: #{tool_name}")
@@ -492,8 +620,9 @@ module TUITD
       def call_tui_find_text(args)
         ensure_driver!
         pattern = args["pattern"] or return "ERROR: 'pattern' argument is required"
+        match_mode = (args["match"] || "partial").to_sym
         state = TUITD::State.new(@driver.state_data)
-        matches = state.find_text(pattern)
+        matches = state.find_text(pattern, match: match_mode)
 
         if matches.empty?
           "No matches found for: #{pattern}"
@@ -513,17 +642,29 @@ module TUITD
 
         role = args["role"]&.to_sym
         text = args["text"]
+        checked = args.key?("checked") ? args["checked"] : nil
+        disabled = args.key?("disabled") ? args["disabled"] : nil
+
+        filters = {}
+        filters[:text] = text if text
+        filters[:checked] = checked unless checked.nil?
+        filters[:disabled] = disabled unless disabled.nil?
 
         elements = if role
-                     selector.get_by_role(role)
+                     selector.get_by_role(role, **filters)
                    else
-                     selector.elements
+                     result = selector.elements
+                     result = result.select { |e| e.text&.include?(text) } if text
+                     result = result.select { |e| e.checked == checked } unless checked.nil?
+                     result = result.select { |e| e.disabled == disabled } unless disabled.nil?
+                     result
                    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
+          desc += " checked=#{checked}" unless checked.nil?
+          desc += " disabled=#{disabled}" unless disabled.nil?
           "No elements found for #{desc}"
         else
           lines = ["Found #{elements.size} element(s):"]
@@ -533,12 +674,115 @@ module TUITD
             parts << "at [#{el.row},#{el.col}]"
             parts << "#{el.width}x#{el.height}"
             parts << "(checked)" if el.checked
+            parts << "(disabled)" if el.disabled
+            parts << "(focused)" if el.focused
             lines << parts.join(" ")
           end
           lines.join("\n")
         end
       end
 
+      def call_tui_element_actions(args)
+        ensure_driver!
+        role = args["role"]&.to_sym || (return "ERROR: 'role' argument is required")
+        text = args["text"]
+
+        state = TUITD::State.new(@driver.state_data)
+        selector = TUITD::Selector.new(state)
+
+        filters = {}
+        filters[:text] = text if text
+        element = selector.get_by_role(role, **filters).first
+
+        unless element
+          desc = "No #{role} element"
+          desc << " with text #{text.inspect}" if text
+          desc << " found"
+          return desc
+        end
+
+        lines = ["Element: :#{element.role} #{element.text.inspect} at [#{element.row},#{element.col}]"]
+        lines << "Bounds: #{element.bounds.inspect}"
+        lines << "Actions:"
+        lines << "  click:       #{element.click.inspect}"
+        lines << "  type(text):  #{element.type("text").inspect}"
+        lines << "  press_key:   #{element.press_key(:enter).inspect}"
+        lines.join("\n")
+      end
+
+      def call_tui_diff(args)
+        ensure_driver!
+        snapshot = args["snapshot"] or return "ERROR: 'snapshot' argument is required"
+        chars_only = args["chars_only"] || false
+
+        current = TUITD::State.new(@driver.state_data)
+        snapshot = deep_symbolize(snapshot) if snapshot.is_a?(Hash)
+        diffs = current.diff(snapshot, chars_only: chars_only)
+
+        if diffs.empty?
+          "No differences found (chars_only: #{chars_only})"
+        else
+          lines = ["Found #{diffs.size} difference(s):"]
+          diffs.first(20).each do |d|
+            before_char = d[:before][:char].inspect
+            after_char = d[:after][:char].inspect
+            lines << "  [#{d[:row]},#{d[:col]}] #{before_char} -> #{after_char}"
+          end
+          lines << "  ... (truncated)" if diffs.size > 20
+          lines.join("\n")
+        end
+      end
+
+      def call_tui_annotate_element(args)
+        ensure_driver!
+        role = args["role"] or return "ERROR: 'role' argument is required"
+        row = args["row"] or return "ERROR: 'row' argument is required"
+        col = args["col"] or return "ERROR: 'col' argument is required"
+        width = args["width"] || 1
+        height = args["height"] || 1
+        text = args["text"]
+
+        state = TUITD::State.new(@driver.state_data)
+        state.annotate_role(role, row: row, col: col, width: width, height: height, text: text)
+
+        desc = "OK: Annotated :#{role} at [#{row},#{col}] #{width}x#{height}"
+        desc << " with text #{text.inspect}" if text
+        desc
+      end
+
+      def call_tui_save_snapshot(args)
+        ensure_driver!
+        name = args["name"] or return "ERROR: 'name' argument is required"
+        type = (args["type"] || "text").to_sym
+        snap = Snapshot.new(name, type: type)
+        snap.save(@driver.state_data)
+        "OK: Snapshot '#{name}' (type: #{type}) saved to #{snap.path}"
+      end
+
+      def call_tui_assert_snapshot(args)
+        ensure_driver!
+        name = args["name"] or return "ERROR: 'name' argument is required"
+        type = (args["type"] || "text").to_sym
+        snap = Snapshot.new(name, type: type)
+
+        if TUITD.configuration.update_snapshots?
+          snap.save(@driver.state_data)
+          return "OK: Snapshot '#{name}' (type: #{type}) updated (UPDATE_SNAPSHOTS mode)"
+        end
+
+        unless snap.exists?
+          snap.save(@driver.state_data)
+          return "OK: Snapshot '#{name}' (type: #{type}) created (first run)"
+        end
+
+        result = snap.compare(@driver.state_data)
+        if result.passed?
+          "OK: Snapshot '#{name}' (type: #{type}) matches"
+        else
+          "MISMATCH: #{result.message}"
+        end
+      end
+
       def call_tui_close
         @driver&.close
         @driver = nil
@@ -547,6 +791,17 @@ module TUITD
 
       # --- Helpers ---
 
+      def deep_symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+        when Array
+          obj.map { |v| deep_symbolize(v) }
+        else
+          obj
+        end
+      end
+
       def safe_path(user_path, ext:)
         default = File.join("/tmp", "tui_td_#{Time.now.to_i}.#{ext}")
         resolved = File.expand_path(user_path || default)