tuile 0.16.0 → 0.17.0

data/lib/tuile/testing.rb

@@ -4,8 +4,8 @@ module Tuile
   # Finds a component in the tree, so a spec can drive the UI it built four
   # layers down:
   #
-  #   Testing.get(Component::Button, caption: "Save").handle_key?(Keys::ENTER)
-  #   Testing.get(id: :name).value = "Zaphod"
+  #   Testing.get(id: :save).handle_key?(Keys::ENTER)
+  #   Testing.get(Component::TextField, id: :name).value = "Zaphod"
   #   Testing.find(Component::Checkbox, in: pane, count: 3)
   #
   # {.get} demands exactly one match and raises with a {.dump} of the tree it
@@ -13,6 +13,16 @@ module Tuile
   # search {Screen}'s whole tree by default — popups included, since they live
   # under the same {ScreenPane} as the content — or the subtree given as `in:`.
   #
+  # **The handles are structural — a class, an {Component#id}, a subtree — never
+  # what a component *says*.** There is no `caption:` filter: chrome text is UI
+  # copy, and a lookup keyed to it makes a rewording break a spec that tests
+  # nothing about the wording. Where a spec does want it, the block says so
+  # per-class and needs nothing from the framework:
+  #
+  #   Testing.get(Component::Button) { _1.caption.to_s == "Save" }
+  #
+  # See `D_component_lookup`.
+  #
   # **Call these qualified**, as above: `find` and `get` collide with names a
   # spec suite is likely to have already (Capybara's `find`), so there is no
   # `Component#get` and mixing this module in is not recommended. Tuile's own
@@ -29,20 +39,69 @@ module Tuile
   # There is deliberately no `visible:` filter handing one back to drive
   # (`D_visibility`).
   #
-  # For *what a component shows*, assert on {Screen#buffer} instead — this
-  # locates and drives, it does not replace that channel. See book ch8 for the
-  # worked usage and `design/decisions.md` `D_component_lookup` for the design.
+  # == Setup
+  #
+  # A spec dispatches no event, so nothing lays out what a mutation left
+  # pending: call {Component#flush_layout} before reading a rect — it settles
+  # the whole tree, from any component in it. {.place} sizes a component the
+  # way its parent would (`rect=` raises outside the parent's `relayout`) and
+  # settles on its own:
+  #
+  #   Testing.place(field, Rect.new(0, 0, 20, 1))   # already settled
+  #   field.visible = false
+  #   field.flush_layout                            # before reading any rect
+  #
+  # `place` never attaches: that is the spec's own step. The pane hands its
+  # content the whole screen, so to attach at a size put an `Absolute` between:
+  #
+  #   holder = Component::Layout::Absolute.new
+  #   Screen.instance.content = holder
+  #   holder.add(field, Rect.new(0, 0, 20, 1))      # attached, at that rect
+  #
+  # The terminal is 160×50; pick another size with `Screen.fake(width:, height:)`,
+  # or resize mid-example as the terminal would report it:
+  #
+  #   Screen.instance.resize_terminal(80, 24)      # FakeScreen#resize_terminal
+  #
+  # == Gestures
+  #
+  # Drive what you found as a *user* would: {.click} routes a real press and
+  # {.set_value} refuses a field the keyboard cannot reach, where a bare
+  # `handle_key?` or `value=` on a handle asserts neither.
+  # {Tuile::Testing::Gestures} gives them receiver syntax:
+  #
+  #   using Tuile::Testing::Gestures
+  #
+  #   Testing.get(Component::TextField, id: :name)._value = "Zaphod"
+  #   Testing.get(Component::Button, id: :save)._click
+  #
+  # == Painting
+  #
+  # {.paint} returns what one component paints, in a {Buffer} of its own whose
+  # `(0, 0)` is the component's top-left. For what the *user* sees, popups
+  # included, call {Screen#repaint} and read {Screen#buffer} at the component's
+  # {Component#absolute_rect}.
+  #
+  # See book ch8 for the worked usage, and `design/decisions.md`
+  # `D_component_lookup` / `D_test_gestures` for the design.
   module Testing
-    # Raised when the match count is not the one asked for. A {Tuile::Error},
-    # so an app rescuing that still catches it.
-    class LookupError < Error; end
+    # Raised by every lookup and every gesture that does not hold: the match
+    # count is not the one asked for, or a gesture was handed a component no
+    # user could have operated.
+    #
+    # **Not a {Tuile::Error}**, which is production's. It descends from
+    # `Exception` rather than `StandardError` for the reason
+    # `Minitest::Assertion` does: a stray `rescue` must not swallow a failed
+    # assertion. Tuile defines its own because the gem depends on no test
+    # framework.
+    class AssertionError < Exception; end # rubocop:disable Lint/InheritException
 
     class << self
       # Every component in the searched tree matching the spec, in pre-order.
       #
       #   find(Component::Button)                     # every button on screen
       #   find(Component::HasBadInput, in: form)      # a mixin works too
-      #   find(Component::Label, caption: /^Total/)   # Regexp: partial match
+      #   find(Component::Label) { _1.text.to_s.start_with?("Total") }
       #   find(Component::Popup, count: 1..)          # assert at least one
       #
       # @param klass [Module] matched with `is_a?`, so a mixin
@@ -50,27 +109,24 @@ module Tuile
       # @param in [Component, nil] root of the subtree to search, itself
       #   included. Defaults to `Screen.instance.pane` — the whole UI.
       # @param id [Symbol, nil] matched against {Component#id}.
-      # @param caption [String, Regexp, nil] matched with `===` against
-      #   {Component::HasCaption#caption}`.to_s`, so a String is exact and a
-      #   Regexp is a partial match. Never matches a component without a
-      #   caption.
       # @param count [Integer, Range, nil] how many matches are expected; any
       #   number when nil.
       # @yield [component] optional extra predicate; a component matches only
-      #   when the block returns truthy.
+      #   when the block returns truthy. This is where a text test goes — see
+      #   the module doc for why there is no `caption:` term.
       # @yieldparam component [Component]
       # @yieldreturn [Boolean]
-      # @raise [LookupError] if `count` is given and the match count differs.
+      # @raise [AssertionError] if `count` is given and the match count differs.
       # @return [Array<Component>]
-      def find(klass = Component, in: nil, id: nil, caption: nil, count: nil, &predicate)
+      def find(klass = Component, in: nil, id: nil, count: nil, &predicate)
         # `in` is a Ruby keyword, so the local it binds is unreachable by name.
         scope = binding.local_variable_get(:in) || Screen.instance.pane
-        spec = ->(c) { matches_spec?(c, klass, id, caption, predicate) }
+        spec = ->(c) { matches_spec?(c, klass, id, predicate) }
         matches = []
         scope.walk_shown_tree { |c| matches << c if spec.call(c) }
         return matches if count.nil? || spec_match?(count, matches.size)
 
-        raise LookupError, failure(klass, id, caption, predicate, count, matches, scope, spec)
+        raise AssertionError, failure(klass, id, predicate, count, matches, scope, spec)
       end
 
       # The one component matching the spec — {.find} with `count: 1`, so it
@@ -81,15 +137,14 @@ module Tuile
       # @param klass [Module] see {.find}.
       # @param in [Component, nil] see {.find}.
       # @param id [Symbol, nil] see {.find}.
-      # @param caption [String, Regexp, nil] see {.find}.
       # @yield [component] see {.find}.
       # @yieldparam component [Component]
       # @yieldreturn [Boolean]
-      # @raise [LookupError] unless exactly one component matches.
+      # @raise [AssertionError] unless exactly one component matches.
       # @return [Component]
-      def get(klass = Component, in: nil, id: nil, caption: nil, &predicate)
+      def get(klass = Component, in: nil, id: nil, &predicate)
         scope = binding.local_variable_get(:in)
-        find(klass, in: scope, id:, caption:, count: 1, &predicate).first
+        find(klass, in: scope, id:, count: 1, &predicate).first
       end
 
       # The searched tree, one component per row, indented by depth and with
@@ -108,6 +163,7 @@ module Tuile
       #   that matched the spec but were skipped for being hidden.
       # @return [String]
       def dump(scope, marked = [], excluded = [])
+        settle_layout
         base = scope.depth
         rows = []
         # walk_tree, not walk_shown_tree: a reader looks here to find out where
@@ -117,37 +173,257 @@ module Tuile
                  elsif excluded.any? { _1.equal?(c) } then "⊘"
                  else " "
                  end
-          row = c.inspect.sub("#<Tuile::Component::", "#<").sub("#<Tuile::", "#<")
+          row = brief(c)
           rows << "#{mark} #{"  " * (c.depth - base)}#{row}"
         end
         rows.join("\n")
       end
 
+      # Clicks `component` as the terminal would: a press and a release at the
+      # top-left cell of its {Component#absolute_extent_rect}, posted through
+      # {Screen#handle_mouse}, so it focuses and dismisses popups exactly as a
+      # real click does.
+      #
+      #   Testing.click(Testing.get(Component::Button, id: :save))
+      #
+      # It does **not** raise when the press lands and nobody claims it: a user
+      # really can click a {Component::Label} and have nothing happen, so this
+      # asserts the click was possible, not that it achieved something.
+      # @param component [Component]
+      # @param button [Symbol] `:left`, `:middle` or `:right`.
+      # @raise [AssertionError] unless a press at that cell reaches `component`
+      #   — it is unattached, hidden, collapsed to no cells, or covered.
+      # @return [void]
+      def click(component, button: :left)
+        point = gesture_point(component)
+        path = component_path_at(point)
+        unless path.include?(component)
+          reached = path.empty? ? "nothing — a modal popup is open" : brief(path.last)
+          raise AssertionError, "#{brief(component)} is not clickable at #{point.x},#{point.y}: " \
+                                "a press there reaches #{reached}\n" \
+                                "searched:\n#{dump(Screen.instance.pane, [component])}"
+        end
+
+        Screen.instance.handle_mouse(Mouse::DownEvent.new(button, point.x, point.y))
+        Screen.instance.handle_mouse(Mouse::UpEvent.new(point.x, point.y))
+      end
+
+      # Sets a field's value as a user who could reach it would.
+      #
+      #   Testing.set_value(Testing.get(Component::IntegerField, id: :age), 25)
+      #
+      # **Moves no focus** — no keystroke is involved — and writes through
+      # {Component::HasValue#set_value} with `from_user: true`, so it is the
+      # value-level shortcut rather than a simulation of typing: the editor's
+      # `insert_text` and its input filters never run, yet a listener reading
+      # {Component::HasValue::ValueChangeEvent#from_user?} sees the user's edit.
+      # The reachability checks below are what keep that claim honest.
+      # @param component [Component]
+      # @param value [Object] whatever the field's {Component::HasValue#set_value} takes.
+      # @raise [AssertionError] unless `component` is a {Component::HasValue}
+      #   the keyboard can reach: shown with every ancestor shown, and inside
+      #   {ScreenPane#key_scope}, so a field behind a modal popup refuses.
+      # @return [void]
+      def set_value(component, value)
+        unless component.is_a?(Component::HasValue)
+          raise AssertionError, "#{brief(component)} is not a field: set_value needs a Component::HasValue"
+        end
+        unless component.focusable?
+          raise AssertionError, "#{brief(component)} is not focusable, so a user could never edit it"
+        end
+
+        scope = Screen.instance.pane.key_scope
+        unless reachable?(component, scope)
+          where = scope.nil? ? "the pane has no content" : "the key scope is #{brief(scope)}"
+          raise AssertionError, "#{brief(component)} is hidden or out of reach: #{where}\n" \
+                                "searched:\n#{dump(Screen.instance.pane, [component])}"
+        end
+
+        component.set_value(value, from_user: true)
+      end
+
+      # Moves `component` to `rect` within the parent it already has, through
+      # whatever places it there, since {Component#rect=} raises outside the
+      # parent's `relayout`. It never changes the tree:
+      #
+      #   Testing.place(label, Rect.new(0, 0, 10, 1))      # a parentless root
+      #   Testing.place(field, Rect.new(2, 1, 20, 1))      # moves it in its Layout::Absolute
+      #   Testing.place(popup, Rect.new(5, 5, 30, 10))     # an open overlay: At[rect]
+      #
+      # A parentless root is sized in a throwaway {Component::Layout::Absolute}
+      # and released again, so it stays unattached.
+      # @param component [Component]
+      # @param rect [Rect] in the parent's coordinates (the screen's, for an
+      #   overlay).
+      # @raise [ArgumentError] if any other container places `component` — move
+      #   it by its constraint there. That includes the pane's content, which is
+      #   always the whole screen: put a {Component::Layout::Absolute} in between.
+      # @return [Component] `component`, settled.
+      def place(component, rect)
+        parent = component.parent
+        case parent
+        when nil
+          holder = Component::Layout::Absolute.new
+          holder.add(component, rect)
+          holder.flush_layout
+          holder.remove(component)
+        when Component::Layout::Absolute
+          parent.constrain(component, rect)
+        when ScreenPane
+          unless component.is_a?(Component::Overlay)
+            raise ArgumentError, "place: the pane gives its content, #{component}, the whole screen; " \
+                                 "put a Layout::Absolute in between, or resize the terminal"
+          end
+
+          component.placement = Component::Overlay::At[rect]
+        else
+          raise ArgumentError, "place: #{parent} places #{component} itself; constrain it there"
+        end
+        component.tap(&:flush_layout)
+      end
+
+      # Paints `component` and its subtree, attached or not, into a {Buffer} of
+      # its own size whose `(0, 0)` is the component's top-left:
+      #
+      #   Testing.place(window, Rect.new(0, 0, 14, 4))
+      #   buffer = Testing.paint(window)
+      #   buffer.text                  # => ["┌Caption─────┐", "│ alpha      │", …]
+      #   buffer.cell(1, 1).style      # component coordinates, no absolute_rect
+      #
+      # What the component paints, not what the user sees: popups over it don't
+      # show, and ancestors don't clip it — only their background shows through.
+      # {Screen#buffer} is left untouched.
+      #
+      # == Implementation details
+      #
+      # A {Component#repaint} paints only its own ink and queues its children,
+      # so this walks the subtree in {Screen#repaint}'s order: pre-order, shown
+      # components only, nothing under an empty rect. The queued children stay
+      # on the screen's queue, harmlessly: a detached one is dropped, an
+      # attached one repaints unchanged.
+      # @param component [Component]
+      # @raise [AssertionError] if `component` is hidden, or has no cell to
+      #   paint — {.place} it first.
+      # @return [Buffer]
+      def paint(component)
+        component.flush_layout
+        raise AssertionError, "#{brief(component)} is hidden, so it paints nothing" unless component.visible?
+        if component.rect.empty?
+          raise AssertionError, "#{brief(component)} has no cell to paint: place it first, " \
+                                "or it is deliberately collapsed"
+        end
+
+        buffer = Buffer.new(component.rect.size)
+        paint_subtree(component, component, buffer)
+        buffer
+      end
+
+      # The shown components under `point`, outermost first — the descent
+      # {Mouse::Router} makes when the terminal reports a press there.
+      #
+      # A deliberate copy of the router's private walk, kept honest by
+      # `testing_spec`'s pin against where a press is really delivered. When
+      # that pin gets hard to keep green the two have diverged for a reason:
+      # move the walk onto {Mouse::Router} and delete this.
+      # @param point [Point]
+      # @return [Array<Component>]
+      def component_path_at(point)
+        settle_layout
+        path = []
+        component = Screen.instance.pane.mouse_root_at(point)
+        while component&.visible? && component.rect.contains?(point)
+          # Rebase into the component's own coordinates as the router does:
+          # a rect is parent-relative (`D_relative_rect`).
+          point = Point.new(point.x - component.rect.left, point.y - component.rect.top)
+          path << component
+          component = component.children.find { _1.visible? && _1.rect.contains?(point) }
+        end
+        path
+      end
+
       private
 
+      # The cell a pointer gesture aims at: the top-left of what the component
+      # actually paints.
+      #
+      # The three refusals are ordered because a layout gives a hidden child no
+      # row, so a *hidden* component reaches the geometry check with an empty
+      # rect and would be reported as collapsed if that ran first.
+      # @param component [Component] the target of a pointer gesture.
+      # @raise [AssertionError] if no cell of it could be clicked.
+      # @return [Point]
+      def gesture_point(component)
+        settle_layout
+        raise AssertionError, "#{brief(component)} is not attached to the screen" unless component.attached?
+
+        unless reachable?(component, Screen.instance.pane)
+          raise AssertionError, "#{brief(component)} is hidden, or sits under a hidden ancestor"
+        end
+
+        rect = component.absolute_extent_rect
+        if rect.empty?
+          raise AssertionError, "#{brief(component)} has no cell to click: the tree was never laid " \
+                                "out (repaint the screen first), or it is deliberately collapsed"
+        end
+
+        Point.new(rect.left, rect.top)
+      end
+
+      # Brings child rects up to date before anything here reads one — these
+      # helpers run straight from spec code, with no event dispatched to settle
+      # the layout the way the loop's would. A no-op with nothing pending.
+      # @return [void]
+      def settle_layout
+        Screen.instance.flush_layout if Screen.instance?
+      end
+
+      # @param component [Component] the node to paint, with its subtree.
+      # @param root [Component] the component {.paint} was asked for.
+      # @param buffer [Buffer]
+      # @return [void]
+      def paint_subtree(component, root, buffer)
+        return if !component.visible? || component.rect.empty?
+
+        component.repaint(Screen.instance.canvas_for(component, backend: buffer, root:))
+        component.children.each { paint_subtree(_1, root, buffer) }
+      end
+
+      # Whether `component` is shown, ancestors included, *and* inside `scope`.
+      # One walk answers both: `walk_shown_tree` skips a hidden subtree whole.
+      # @param component [Component]
+      # @param scope [Component, nil] see {ScreenPane#key_scope}.
+      # @return [Boolean]
+      def reachable?(component, scope)
+        return false if scope.nil?
+
+        scope.walk_shown_tree { |c| return true if c.equal?(component) }
+        false
+      end
+
+      # @param component [Component]
+      # @return [String] its `inspect` with the `Tuile::` namespaces stripped,
+      #   as {.dump} prints it.
+      def brief(component)
+        component.inspect.sub("#<Tuile::Component::", "#<").sub("#<Tuile::", "#<")
+      end
+
       # @param component [Component]
       # @param klass [Module] see {.find}.
       # @param id [Symbol, nil] see {.find}.
-      # @param caption [String, Regexp, nil] see {.find}.
       # @param predicate [Proc, nil] see {.find}.
       # @return [Boolean] whether the component satisfies every given term.
       #   Visibility is the *walk's* business, deliberately not tested here, so
       #   {.failure} can re-run this over the components the walk skipped.
-      def matches_spec?(component, klass, id, caption, predicate)
+      def matches_spec?(component, klass, id, predicate)
         return false unless component.is_a?(klass)
         return false unless id.nil? || component.id == id
-        if !caption.nil? &&
-           !(component.is_a?(Component::HasCaption) && spec_match?(caption, component.caption.to_s))
-          return false
-        end
 
         predicate.nil? || predicate.call(component)
       end
 
-      # Whether `actual` satisfies a spec value, which for both `caption:` and
-      # `count:` may be either an exact value or a pattern — `===` is the
-      # feature, not an accident: a String caption matches exactly and a Regexp
-      # partially, an Integer count exactly and a Range as a bound.
+      # Whether `actual` satisfies a `count:` spec, which may be an exact value
+      # or a pattern — `===` is the feature, not an accident: an Integer matches
+      # exactly and a Range as a bound.
       # @param spec [Object] the expected value or pattern.
       # @param actual [Object]
       # @return [Boolean]
@@ -155,7 +431,6 @@ module Tuile
 
       # @param klass [Module] the class or mixin that was asked for.
       # @param id [Symbol, nil] the id spec, if any.
-      # @param caption [String, Regexp, nil] the caption spec, if any.
       # @param predicate [Proc, nil] the block spec, if any.
       # @param count [Integer, Range] the count that was not met.
       # @param matches [Array<Component>] what the search did find.
@@ -163,10 +438,9 @@ module Tuile
       # @param spec [Proc] the same term test the search ran, re-run over the
       #   components the walk skipped.
       # @return [String]
-      def failure(klass, id, caption, predicate, count, matches, scope, spec)
+      def failure(klass, id, predicate, count, matches, scope, spec)
         wanted = [(klass.name || klass.to_s).sub("Tuile::", "")]
         wanted << "id=#{id.inspect}" unless id.nil?
-        wanted << "caption=#{caption.inspect}" unless caption.nil?
         wanted << "matching the block" unless predicate.nil?
         excluded = hidden_matches(scope, spec)
         "expected #{count} #{wanted.join(" ")}, found #{matches.size}#{excluded_note(excluded)}\n" \