tui-td 0.2.17 → 0.2.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cadf6d0ad5e362e3704a7a87673e0ad7254573eba2f53575aea38fc45f949877
-  data.tar.gz: fbfd589b84e911d6c46b16976b34dc46943019c52bd7519b04ffc6422a71b659
+  metadata.gz: 48cd9df54d8ad7bc1d41b8d4cfd961462ecff6e8056c4fd37e46abb56fa50f38
+  data.tar.gz: c77b9a6eb3a048806d17d4f5b2245dcf82dd1c5e818a247db48912e9b590d78d
 SHA512:
-  metadata.gz: c0e8f58b7f193a556d2dee0e1f8c15f005b669fe3823d31763e57efd8c35d511f5e2e5dbb9ff03a61abe534030c1673cc1de437bcbe705b8c008c1ff9af8878a
-  data.tar.gz: 520f31800ee26803d9ec56b9128b729f59a057246a11e2b70c1647f253b76bb95e06f99631fb4d6c23597415e8a48a92725e22c36b99faca932cb75d00c84d8c
+  metadata.gz: ce4bdb6d4397369717686756508ec43219340ed4a0cc0ec8a4851018a19dc19bbdec3050147238a221cd4b282c92d848df1d71a1377b4915bfb42282af400d95
+  data.tar.gz: 6053e73dd915f8839d92ef8b046578bae6fbf481b0fda21872851e7e9052816833ce62ab5d6a4d15a685ce517f161fe31e75d5a9309a0dacb3521a3df4e893af

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## 0.2.17
+
+### Added
+
+- Named snapshot testing: `match_snapshot("name")` — first run creates golden master,
+  subsequent runs compare. Supports `type: :text` (chars_only), `:full`, `:png`, `:html`, `:all`.
+- `ignore_rows:` parameter — skip specific rows during snapshot comparison
+- `region:` parameter — restrict comparison to a row range (e.g., `region: 0..6`)
+  Combinable with `ignore_rows:` for fine-grained control.
+- `UPDATE_SNAPSHOTS=1` — environment variable to auto-update all snapshots
+- `TUITD.configure { |c| c.snapshot_dir = "..." }` — configurable snapshot directory
+- `Driver#find_text(pattern, match:)` — convenience delegation to State#find_text
+- `Driver#snapshot` — returns a State snapshot for in-memory comparison
+- JSON test steps: `snapshot`, `assert_snapshot` with `type:` and `wait:` options
+- MCP tools: `tui_save_snapshot`, `tui_assert_snapshot`, `tui_element_actions`,
+  `tui_annotate_element`, `tui_diff`
+- Drive mode: `snapshot <name>`, `diff <name>` commands
+- `TUITD::Snapshot` class — core abstraction for save/load/compare of named snapshots
+- `TUITD::Configuration` class — global gem configuration
+
+### Changed
+
+- `match_snapshot` matcher: now accepts String names (named snapshots) in addition to
+  legacy State objects. New kwargs: `type:`, `wait:`, `ignore_rows:`, `region:`.
+- `tui_find_text` MCP tool: added `match:` parameter (`partial`, `exact`, `regex`)
+- `tui_find_elements` MCP tool: added `checked:`/`disabled:` filters, new roles
+- `tui_diff` MCP tool: fixed deep key symbolization for snapshot hash compatibility
+- Dependency: tans-parser `~> 0.1.3`
+
 ## 0.2.16
 
 ### Added

data/README.md

@@ -379,6 +379,56 @@ end
 | `have_progress_bar("50%")` | Assert a progress bar (`[####]`) is visible |
 | `have_exit_status(N)` | Assert the driver process exit status equals N |
 
+## Snapshot Testing
+
+Named, persisted snapshot testing à la Playwright/Jest. First run creates a golden master — subsequent runs compare.
+
+### RSpec
+
+```ruby
+# Named snapshot (recommended)
+expect(driver).to match_snapshot("login_screen")
+expect(driver).to match_snapshot("login_screen", type: :all, wait: true)
+
+# Partial screen comparison
+expect(driver).to match_snapshot("banner", region: 0..6, chars_only: true)
+
+# Skip volatile rows (e.g., prompt line)
+expect(driver).to match_snapshot("main", ignore_rows: [5])
+
+# In-memory comparison (legacy)
+pre = driver.snapshot
+expect(driver).to match_snapshot(pre, chars_only: true)
+```
+
+### Configuration
+
+```ruby
+TUITD.configure do |c|
+  c.snapshot_dir = "spec/snapshots"   # default
+end
+
+# Update all snapshots
+UPDATE_SNAPSHOTS=1 bundle exec rspec
+```
+
+### JSON Test Steps
+
+```json
+{"snapshot": "login_screen", "type": "text"}
+{"assert_snapshot": "login_screen", "type": "png", "wait": true}
+```
+
+### Types
+
+| Type | Comparison | File |
+|------|-----------|------|
+| `:text` | chars only (ignores colors/styles) | `.json` |
+| `:full` | full cell comparison (chars + colors) | `.json` |
+| `:png` | screenshot byte-identical | `.png` |
+| `:html` | HTML render byte-identical | `.html` |
+| `:all` | all three at once | `.json` + `.png` + `.html` |
+
 ## MCP Server — AI Integration
 
 Start the MCP server to let any MCP client control TUIs:
@@ -407,6 +457,8 @@ tui-td serve
 | `tui_element_actions` | Get click/type/press_key action hashes for a detected UI element. For AI-driven interaction. |
 | `tui_diff` | Compare current state against a previous snapshot. Returns cell-level differences. |
 | `tui_annotate_element` | Manually register a UI element annotation. Picked up by tui_find_elements. |
+| `tui_save_snapshot` | Save the current terminal state as a named snapshot to disk. |
+| `tui_assert_snapshot` | Assert current state matches a saved named snapshot. Creates on first run. |
 | `tui_close` | Close the TUI and clean up. |
 
 ### MCP configuration

data/lib/tui_td/cli.rb

@@ -120,6 +120,8 @@ module TUITD
           _help_test
         when "rspec"
           _help_rspec
+        when "minitest"
+          _help_minitest
         when nil
           _help_main
         else
@@ -373,8 +375,9 @@ module TUITD
     def _help_main
       puts(OptionParser.new { |o| o.banner = "Usage: tui-td <command> [options]" })
       puts
-      puts "For more: tui-td help test   (JSON test step types)"
-      puts "          tui-td help rspec  (RSpec matchers)"
+      puts "For more: tui-td help test     (JSON test step types)"
+      puts "          tui-td help rspec    (RSpec matchers)"
+      puts "          tui-td help minitest (Minitest assertions)"
       exit 0
     end
 
@@ -504,6 +507,15 @@ module TUITD
           {"assert_progress_bar": true} or {"assert_progress_bar": "50%"}
               Assert that a progress bar ([####   ]) is visible.
 
+          {"snapshot": "login_screen", "type": "text", "wait": true}
+              Save current terminal state as a named snapshot to disk.
+              type: "text" (default), "full", "png", "html", "all".
+
+          {"assert_snapshot": "login_screen", "type": "text", "wait": true}
+              Assert current state matches a saved named snapshot.
+              First run creates the golden master (passes automatically).
+              UPDATE_SNAPSHOTS=1 to force update all snapshots.
+
         Example test file: examples/echo_test.json
       HELP
       exit 0
@@ -616,9 +628,19 @@ module TUITD
             Passes if a progress bar ([####   ]) is visible.
             Usage: expect(state).to have_progress_bar
 
-        match_snapshot(snapshot, chars_only: false)
-            Passes if the current state matches a previously saved snapshot.
-            Use chars_only: true to ignore color/style changes.
+        match_snapshot("<name>", type: :text, wait: false, region: 0..6, ignore_rows: [2])
+            Named, persisted snapshot testing. First run creates the snapshot
+            (passes automatically), subsequent runs compare.
+            Types: :text (chars_only, default), :full (chars+colors), :png, :html, :all.
+            region: restricts comparison to a row range (e.g., 0..6).
+            ignore_rows: skips specific rows during comparison.
+            UPDATE_SNAPSHOTS=1 to auto-update all snapshots.
+            Usage: expect(driver).to match_snapshot("login_screen")
+            Usage: expect(driver).to match_snapshot("banner", region: 0..6, chars_only: true)
+            Usage: expect(driver).to match_snapshot("main", ignore_rows: [5], wait: true)
+
+        match_snapshot(State, chars_only: false)  (legacy in-memory)
+            Passes if the current state matches a previously saved snapshot object.
             Usage: pre = driver.snapshot; ... ; expect(driver).to match_snapshot(pre)
             Usage: expect(state).to match_snapshot(snap, chars_only: true)
 
@@ -631,6 +653,108 @@ module TUITD
       HELP
       exit 0
     end
+
+    def _help_minitest
+      puts <<~HELP
+        Minitest Assertions
+        ===================
+
+        Include the assertions module in your Minitest test class:
+
+          require "tui_td/minitest/assertions"
+
+          class MyTUITest < Minitest::Test
+            include TUITD::Minitest::Assertions
+
+            def setup
+              @driver = TUITD::Driver.new("my_tui", rows: 24, cols: 80)
+              @driver.start
+            end
+
+            def teardown
+              @driver&.close
+            end
+          end
+
+        Auto-wait: When given a Driver, assertions wait up to 3 seconds.
+        When given a State, assertions check immediately.
+
+        Assertions
+        ----------
+
+        Text / Regex / Color / Style:
+
+        assert_text(driver, "Welcome")
+            Passes if text appears anywhere in the terminal.
+            Negate: refute_text(driver, "Error")
+
+        assert_regex(driver, /error|fail/)
+            Passes if regex pattern matches anywhere.
+            Negate: refute_regex(driver, /pattern/)
+
+        assert_fg(driver, "cyan", row: 0, col: 5)
+            Assert foreground color at position.
+
+        assert_bg(driver, "blue", row: 0, col: 0)
+            Assert background color at position.
+
+        assert_style(driver, row: 0, col: 0, bold: true, italic: false)
+            Assert style attributes at position.
+
+        assert_exit_status(driver, 0)
+            Assert the process exit status matches expected.
+
+        Selector assertions:
+
+        assert_button(driver, "OK")
+            Passes if a button with given text is visible.
+            Negate: refute_button(driver, "Cancel")
+
+        assert_dialog(driver)
+            Passes if a dialog (box-drawing region) is visible.
+            Negate: refute_dialog(driver)
+
+        assert_checkbox(driver, "Label", checked: true)
+            Passes if checkbox with given label (and optionally state) is visible.
+            Use checked: true, checked: false, or unchecked: true.
+
+        assert_role(driver, :button, text: "OK", checked: nil, disabled: nil)
+            Generic role assertion. Accepts :button, :checkbox, :dialog,
+            :statusbar, :progress, :input, :label, :menu, :tab.
+
+        assert_input(driver)
+        assert_input(driver, "Name")
+            Passes if an input field ([____]) is visible.
+
+        assert_label(driver, "Username")
+            Passes if a label (text ending with colon) is visible.
+
+        assert_menu(driver)
+            Passes if a menu bar or dropdown item is visible.
+
+        assert_tab(driver, "File")
+            Passes if a tab is visible.
+
+        assert_statusbar(driver)
+            Passes if a status bar (bottom row with background) is visible.
+
+        assert_progress_bar(driver, "50%")
+            Passes if a progress bar ([####   ]) is visible.
+
+        Snapshot:
+
+        assert_snapshot(driver, "login_screen", type: :text, wait: true)
+            Named snapshot testing. First run creates golden master,
+            subsequent runs compare.
+
+        assert_snapshot(driver, "banner", region: 0..6, chars_only: true)
+            Partial screen comparison with region:.
+
+        assert_snapshot(driver, "main", ignore_rows: [5])
+            Skip volatile rows with ignore_rows:.
+      HELP
+      exit 0
+    end
   end
 end
 # rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength

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/version.rb

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

data/lib/tui_td.rb

@@ -19,6 +19,7 @@ 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"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.2.17
+  version: 0.2.19
 platform: ruby
 authors:
 - Haluk Durmus
@@ -151,7 +151,8 @@ dependencies:
         version: '1.50'
 description: tui-td drives terminal applications in a PTY, captures ANSI state as
   structured data, and provides PNG screenshots and HTML renders. Includes an MCP
-  server for AI-driven testing, a JSON test runner, and RSpec matchers.
+  server for AI-driven testing, a JSON test runner, RSpec matchers, Minitest assertions,
+  semantic selectors, and named snapshot testing.
 email:
 - haluk_durmus@yahoo.de
 executables:
@@ -173,6 +174,7 @@ files:
 - lib/tui_td/html_renderer.rb
 - lib/tui_td/matchers.rb
 - lib/tui_td/mcp/server.rb
+- lib/tui_td/minitest/assertions.rb
 - lib/tui_td/screenshot.rb
 - lib/tui_td/selector.rb
 - lib/tui_td/snapshot.rb
@@ -204,5 +206,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: TUI testing framework — language-agnostic via JSON tests and MCP
+summary: TUI testing framework — RSpec, Minitest, JSON, and MCP
 test_files: []