ratatui_ruby 0.5.0 → 0.6.0

data/lib/ratatui_ruby/test_helper/style_assertions.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Assertions for verifying cell-level styling in terminal UIs.
+    #
+    # TUI styling is invisible to plain text comparisons. Colors, bold, italic,
+    # and other modifiers define the visual hierarchy. Without style assertions,
+    # you cannot verify that your highlight is actually highlighted.
+    #
+    # This mixin provides assertions to check foreground, background, and modifiers
+    # at specific coordinates or across entire regions.
+    #
+    # Use it to verify selection highlights, error colors, or themed areas.
+    #
+    # === Examples
+    #
+    #   # Single cell
+    #   assert_cell_style(0, 0, fg: :red, modifiers: [:bold])
+    #
+    #   # Foreground color at coordinate
+    #   assert_color(:green, x: 5, y: 2)
+    #
+    #   # Entire header region
+    #   assert_area_style({ x: 0, y: 0, w: 80, h: 1 }, bg: :blue)
+    #
+    module StyleAssertions
+      ##
+      # Asserts that a cell has the expected style attributes.
+      #
+      # === Example
+      #
+      #   assert_cell_style(0, 0, char: "H", fg: :red)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      # [expected_attributes] Hash of attribute names to expected values.
+      def assert_cell_style(x, y, **expected_attributes)
+        cell = get_cell(x, y)
+        expected_attributes.each do |key, value|
+          actual_value = cell.public_send(key)
+          if value.nil?
+            assert_nil actual_value, "Expected cell at (#{x}, #{y}) to have #{key}=nil, but got #{actual_value.inspect}"
+          else
+            assert_equal value, actual_value, "Expected cell at (#{x}, #{y}) to have #{key}=#{value.inspect}, but got #{actual_value.inspect}"
+          end
+        end
+      end
+
+      ##
+      # Asserts foreground or background color at a coordinate.
+      #
+      # Accepts symbols (<tt>:red</tt>), indexed colors (integers), or hex strings.
+      #
+      # === Examples
+      #
+      #   assert_color(:red, x: 10, y: 5)
+      #   assert_color(5, x: 10, y: 5, layer: :bg)
+      #   assert_color("#ff00ff", x: 10, y: 5)
+      #
+      # [expected] Symbol, Integer, or String (hex).
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      # [layer] <tt>:fg</tt> (default) or <tt>:bg</tt>.
+      def assert_color(expected, x:, y:, layer: :fg)
+        cell = get_cell(x, y)
+        actual = cell.public_send(layer)
+
+        # Normalize expected integer to symbol if needed (RatatuiRuby returns :indexed_N)
+        expected_normalized = if expected.is_a?(Integer)
+          :"indexed_#{expected}"
+        else
+          expected
+        end
+
+        assert_equal expected_normalized, actual,
+          "Expected #{layer} at (#{x}, #{y}) to be #{expected.inspect}, but got #{actual.inspect}"
+      end
+
+      ##
+      # Asserts that all cells in an area have the expected style.
+      #
+      # === Examples
+      #
+      #   header = RatatuiRuby::Rect.new(x: 0, y: 0, width: 80, height: 1)
+      #   assert_area_style(header, bg: :blue, modifiers: [:bold])
+      #
+      #   assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, fg: :red)
+      #
+      # [area] Rect-like object or Hash with x, y, width/w, height/h.
+      # [attributes] Style attributes to verify.
+      def assert_area_style(area, **attributes)
+        if area.is_a?(Hash)
+          x = area[:x] || 0
+          y = area[:y] || 0
+          w = area[:width] || area[:w] || 0
+          h = area[:height] || area[:h] || 0
+        else
+          x = area.x
+          y = area.y
+          w = area.width
+          h = area.height
+        end
+
+        (y...(y + h)).each do |row|
+          (x...(x + w)).each do |col|
+            assert_cell_style(col, row, **attributes)
+          end
+        end
+      end
+
+      ##
+      # Asserts the foreground color at a coordinate.
+      #
+      # Convenience alias for <tt>assert_color(expected, x:, y:, layer: :fg)</tt>.
+      #
+      # === Example
+      #
+      #   assert_fg_color(:yellow, 0, 2)
+      #
+      # [expected] Symbol, Integer, or String (hex).
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_fg_color(expected, x, y)
+        assert_color(expected, x:, y:, layer: :fg)
+      end
+      alias assert_fg assert_fg_color
+
+      ##
+      # Asserts the background color at a coordinate.
+      #
+      # Convenience alias for <tt>assert_color(expected, x:, y:, layer: :bg)</tt>.
+      #
+      # === Example
+      #
+      #   assert_bg_color(:blue, 0, 2)
+      #
+      # [expected] Symbol, Integer, or String (hex).
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_bg_color(expected, x, y)
+        assert_color(expected, x:, y:, layer: :bg)
+      end
+      alias assert_bg assert_bg_color
+
+      ##
+      # Asserts that a cell has the bold modifier.
+      #
+      # === Example
+      #
+      #   assert_bold(0, 2)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_bold(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:bold),
+          "Expected cell at (#{x}, #{y}) to be bold, but modifiers were #{modifiers.inspect}"
+      end
+
+      ##
+      # Asserts that a cell has the italic modifier.
+      #
+      # === Example
+      #
+      #   assert_italic(0, 2)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_italic(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:italic),
+          "Expected cell at (#{x}, #{y}) to be italic, but modifiers were #{modifiers.inspect}"
+      end
+
+      ##
+      # Asserts that a cell has the underlined modifier.
+      #
+      # === Example
+      #
+      #   assert_underlined(0, 2)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_underlined(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:underlined),
+          "Expected cell at (#{x}, #{y}) to be underlined, but modifiers were #{modifiers.inspect}"
+      end
+      alias assert_underline assert_underlined
+
+      ##
+      # Asserts that a cell has the dim modifier.
+      #
+      # === Example
+      #
+      #   assert_dim(0, 2)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_dim(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:dim),
+          "Expected cell at (#{x}, #{y}) to be dim, but modifiers were #{modifiers.inspect}"
+      end
+
+      ##
+      # Asserts that a cell has the reversed (inverse video) modifier.
+      #
+      # === Example
+      #
+      #   assert_reversed(0, 2)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_reversed(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:reversed),
+          "Expected cell at (#{x}, #{y}) to be reversed, but modifiers were #{modifiers.inspect}"
+      end
+      alias assert_inverse assert_reversed
+      alias assert_inverse_video assert_reversed
+
+      ##
+      # Asserts that a cell has the crossed_out (strikethrough) modifier.
+      #
+      # === Example
+      #
+      #   assert_crossed_out(0, 2)
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_crossed_out(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:crossed_out),
+          "Expected cell at (#{x}, #{y}) to be crossed_out, but modifiers were #{modifiers.inspect}"
+      end
+      alias assert_strikethrough assert_crossed_out
+      alias assert_strike assert_crossed_out
+
+      ##
+      # Asserts that a cell has the hidden modifier.
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_hidden(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:hidden),
+          "Expected cell at (#{x}, #{y}) to be hidden, but modifiers were #{modifiers.inspect}"
+      end
+
+      ##
+      # Asserts that a cell has the slow_blink modifier.
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_slow_blink(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:slow_blink),
+          "Expected cell at (#{x}, #{y}) to have slow_blink, but modifiers were #{modifiers.inspect}"
+      end
+      alias assert_blink assert_slow_blink
+
+      ##
+      # Asserts that a cell has the rapid_blink modifier.
+      #
+      # [x] Integer x-coordinate.
+      # [y] Integer y-coordinate.
+      def assert_rapid_blink(x, y)
+        cell = get_cell(x, y)
+        modifiers = (cell.modifiers || []).map(&:to_sym)
+        assert modifiers.include?(:rapid_blink),
+          "Expected cell at (#{x}, #{y}) to have rapid_blink, but modifiers were #{modifiers.inspect}"
+      end
+      # Color-specific assertion helpers.
+      #
+      # Manually specifying <tt>:red</tt> or <tt>:blue</tt> in every <tt>assert_color</tt> call is repetitive.
+      # It hides the intent of the test behind boilerplate arguments.
+      #
+      # These meta-programmed helpers provide a punchy, intent-focused API. Use them to
+      # verify colors with minimal ceremony.
+      #
+      # === Standard Foreground Color Aliases
+      #
+      # - <tt>assert_black(x, y)</tt>
+      # - <tt>assert_red(x, y)</tt>
+      # - <tt>assert_green(x, y)</tt>
+      # - <tt>assert_yellow(x, y)</tt>
+      # - <tt>assert_blue(x, y)</tt>
+      # - <tt>assert_magenta(x, y)</tt>
+      # - <tt>assert_cyan(x, y)</tt>
+      # - <tt>assert_gray(x, y)</tt>
+      # - <tt>assert_dark_gray(x, y)</tt>
+      # - <tt>assert_light_red(x, y)</tt>
+      # - <tt>assert_light_green(x, y)</tt>
+      # - <tt>assert_light_yellow(x, y)</tt>
+      # - <tt>assert_light_blue(x, y)</tt>
+      # - <tt>assert_light_magenta(x, y)</tt>
+      # - <tt>assert_light_cyan(x, y)</tt>
+      # - <tt>assert_white(x, y)</tt>
+      #
+      # === Standard Background Color Aliases
+      #
+      # - <tt>assert_bg_black(x, y)</tt>
+      # - <tt>assert_bg_red(x, y)</tt>
+      # - ...and so on for all standard colors.
+      [
+        :black,
+        :red,
+        :green,
+        :yellow,
+        :blue,
+        :magenta,
+        :cyan,
+        :gray,
+        :dark_gray,
+        :light_red,
+        :light_green,
+        :light_yellow,
+        :light_blue,
+        :light_magenta,
+        :light_cyan,
+        :white,
+      ].each do |color|
+        # :method: assert_#{color}
+        # Asserts the foreground color at (x, y) is <tt>:#{color}</tt>.
+        define_method(:"assert_#{color}") do |x, y|
+          assert_fg_color(color, x, y)
+        end
+
+        # :method: assert_bg_#{color}
+        # Asserts the background color at (x, y) is <tt>:#{color}</tt>.
+        define_method(:"assert_bg_#{color}") do |x, y|
+          assert_bg_color(color, x, y)
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper/terminal.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "timeout"
+require "minitest/mock"
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Terminal setup and buffer inspection for TUI tests.
+    #
+    # Testing TUIs against a real terminal is slow, flaky, and hard to automate.
+    # Initializing, cleaning up, and inspecting terminal state by hand is tedious.
+    #
+    # This mixin wraps a headless test terminal. It handles setup, teardown,
+    # and provides methods to query buffer content, cursor position, and cell styles.
+    #
+    # Use it to write fast, deterministic tests for your TUI applications.
+    #
+    # === Example
+    #
+    #   class MyTest < Minitest::Test
+    #     include RatatuiRuby::TestHelper
+    #
+    #     def test_rendering
+    #       with_test_terminal(80, 24) do
+    #         MyApp.new.run_once
+    #         assert_includes buffer_content.join, "Hello"
+    #       end
+    #     end
+    #   end
+    module Terminal
+      ##
+      # Initializes a test terminal context with specified dimensions.
+      # Restores the original terminal state after the block executes.
+      #
+      # [width] Integer width of the test terminal (default: 80).
+      # [height] Integer height of the test terminal (default: 24).
+      # [timeout] Integer maximum execution time in seconds (default: 2). Pass <tt>nil</tt> to disable.
+      #
+      # === Example
+      #
+      #   with_test_terminal(120, 40) do
+      #     # render and test your app
+      #   end
+      def with_test_terminal(width = 80, height = 24, **opts)
+        RatatuiRuby.init_test_terminal(width, height)
+        # Flush any lingering events from previous tests
+        while (event = RatatuiRuby.poll_event) && !event.none?; end
+
+        RatatuiRuby.stub :init_terminal, nil do
+          RatatuiRuby.stub :restore_terminal, nil do
+            @_ratatui_test_terminal_active = true
+            timeout = opts.fetch(:timeout, 2)
+            if timeout
+              Timeout.timeout(timeout) do
+                yield
+              end
+            else
+              yield
+            end
+          ensure
+            @_ratatui_test_terminal_active = false
+          end
+        end
+      ensure
+        RatatuiRuby.restore_terminal
+      end
+
+      ##
+      # Current content of the terminal buffer as an array of strings.
+      # Each string represents one row.
+      #
+      # === Example
+      #
+      #   buffer_content
+      #   # => ["Row 1 text", "Row 2 text", ...]
+      def buffer_content
+        RatatuiRuby.get_buffer_content.split("\n")
+      end
+
+      ##
+      # Current cursor position as a hash with <tt>:x</tt> and <tt>:y</tt> keys.
+      #
+      # === Example
+      #
+      #   cursor_position
+      #   # => { x: 0, y: 0 }
+      def cursor_position
+        x, y = RatatuiRuby.get_cursor_position
+        { x:, y: }
+      end
+
+      ##
+      # Cell attributes at the given coordinates.
+      #
+      # Returns a hash with <tt>"symbol"</tt>, <tt>"fg"</tt>, and <tt>"bg"</tt> keys.
+      #
+      # [x] Integer column position (0-indexed).
+      # [y] Integer row position (0-indexed).
+      #
+      # === Example
+      #
+      #   get_cell(0, 0)
+      #   # => { "symbol" => "H", "fg" => :red, "bg" => nil }
+      def get_cell(x, y)
+        RatatuiRuby.get_cell_at(x, y)
+      end
+
+      ##
+      # Prints the current buffer to STDOUT with full ANSI colors.
+      # Useful for debugging test failures.
+      #
+      # === Example
+      #
+      #   with_test_terminal do
+      #     MyApp.new.render
+      #     print_buffer  # see exactly what would display
+      #   end
+      def print_buffer
+        puts _render_buffer_with_ansi
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper/test_doubles.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Test doubles for view testing.
+    #
+    # View tests verify widget rendering without a real terminal. Real frames draw
+    # to the screen. Real rects come from terminal dimensions. Mocking both by hand
+    # is tedious.
+    #
+    # This mixin provides <tt>MockFrame</tt> to capture rendered widgets and
+    # <tt>StubRect</tt> to supply fixed dimensions.
+    #
+    # Use them to test view logic in isolation.
+    #
+    # === Example
+    #
+    #   frame = MockFrame.new
+    #   area = StubRect.new(width: 60, height: 20)
+    #   MyView.new.call(state, tui, frame, area)
+    #
+    #   widget = frame.rendered_widgets.first[:widget]
+    #   assert_equal "Dashboard", widget.block.title
+    module TestDoubles
+      ##
+      # Mock frame for view tests.
+      #
+      # Captures widgets passed to <tt>render_widget</tt> for later inspection.
+      #
+      # === Example
+      #
+      #   frame = MockFrame.new
+      #   View::Log.new.call(state, tui, frame, area)
+      #   widget = frame.rendered_widgets.first[:widget]
+      #   assert_equal "Event Log", widget.block.title
+      MockFrame = Data.define(:rendered_widgets) do
+        def initialize(rendered_widgets: [])
+          super
+        end
+
+        def render_widget(widget, area)
+          rendered_widgets << { widget:, area: }
+        end
+      end
+
+      ##
+      # Stub rect with fixed dimensions.
+      #
+      # [x] Integer left edge (default: 0).
+      # [y] Integer top edge (default: 0).
+      # [width] Integer width in cells (default: 80).
+      # [height] Integer height in cells (default: 24).
+      #
+      # === Example
+      #
+      #   area = StubRect.new(width: 60, height: 20)
+      StubRect = Data.define(:x, :y, :width, :height) do
+        def initialize(x: 0, y: 0, width: 80, height: 24)
+          super
+        end
+      end
+    end
+  end
+end