Module: Charming::TestHelper

Defined in:
lib/charming/test_helper.rb

Overview

TestHelper provides controller- and component-level test ergonomics for Charming apps, in the spirit of Rails’ ActionController::TestCase:

require "charming/test_helper"

RSpec.describe HomeController do
  include Charming::TestHelper

  let(:ctrl) { build_controller(HomeController) }

  it "renders a greeting" do
    expect(ctrl.dispatch(:show)).to render_text("Welcome")
  end

  it "quits on q" do
    expect(press(ctrl_class: HomeController, key: "q")).to be_quit
  end
end

Helpers:

  • ‘build_controller(klass, app:, screen:, route:)` — controller instance wired to an app

  • ‘key_event(“ctrl+p”)` — build a KeyEvent from a human-readable string

  • ‘press(controller_or_class, “down”)` — dispatch a key press, returns the Response

  • ‘press_sequence(klass, [“down”, “down”, “enter”], app:)` — dispatch several presses

RSpec matchers (when RSpec is loaded):

  • ‘expect(response).to render_text(“…”)` / `render_match(/…/)`

  • ‘expect(response).to be_quit` / `be_navigate` (predicate matchers on Response)

  • ‘expect(response).to navigate_to(“/path”)`

Instance Method Summary collapse

Instance Method Details

#build_controller(controller_class, app: nil, screen: nil, route: nil, event: nil) ⇒ Object

Builds a controller instance with sensible test defaults: a fresh Application, an 80x24 screen, and no event.



38
39
40
41
42
 
# File 'lib/charming/test_helper.rb', line 38

def build_controller(controller_class, app: nil, screen: nil, route: nil, event: nil)
  app ||= Charming::Application.new
  screen ||= Charming::Screen.new(width: 80, height: 24)
  controller_class.new(application: app, event: event, screen: screen, route: route)
end

#key_event(description) ⇒ Object

Builds a KeyEvent from a human-readable string like “q”, “down”, “ctrl+p”, or “shift+tab”. Modifier order is irrelevant.



46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/charming/test_helper.rb', line 46

def key_event(description)
  parts = description.to_s.split("+")
  key = parts.pop
  modifiers = parts.map(&:downcase)
  char = (key.length == 1) ? key : nil
  Charming::Events::KeyEvent.new(
    key: key.to_sym,
    char: char,
    ctrl: modifiers.include?("ctrl") || modifiers.include?("control"),
    alt: modifiers.include?("alt"),
    shift: modifiers.include?("shift")
  )
end

#memory_backend(*keys, width: 80, height: 24) ⇒ Object

Builds a MemoryBackend pre-seeded with KeyEvents parsed from keys, ready to be passed to Charming::Runtime for integration-style tests.



76
77
78
79
 
# File 'lib/charming/test_helper.rb', line 76

def memory_backend(*keys, width: 80, height: 24)
  events = keys.map { |key| key.is_a?(String) ? key_event(key) : key }
  Charming::Internal::Terminal::MemoryBackend.new(events: events, width: width, height: height)
end

#press(controller_class, key, app:, screen: nil, route: nil) ⇒ Object

Dispatches a single key press against controller_class and returns the Response. Pass ‘app:` to share session state across presses.



62
63
64
65
 
# File 'lib/charming/test_helper.rb', line 62

def press(controller_class, key, app:, screen: nil, route: nil)
  controller = build_controller(controller_class, app: app, screen: screen, route: route, event: key_event(key))
  controller.dispatch_key
end

#press_sequence(controller_class, keys, app:, screen: nil, route: nil) ⇒ Object

Dispatches each key in keys in order against fresh controller instances sharing app’s session (mirroring the runtime’s controller-per-event model). Returns the last Response.



70
71
72
 
# File 'lib/charming/test_helper.rb', line 70

def press_sequence(controller_class, keys, app:, screen: nil, route: nil)
  keys.map { |key| press(controller_class, key, app: app, screen: screen, route: route) }.last
end