tui-td 0.2.14 → 0.2.19

data/lib/tui_td/minitest/assertions.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
+
+require "minitest"
+
+module TUITD
+  module Minitest
+    # Assertions for TUI testing with Minitest.
+    #
+    # Include this module in your Minitest test class:
+    #
+    #   require "tui_td/minitest/assertions"
+    #
+    #   class MyTUITest < Minitest::Test
+    #     include TUITD::Minitest::Assertions
+    #
+    #     def test_login_screen
+    #       driver = TUITD::Driver.new("my_tui", rows: 24, cols: 80)
+    #       driver.start
+    #       assert_text(driver, "Welcome")
+    #       assert_button(driver, "OK")
+    #       refute_text(driver, "Error")
+    #     ensure
+    #       driver&.close
+    #     end
+    #   end
+    #
+    # Auto-wait: When given a Driver, assertions wait up to 3 seconds.
+    # When given a State, assertions check immediately.
+    #
+    module Assertions
+      AUTO_WAIT_TIMEOUT = 3
+
+      private
+
+      def 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
+
+      def state_from(actual)
+        if actual.respond_to?(:state_data)
+          TUITD::State.new(actual.state_data)
+        else
+          actual # State or raw hash — pass through
+        end
+      end
+
+      public
+
+      # --- Text / Regex / Color / Style ---
+
+      def assert_text(actual, expected)
+        result = auto_wait(actual) { |s| s.find_text(expected).any? }
+        assert(result, "Expected terminal to contain #{expected.inspect}")
+      end
+
+      def refute_text(actual, expected)
+        result = auto_wait(actual) { |s| s.find_text(expected).empty? }
+        assert(result, "Expected terminal NOT to contain #{expected.inspect}")
+      end
+
+      def assert_regex(actual, pattern)
+        regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+        result = auto_wait(actual) { |s| s.find_text(regex).any? }
+        assert(result, "Expected terminal to match #{pattern.inspect}")
+      end
+
+      def refute_regex(actual, pattern)
+        regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+        result = auto_wait(actual) { |s| s.find_text(regex).empty? }
+        assert(result, "Expected terminal NOT to match #{pattern.inspect}")
+      end
+
+      def assert_fg(actual, expected, row:, col:)
+        result = auto_wait(actual) { |s| s.foreground_at(row, col) == expected }
+        actual_fg = state_from(actual).foreground_at(row, col)
+        assert(result, "Expected FG at [#{row},#{col}] to be #{expected.inspect}, but was #{actual_fg.inspect}")
+      end
+
+      def assert_bg(actual, expected, row:, col:)
+        result = auto_wait(actual) { |s| s.background_at(row, col) == expected }
+        actual_bg = state_from(actual).background_at(row, col)
+        assert(result, "Expected BG at [#{row},#{col}] to be #{expected.inspect}, but was #{actual_bg.inspect}")
+      end
+
+      def assert_style(actual, row:, col:, **expected_styles)
+        result = auto_wait(actual) do |s|
+          style = s.style_at(row, col)
+          expected_styles.all? { |k, v| style[k] == v }
+        end
+        actual_style = state_from(actual).style_at(row, col)
+        assert(result,
+               "Expected style at [#{row},#{col}] to be #{expected_styles.inspect}, but was #{actual_style.inspect}",)
+      end
+
+      def assert_exit_status(actual, expected)
+        status = actual.exitstatus
+        assert(status == expected, "Expected exit status #{expected}, but was #{status}")
+      end
+
+      # --- Selector-based ---
+
+      def assert_button(actual, expected)
+        result = auto_wait(actual) { |s| TUITD::Selector.new(s).button(text: expected) }
+        assert(result, "Expected terminal to have a button #{expected.inspect}")
+      end
+
+      def refute_button(actual, expected)
+        result = auto_wait(actual) { |s| TUITD::Selector.new(s).button(text: expected).nil? }
+        assert(result, "Expected terminal NOT to have a button #{expected.inspect}")
+      end
+
+      def assert_dialog(actual)
+        result = auto_wait(actual) { |s| TUITD::Selector.new(s).dialogs.any? }
+        assert(result, "Expected terminal to have a dialog")
+      end
+
+      def refute_dialog(actual)
+        result = auto_wait(actual) { |s| TUITD::Selector.new(s).dialogs.empty? }
+        assert(result, "Expected terminal NOT to have a dialog")
+      end
+
+      def assert_checkbox(actual, expected, checked: nil, unchecked: nil)
+        checked = false if unchecked
+        result = auto_wait(actual) do |s|
+          filters = { text: expected }
+          filters[:checked] = checked unless checked.nil?
+          TUITD::Selector.new(s).checkbox(**filters)
+        end
+        msg = "Expected terminal to have checkbox #{expected.inspect}"
+        msg += " (checked)" if checked == true
+        msg += " (unchecked)" if checked == false
+        assert(result, msg)
+      end
+
+      def assert_role(actual, role, text: nil, checked: nil, disabled: nil)
+        result = auto_wait(actual) do |s|
+          filters = {}
+          filters[:text] = text if text
+          filters[:checked] = checked unless checked.nil?
+          filters[:disabled] = disabled unless disabled.nil?
+          TUITD::Selector.new(s).get_by_role(role, **filters).any?
+        end
+        msg = "Expected terminal to have role :#{role}"
+        msg += " with text #{text.inspect}" if text
+        assert(result, msg)
+      end
+
+      def assert_input(actual, expected = nil)
+        result = auto_wait(actual) do |s|
+          if expected
+            TUITD::Selector.new(s).input(text: expected)
+          else
+            TUITD::Selector.new(s).inputs.any?
+          end
+        end
+        msg = "Expected terminal to have an input field"
+        msg += " #{expected.inspect}" if expected
+        assert(result, msg)
+      end
+
+      def assert_label(actual, expected = nil)
+        result = auto_wait(actual) do |s|
+          if expected
+            TUITD::Selector.new(s).label(text: expected)
+          else
+            TUITD::Selector.new(s).labels.any?
+          end
+        end
+        msg = "Expected terminal to have a label"
+        msg += " #{expected.inspect}" if expected
+        assert(result, msg)
+      end
+
+      def assert_menu(actual, expected = nil)
+        result = auto_wait(actual) do |s|
+          if expected
+            TUITD::Selector.new(s).menu(text: expected)
+          else
+            TUITD::Selector.new(s).menus.any?
+          end
+        end
+        msg = "Expected terminal to have a menu"
+        msg += " #{expected.inspect}" if expected
+        assert(result, msg)
+      end
+
+      def assert_tab(actual, expected = nil)
+        result = auto_wait(actual) do |s|
+          if expected
+            TUITD::Selector.new(s).tab(text: expected)
+          else
+            TUITD::Selector.new(s).tabs.any?
+          end
+        end
+        msg = "Expected terminal to have a tab"
+        msg += " #{expected.inspect}" if expected
+        assert(result, msg)
+      end
+
+      def assert_statusbar(actual, expected = nil)
+        result = auto_wait(actual) do |s|
+          if expected
+            TUITD::Selector.new(s).statusbar(text: expected)
+          else
+            TUITD::Selector.new(s).statusbars.any?
+          end
+        end
+        msg = "Expected terminal to have a status bar"
+        msg += " #{expected.inspect}" if expected
+        assert(result, msg)
+      end
+
+      def assert_progress_bar(actual, expected = nil)
+        result = auto_wait(actual) do |s|
+          if expected
+            TUITD::Selector.new(s).progress_bar(text: expected)
+          else
+            TUITD::Selector.new(s).progress_bars.any?
+          end
+        end
+        msg = "Expected terminal to have a progress bar"
+        msg += " #{expected.inspect}" if expected
+        assert(result, msg)
+      end
+
+      # --- Snapshot ---
+
+      def assert_snapshot(actual, name, type: :text, wait: false, region: nil, ignore_rows: nil)
+        snap = TUITD::Snapshot.new(name.to_s, type: type)
+
+        state_data = if actual.respond_to?(:state_data)
+                       actual.wait_for_stable if wait && actual.respond_to?(:wait_for_stable)
+                       actual.state_data
+                     elsif actual.respond_to?(:to_h)
+                       actual.to_h
+                     else
+                       actual
+                     end
+
+        if TUITD.configuration.update_snapshots? || !snap.exists?
+          snap.save(state_data)
+          pass
+        else
+          result = snap.compare(state_data, ignore_rows: ignore_rows, region: region)
+          msg = result.passed? ? nil : "Snapshot '#{name}' does not match.\n#{result.message}"
+          assert(result.passed?, msg)
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists

data/lib/tui_td/selector.rb

@@ -5,27 +5,4 @@ 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/snapshot.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+require "json"
+require "fileutils"
+
+module TUITD
+  # Named, persisted snapshot for terminal state comparison.
+  #
+  # First run: saves the snapshot to disk (golden master).
+  # Subsequent runs: compares current state against the saved snapshot.
+  #
+  # Types:
+  #   :text  - chars_only comparison (ignores colors/styles), saved as JSON
+  #   :full  - full cell comparison (includes colors/styles), saved as JSON
+  #   :png   - screenshot PNG, compared byte-by-byte
+  #   :html  - HTML render, compared byte-by-byte
+  #   :all   - saves/compares all three formats
+  #
+  # Environment:
+  #   UPDATE_SNAPSHOTS=1 — auto-update all snapshots instead of comparing
+  #
+  class Snapshot
+    EXTENSIONS = {
+      text: ".json",
+      full: ".json",
+      png: ".png",
+      html: ".html",
+    }.freeze
+
+    # Result of a snapshot comparison.
+    ComparisonResult = Struct.new(
+      :passed, :diff_count, :message, :details, :type,
+      keyword_init: true,
+    ) do
+      def passed?
+        passed
+      end
+    end
+
+    attr_reader :name, :type, :snapshot_dir
+
+    def initialize(name, type: :text, snapshot_dir: nil)
+      @name = name.to_s
+      @type = type.to_sym
+      @snapshot_dir = snapshot_dir || TUITD.configuration.snapshot_dir || "spec/snapshots"
+      FileUtils.mkdir_p(@snapshot_dir)
+    end
+
+    # Return the full filesystem path for the given extension.
+    def path(ext = EXTENSIONS.fetch(@type, ".json"))
+      File.join(@snapshot_dir, "#{@name}#{ext}")
+    end
+
+    # Check if the primary snapshot file exists on disk.
+    def exists?
+      if @type == :all
+        %i[text png html].all? { |t| File.exist?(path(EXTENSIONS[t])) }
+      else
+        File.exist?(path)
+      end
+    end
+
+    # Save terminal state as a named snapshot.
+    def save(state_data)
+      data = normalize(state_data)
+
+      File.write(path(".json"), JSON.pretty_generate(data)) if save_json?
+
+      Screenshot.new(data).render(path(".png")) if save_png?
+
+      return unless save_html?
+
+      HtmlRenderer.new(data).render(path(".html"))
+    end
+
+    # Compare current terminal state against the saved snapshot.
+    # Returns ComparisonResult.
+    def compare(state_data, ignore_rows: nil, region: nil)
+      if @type == :all
+        compare_all(state_data, ignore_rows: ignore_rows, region: region)
+      elsif png?
+        compare_png(state_data)
+      elsif html?
+        compare_html(state_data)
+      else
+        compare_json(state_data, chars_only: @type == :text, ignore_rows: ignore_rows, region: region)
+      end
+    end
+
+    private
+
+    def normalize(state_data)
+      return state_data if state_data.is_a?(Hash)
+
+      # Extract hash from State objects
+      if state_data.respond_to?(:grid) && state_data.respond_to?(:rows)
+        return {
+          size: { rows: state_data.rows, cols: state_data.cols },
+          cursor: state_data.cursor,
+          rows: state_data.grid,
+        }
+      end
+
+      state_data
+    end
+
+    def save_json?
+      %i[text full all].include?(@type)
+    end
+
+    def save_png?
+      %i[png all].include?(@type)
+    end
+
+    def save_html?
+      %i[html all].include?(@type)
+    end
+
+    def png?
+      @type == :png
+    end
+
+    def html?
+      @type == :html
+    end
+
+    def compare_json(state_data, chars_only:, ignore_rows: nil, region: nil)
+      file = path(".json")
+      return missing_file_result(file) unless File.exist?(file)
+
+      begin
+        saved = JSON.parse(File.read(file), symbolize_names: true)
+      rescue JSON::ParserError => e
+        return ComparisonResult.new(
+          passed: false, diff_count: 1, type: @type,
+          message: "Failed to parse snapshot JSON: #{e.message}",
+        )
+      end
+
+      current = TUITD::State.new(normalize(state_data))
+      saved_state = TUITD::State.new(saved)
+      diffs = current.diff(saved_state, chars_only: chars_only)
+
+      # Restrict to specified region first, then remove ignored rows
+      if region
+        region = Array(region)
+        diffs.select! { |d| region.include?(d[:row]) }
+      end
+      if ignore_rows
+        ignored = Array(ignore_rows)
+        diffs.reject! { |d| ignored.include?(d[:row]) }
+      end
+
+      if diffs.empty?
+        ComparisonResult.new(
+          passed: true, diff_count: 0, type: @type,
+          message: "Snapshot '#{@name}' matches (#{@type})",
+        )
+      else
+        details = diffs.first(20).map do |d|
+          {
+            row: d[:row], col: d[:col],
+            before: d[:before], after: d[:after],
+          }
+        end
+        msg = ["Snapshot '#{@name}' has #{diffs.size} difference(s) (#{@type}):"]
+        diffs.first(20).each do |d|
+          msg << "  [#{d[:row]},#{d[:col]}] #{d[:before][:char].inspect} -> #{d[:after][:char].inspect}"
+        end
+        msg << "  ... (truncated)" if diffs.size > 20
+        ComparisonResult.new(
+          passed: false, diff_count: diffs.size, type: @type,
+          message: msg.join("\n"), details: details,
+        )
+      end
+    end
+
+    def compare_png(state_data)
+      file = path(".png")
+      return missing_file_result(file) unless File.exist?(file)
+
+      expected = File.binread(file)
+      tmp = File.join(@snapshot_dir, ".#{@name}_tmp.png")
+      Screenshot.new(state_data).render(tmp)
+      actual = File.binread(tmp)
+      FileUtils.rm_f(tmp)
+
+      if expected == actual
+        ComparisonResult.new(
+          passed: true, diff_count: 0, type: :png,
+          message: "Snapshot '#{@name}' matches (png)",
+        )
+      else
+        ComparisonResult.new(
+          passed: false, diff_count: 1, type: :png,
+          message: "Snapshot '#{@name}' does not match (png — pixel difference)",
+        )
+      end
+    end
+
+    def compare_html(state_data)
+      file = path(".html")
+      return missing_file_result(file) unless File.exist?(file)
+
+      expected = File.read(file)
+      actual = HtmlRenderer.new(state_data).to_html
+
+      if expected == actual
+        ComparisonResult.new(
+          passed: true, diff_count: 0, type: :html,
+          message: "Snapshot '#{@name}' matches (html)",
+        )
+      else
+        ComparisonResult.new(
+          passed: false, diff_count: 1, type: :html,
+          message: "Snapshot '#{@name}' does not match (html — content difference)",
+        )
+      end
+    end
+
+    def compare_all(state_data, ignore_rows: nil, region: nil)
+      results = []
+      results << compare_json(state_data, chars_only: true, ignore_rows: ignore_rows, region: region)
+      results << compare_png(state_data)
+      results << compare_html(state_data)
+
+      all_passed = results.all?(&:passed?)
+      messages = results.map(&:message).join("\n")
+      total_diffs = results.sum(&:diff_count)
+
+      ComparisonResult.new(
+        passed: all_passed, diff_count: total_diffs, type: :all,
+        message: messages,
+      )
+    end
+
+    def missing_file_result(file)
+      ComparisonResult.new(
+        passed: false, diff_count: 0, type: @type,
+        message: "Snapshot '#{@name}' not found at #{file}",
+      )
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity

data/lib/tui_td/test_runner.rb

@@ -170,11 +170,62 @@ module TUITD
                   check_role(driver, :dialog, nil)
 
                 when "assert_checkbox"
-                  check_role(driver, :checkbox, value.to_s, checked: step[:checked])
+                  check_role(driver, :checkbox, value.to_s, checked: step[:checked], disabled: step[:disabled])
 
                 when "assert_role"
                   role = step[:role]&.to_sym
-                  check_role(driver, role, value.to_s)
+                  check_role(driver, role, value.to_s, checked: step[:checked], disabled: step[:disabled])
+
+                when "assert_input"
+                  check_role(driver, :input, value == true ? nil : value.to_s)
+
+                when "assert_label"
+                  check_role(driver, :label, value == true ? nil : value.to_s)
+
+                when "assert_menu"
+                  check_role(driver, :menu, value == true ? nil : value.to_s)
+
+                when "assert_tab"
+                  check_role(driver, :tab, value == true ? nil : value.to_s)
+
+                when "assert_statusbar"
+                  check_role(driver, :statusbar, value == true ? nil : value.to_s)
+
+                when "assert_progress_bar"
+                  check_role(driver, :progress, value == true ? nil : value.to_s)
+
+                when "snapshot"
+                  ensure_driver!(driver)
+                  driver.wait_for_stable if step[:wait] || step["wait"]
+                  snap_type = (step[:type] || step["type"] || :text).to_s.to_sym
+                  snap = Snapshot.new(value, type: snap_type)
+                  snap.save(driver.state_data)
+                  Result.new(step: action, passed: true,
+                             message: "Snapshot saved: #{value} (#{snap_type})",)
+
+                when "assert_snapshot"
+                  ensure_driver!(driver)
+                  driver.wait_for_stable if step[:wait] || step["wait"]
+                  snap_type = (step[:type] || step["type"] || :text).to_s.to_sym
+                  snap = Snapshot.new(value, type: snap_type)
+
+                  if TUITD.configuration.update_snapshots?
+                    snap.save(driver.state_data)
+                    Result.new(step: action, passed: true,
+                               message: "Snapshot updated: #{value} (#{snap_type})",)
+                  elsif !snap.exists?
+                    snap.save(driver.state_data)
+                    Result.new(step: action, passed: true,
+                               message: "Snapshot created: #{value} (#{snap_type})",)
+                  else
+                    result = snap.compare(driver.state_data)
+                    msg = if result.passed?
+                            "Snapshot matches: #{value}"
+                          else
+                            "Snapshot mismatch: #{value}\n#{result.message}"
+                          end
+                    Result.new(step: action, passed: result.passed?, message: msg)
+                  end
 
                 when "close"
                   driver&.close
@@ -224,21 +275,29 @@ module TUITD
 
     private
 
-    def check_role(driver, role, text, checked: nil)
+    def check_role(driver, role, text, checked: nil, disabled: 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?
+
+      filters = {}
+      filters[:text] = text.to_s if text
+      filters[:checked] = checked unless checked.nil?
+      filters[:disabled] = disabled unless disabled.nil?
+      elements = selector.get_by_role(role, **filters)
 
       action = "assert_#{role}"
       if elements.any?
         count = elements.size
         desc = text ? "#{role} #{text.inspect}" : role.to_s
+        desc += " (checked)" if checked == true
+        desc += " (unchecked)" if checked == false
+        desc += " (disabled)" if disabled == true
         Result.new(step: action, passed: true, message: "Found #{count} #{desc} element(s)")
       else
         desc = text ? "#{role} with text #{text.inspect}" : role.to_s
+        desc += " (checked)" if checked == true
+        desc += " (disabled)" if disabled == true
         Result.new(step: action, passed: false, message: "No #{desc} found")
       end
     end

data/lib/tui_td/version.rb

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

data/lib/tui_td.rb

@@ -13,10 +13,13 @@ require_relative "tui_td/driver"
 require_relative "tui_td/ansi_parser"
 require_relative "tui_td/ansi_utils"
 require_relative "tui_td/state"
+require_relative "tui_td/configuration"
+require_relative "tui_td/snapshot"
 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/minitest/assertions"
 require_relative "tui_td/mcp/server"
 require_relative "tui_td/cli"