Module: RatatuiRuby::TestHelper::Terminal

Included in:
RatatuiRuby::TestHelper
Defined in:
lib/ratatui_ruby/test_helper/terminal.rb

Overview

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Instance Method Summary collapse

Instance Method Details

#buffer_content ⇒ Object

Current content of the terminal buffer as an array of strings. Each string represents one row.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

buffer_content
# => ["Row 1 text", "Row 2 text", ...]

– SPDX-SnippetEnd ++



116
117
118
 
# File 'lib/ratatui_ruby/test_helper/terminal.rb', line 116

def buffer_content
  RatatuiRuby.get_buffer_content.split("\n")
end

#cursor_position ⇒ Object

Current cursor position as a hash with :x and :y keys.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

cursor_position
# => { x: 0, y: 0 }

– SPDX-SnippetEnd ++



135
136
137
138
 
# File 'lib/ratatui_ruby/test_helper/terminal.rb', line 135

def cursor_position
  x, y = RatatuiRuby.get_cursor_position
  { x:, y: }
end

#get_cell(x, y) ⇒ Object

Cell attributes at the given coordinates.

Returns a hash with "symbol", "fg", and "bg" keys.

x

Integer column position (0-indexed).

y

Integer row position (0-indexed).

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

get_cell(0, 0)
# => { "symbol" => "H", "fg" => :red, "bg" => nil }

– SPDX-SnippetEnd ++



160
161
162
 
# File 'lib/ratatui_ruby/test_helper/terminal.rb', line 160

def get_cell(x, y)
  RatatuiRuby.get_cell_at(x, y)
end

#print_buffer ⇒ Object

Prints the current buffer to STDOUT with full ANSI colors. Useful for debugging test failures.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

with_test_terminal do
  MyApp.new.render
  print_buffer  # see exactly what would display
end

– SPDX-SnippetEnd ++



182
183
184
 
# File 'lib/ratatui_ruby/test_helper/terminal.rb', line 182

def print_buffer
  puts _render_buffer_with_ansi
end

#with_test_terminal(width = 80, height = 24, **opts) ⇒ Object

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 nil to disable.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

with_test_terminal(120, 40) do
  # render and test your app
end

– SPDX-SnippetEnd ++



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/ratatui_ruby/test_helper/terminal.rb', line 66

def with_test_terminal(width = 80, height = 24, **opts)
  # Defensive cleanup: reset any stale session state from previous test failures
  RatatuiRuby.instance_variable_set(:@tui_session_active, false)

  # Extract and resolve viewport
  viewport_param = opts[:viewport]
  viewport = case viewport_param
  when nil then RatatuiRuby::Terminal::Viewport.fullscreen
  when RatatuiRuby::Terminal::Viewport then viewport_param
  end

  RatatuiRuby.init_test_terminal(width, height, viewport.type.to_s, viewport.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