Module: RatatuiRuby::TestHelper

Includes:
EventInjection, GlobalState, Snapshot, StyleAssertions, SubprocessTimeout, Terminal, TestDoubles
Defined in:
lib/ratatui_ruby/test_helper.rb,
lib/ratatui_ruby/test_helper/snapshot.rb,
lib/ratatui_ruby/test_helper/terminal.rb,
lib/ratatui_ruby/test_helper/global_state.rb,
lib/ratatui_ruby/test_helper/test_doubles.rb,
lib/ratatui_ruby/test_helper/event_injection.rb,
lib/ratatui_ruby/test_helper/style_assertions.rb,
lib/ratatui_ruby/test_helper/subprocess_timeout.rb

Overview

Helpers for testing RatatuiRuby applications.

Writing TUI tests by hand is tedious. You need a headless terminal, event injection, snapshot comparisons, and style assertions. Wiring all that up yourself is error-prone.

This module bundles everything you need. Include it in your test class and start writing tests immediately.

Included Mixins

Terminal

Sets up a headless terminal and queries its buffer.

Snapshot

Compares the screen against stored reference files.

EventInjection

Simulates keypresses, mouse clicks, and resize events.

StyleAssertions

Checks foreground color, background color, and text modifiers.

TestDoubles

Provides mocks and stubs for testing views in isolation.

GlobalState

Provides with_argv and with_env helpers for testing global state access.

Example

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

require "ratatui_ruby/test_helper"

class TestMyApp < Minitest::Test
  include RatatuiRuby::TestHelper

  def test_initial_render
    with_test_terminal(80, 24) do
      MyApp.new.run_once
      assert_snapshots("initial")
    end
  end

  def test_themes
    with_test_terminal do
      app = ThemeDemo.new
      app.run_once
      assert_rich_snapshot("default_theme")

      inject_key("t", modifiers: [:ctrl])
      app.run_once
      assert_rich_snapshot("dark_theme")

      inject_key("t", modifiers: [:ctrl])
      app.run_once
      assert_rich_snapshot("high_contrast_theme")
    end
  end

  def test_highlighter_applies_selection_style
    with_test_terminal(40, 5) do
      RatatuiRuby.draw do |frame|
        highlighter = MyApp::UI::Highlighter.new(:yellow)
        highlighter.render_at(frame, 0, 2, "Selected Item")
      end

      assert_fg_color(:yellow, 0, 2)
      assert_bold(0, 2)
    end
  end

  def test_view_in_isolation
    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
  end
end

– SPDX-SnippetEnd ++

Defined Under Namespace

Modules: EventInjection, GlobalState, Snapshot, StyleAssertions, SubprocessTimeout, Terminal, TestDoubles

Class Method Summary collapse

Methods included from GlobalState

#with_argv, #with_env

Methods included from StyleAssertions

#assert_area_style, #assert_bg_color, #assert_bold, #assert_cell_style, #assert_color, #assert_crossed_out, #assert_dim, #assert_fg_color, #assert_hidden, #assert_italic, #assert_rapid_blink, #assert_reversed, #assert_slow_blink, #assert_underlined

Methods included from EventInjection

#inject_click, #inject_drag, #inject_event, #inject_keys, #inject_mouse, #inject_right_click, #inject_sync

Methods included from Snapshot

#assert_plain_snapshot, #assert_rich_snapshot, #assert_screen_matches, #assert_snapshots, #render_rich_buffer

Methods included from Terminal

#buffer_content, #cursor_position, #get_cell, #print_buffer, #with_test_terminal

Class Method Details

.included(base) ⇒ Object

Auto-enables debug mode when TestHelper is included.

This ensures Rust backtraces are available in tests. Skips remote debugging since tests don’t need it.



103
104
105
 
# File 'lib/ratatui_ruby/test_helper.rb', line 103

def self.included(base)
  RatatuiRuby::Debug.enable!(source: :test)
end