syrma 0.1.0

data/lib/syrma/window_driver.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Syrma
+  class WindowDriver
+    I = Zaniah::Input
+
+    attr_reader :window, :session
+
+    def initialize(window, session)
+      @window = window
+      @session = session
+      Instrumentation.capture(window, lazy_raster: session.raster == :lazy)
+      @builder = SnapshotBuilder.new
+    end
+
+    def strict = session.strict
+
+    def tree
+      session.settle
+      @tree = nil if @tree && @tree.frame != window.testing_frame
+      @tree ||= @builder.build(window)
+    end
+
+    def find(**conditions, &predicate) = Locator.new(self, Criteria.new(conditions, predicate))
+    def all(**conditions, &predicate) = find(**conditions, &predicate).resolve_all
+    def test_id(id) = find(test_id: id)
+    def text(value) = find(text: value)
+    def texts = tree.text_runs.map { |run| run[2] }
+    def tooltip = tree.tooltip
+
+    def button(label)
+      find(clickable: true) do |node|
+        node.content_text == label &&
+          node.descendants.none? { |descendant| descendant.clickable? && descendant.content_text == label }
+      end
+    end
+
+    def at(x, y = nil, event: :mouse_down, button: :left)
+      point = x.is_a?(Zaniah::Point) ? x : Zaniah::Point.new(x, y)
+      tree.hit_at(point, event: event, button: button)
+    end
+
+    def pixel(x, y)
+      width = window.content_size.width.to_i
+      height = window.content_size.height.to_i
+      x = Integer(x)
+      y = Integer(y)
+      raise RangeError, "Pixel coordinates are out of bounds: #{x},#{y}" unless x.between?(0, width - 1) && y.between?(0, height - 1)
+
+      session.screenshot_pixels(self).byteslice((y * width + x) * 4, 4).bytes
+    end
+
+    def screenshot(path = nil)
+      width = window.content_size.width.to_i
+      height = window.content_size.height.to_i
+      pixels = session.screenshot_pixels(self)
+      return pixels unless path
+
+      Zaniah::PNG.write(path, width, height, pixels)
+      path
+    end
+
+    def terminal_lines(colors: false)
+      raise UnsupportedBackend, "terminal_lines is only available for TUI sessions" unless session.tui?(self)
+
+      session.settle
+      TerminalFormat.lines(session.output_for(self).string, colors: colors)
+    end
+
+    def click(target = nil, button: :left, modifiers: [], count: 1, offset: nil, force: false, **criteria)
+      target = criteria unless criteria.empty?
+      point = actionable_point(target, :mouse_down, button, force, offset)
+      gesture do
+        dispatch I::MouseMove.new(point, modifiers)
+        dispatch I::MouseDown.new(point, button, modifiers, count)
+        dispatch I::MouseUp.new(point, button, modifiers)
+      end
+    end
+
+    def double_click(target, **options)
+      click(target, **options, count: 1)
+      click(target, **options, count: 2)
+    end
+
+    def right_click(target, **options) = click(target, **options, button: :right)
+    def hover(target) = dispatch(I::MouseMove.new(actionable_point(target, :mouse_move, :left, false, nil), []))
+
+    def drag(from, to, steps: 8, button: :left, modifiers: [])
+      raise ArgumentError, "steps must be a positive integer" unless steps.is_a?(Integer) && steps.positive?
+
+      start = actionable_point(from, :mouse_down, button, false, nil)
+      finish = point_for(to)
+      gesture do
+        dispatch I::MouseMove.new(start, modifiers)
+        dispatch I::MouseDown.new(start, button, modifiers, 1)
+        1.upto(steps) do |index|
+          ratio = index.fdiv(steps)
+          dispatch I::MouseMove.new(
+            Zaniah::Point.new(start.x + (finish.x - start.x) * ratio,
+                              start.y + (finish.y - start.y) * ratio), modifiers
+          )
+        end
+        dispatch I::MouseUp.new(finish, button, modifiers)
+      end
+    end
+
+    def scroll(target, dx: 0, dy: 0, modifiers: [])
+      point = actionable_point(target, :scroll, :left, false, nil)
+      dispatch I::ScrollWheel.new(point, Zaniah::Point.new(dx, dy), nil, modifiers)
+    end
+
+    def mouse_move(point, modifiers: []) = dispatch(I::MouseMove.new(point_for(point), modifiers))
+    def mouse_down(point, button: :left, modifiers: [], count: 1) = dispatch(I::MouseDown.new(point_for(point), button, modifiers, count))
+    def mouse_up(point, button: :left, modifiers: []) = dispatch(I::MouseUp.new(point_for(point), button, modifiers))
+
+    def press(*keystrokes)
+      keystrokes.each do |stroke|
+        normalized = I::Keystroke.normalize(stroke)
+        gesture do
+          dispatch I::KeyDown.new(normalized, false)
+          dispatch I::KeyUp.new(normalized)
+        end
+      end
+    end
+
+    def key_down(stroke, held: false) = dispatch(I::KeyDown.new(I::Keystroke.normalize(stroke), held))
+    def key_up(stroke) = dispatch(I::KeyUp.new(I::Keystroke.normalize(stroke)))
+
+    def type(text, key_events: true)
+      text.each_grapheme_cluster do |character|
+        key = character == " " ? "space" : character.downcase
+        gesture do
+          dispatch I::KeyDown.new(key, false) if key_events
+          dispatch I::TextInput.new(character)
+          dispatch I::KeyUp.new(key) if key_events
+        end
+      end
+    end
+
+    def paste(text) = dispatch(I::TextInput.new(text))
+    def compose(text, selection: nil) = dispatch(I::Composition.new(text, selection))
+    def commit(text) = dispatch(I::TextInput.new(text))
+
+    def drop_files(paths, at:)
+      dispatch I::FileDrop.new(Array(paths).map(&:to_s), point_for(at))
+    end
+
+    def resize(width, height)
+      window.resize(width, height)
+      session.settle
+    end
+
+    def close = window.close
+
+    def feed_terminal(bytes)
+      raise UnsupportedBackend, "feed_terminal is only available for TUI sessions" unless window.respond_to?(:feed_input)
+
+      window.feed_input(bytes)
+      session.settle
+    end
+
+    def scroll_until(list, found:, step: 100, max: 50)
+      target = find(**found)
+      max.times do
+        return target if target.exists? && target.resolve_all.any?(&:visible?)
+
+        scroll(list, dy: step)
+      end
+      raise ElementNotFound.new(target, tree)
+    end
+
+    def menu = (@menu_driver ||= PopupDriver.new(self))
+
+    def dispatch(event)
+      session.event_log.add(window.testing_frame, window.title, event)
+      window.input(event)
+      session.settle unless @in_gesture && session.event_frames == :gesture
+      event
+    end
+
+    def gesture
+      outer = @in_gesture
+      @in_gesture = true
+      yield
+    ensure
+      @in_gesture = outer
+      session.settle unless outer
+    end
+
+    private
+
+    def normalize_target(target)
+      return find(**target) if target.is_a?(Hash)
+      return Zaniah::Point.new(*target) if target.is_a?(Array) && target.length == 2
+
+      target
+    end
+
+    def resolve_node(target)
+      target = normalize_target(target)
+      target.is_a?(Locator) ? target.resolve : target
+    end
+
+    def point_for(target)
+      target = normalize_target(target)
+      return target if target.is_a?(Zaniah::Point)
+
+      resolve_node(target).center
+    end
+
+    def actionable_point(target, event, button, force, offset)
+      target = normalize_target(target)
+      return target if target.is_a?(Zaniah::Point)
+
+      last_error = nil
+      session.wait_for(-> { "Target did not become actionable: #{target}\n  Last reason: #{last_error&.message}" }) do
+        current_tree = tree
+        node = target.is_a?(Locator) ? target.resolve(current_tree) : target
+        point = offset ? offset_point(node, offset) : node.center
+        force ? point : check_actionable(current_tree, node, event, button, point)
+      rescue ElementNotFound, AmbiguousMatch, NotActionable => error
+        raise if error.is_a?(AmbiguousMatch)
+
+        last_error = error
+        nil
+      end
+    end
+
+    def offset_point(node, offset)
+      x, y = offset.respond_to?(:x) ? [offset.x, offset.y] : offset
+      Zaniah::Point.new(node.visible_bounds.x + x, node.visible_bounds.y + y)
+    end
+
+    def check_actionable(current_tree, node, event, button, preferred = nil)
+      bounds = node.bounds
+      unless bounds.width.positive? && bounds.height.positive?
+        raise NotActionable.new(:invisible, "#{node.inspect} has zero size")
+      end
+      unless node.visible?
+        raise NotActionable.new(:outside_viewport, "#{node.inspect} is outside the viewport or clipped by an ancestor")
+      end
+      raise NotActionable.new(:popup, "A context menu has captured input") if current_tree.menu
+
+      points = preferred ? [preferred] : samples(node.visible_bounds)
+      points.each do |point|
+        hit = current_tree.hit_at(point, event: event, button: button)
+        next if hit.nil?
+
+        return point if hit.equal?(node) || node.ancestor_of?(hit) || hit.ancestor_of?(node)
+      end
+      blocker = current_tree.hit_at(preferred || node.center, event: event, button: button)
+      reason = blocker ? :obscured : :no_handler
+      message = blocker ? "#{node.inspect} is covered by #{blocker.inspect}" : "No element receives events at #{node.inspect}"
+      raise NotActionable.new(reason, message)
+    end
+
+    def samples(bounds)
+      [[0.5, 0.5], *[0.2, 0.5, 0.8].product([0.2, 0.5, 0.8])].uniq.map do |x, y|
+        Zaniah::Point.new(bounds.x + bounds.width * x, bounds.y + bounds.height * y)
+      end
+    end
+  end
+end

data/lib/syrma.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "zaniah"
+require_relative "syrma/version"
+require_relative "syrma/configuration"
+require_relative "syrma/errors"
+require_relative "syrma/internals"
+require_relative "syrma/instrumentation"
+require_relative "syrma/clock"
+require_relative "syrma/text_systems"
+require_relative "syrma/snapshot"
+require_relative "syrma/query"
+require_relative "syrma/event_log"
+require_relative "syrma/event_codec"
+require_relative "syrma/recorder"
+require_relative "syrma/window_driver"
+require_relative "syrma/popup_driver"
+require_relative "syrma/session"
+require_relative "syrma/visual/comparator"
+require_relative "syrma/visual/image"
+require_relative "syrma/snapshots/store"
+require_relative "syrma/snapshots/tree_format"
+require_relative "syrma/snapshots/terminal_format"
+require_relative "syrma/diagnostics"
+require_relative "syrma/codegen"
+require_relative "syrma/script_launcher"
+require_relative "syrma/report"
+
+module Syrma
+  class << self
+    attr_writer :configuration
+
+    def configuration = (@configuration ||= Configuration.new)
+    def configure = yield(configuration)
+    def reset_configuration! = self.configuration = Configuration.new
+  end
+end

data/sig/syrma.rbs

@@ -0,0 +1,266 @@
+module Syrma
+  VERSION: String
+
+  def self.configuration: () -> Configuration
+  def self.configuration=: (Configuration) -> Configuration
+  def self.configure: () { (Configuration) -> untyped } -> untyped
+  def self.reset_configuration!: () -> Configuration
+
+  class Configuration
+    attr_accessor timeout: Float
+    attr_accessor strict: bool
+    attr_accessor event_frames: Symbol
+    attr_accessor text: untyped
+    attr_accessor fonts: Array[String]
+    attr_accessor snapshot_dir: String
+    attr_accessor artifacts_dir: String
+    def initialize: () -> void
+  end
+
+  class Clock
+    def self.real_now: () -> Float
+    def initialize: () -> void
+    def call: () -> Float
+    def advance: (Numeric seconds) -> Float
+  end
+
+  class Error < StandardError
+  end
+  class UnstableUI < Error
+  end
+  class WaitTimeout < Error
+  end
+  class SnapshotMissing < Error
+  end
+  class SnapshotMismatch < Error
+  end
+  class UnsupportedBackend < Error
+  end
+  class ElementNotFound < Error
+    def initialize: (untyped locator, Tree tree) -> void
+  end
+  class AmbiguousMatch < Error
+    def initialize: (untyped locator, Array[Node] nodes) -> void
+  end
+  class NotActionable < Error
+    attr_reader reason: Symbol
+    def initialize: (Symbol reason, String message) -> void
+  end
+
+  class Node
+    attr_reader path: Array[Integer]
+    attr_reader element: untyped
+    attr_reader type: Symbol
+    attr_reader test_id: String?
+    attr_reader key: untyped
+    attr_reader text: String?
+    attr_reader color: untyped
+    attr_reader font_size: Numeric?
+    attr_reader bounds: untyped
+    attr_reader visible_bounds: untyped
+    attr_reader background: untyped
+    attr_reader border_color: untyped
+    attr_reader radius: untyped
+    attr_reader handlers: Array[Symbol]
+    attr_reader tooltip: String?
+    attr_reader children: Array[Node]
+    def visible?: () -> bool
+    def clickable?: () -> bool
+    def center: () -> untyped
+    def descendants: () -> Array[Node]
+    def content_text: () -> String
+    def ancestor_of?: (Node other) -> bool
+  end
+
+  class Tree
+    attr_reader frame: Integer
+    attr_reader size: untyped
+    attr_reader root: Node?
+    attr_reader nodes: Array[Node]
+    attr_reader hits: Array[untyped]
+    attr_reader text_runs: Array[untyped]
+    attr_reader menu: Array[String]?
+    attr_reader menu_index: Integer?
+    attr_reader tooltip: String?
+    def hit_at: (untyped point, ?event: Symbol, ?button: Symbol) -> Node?
+  end
+
+  class Criteria
+    def initialize: (Hash[Symbol, untyped] conditions, ?^(Node) -> bool predicate) -> void
+    def match?: (Node node) -> bool
+    def to_s: () -> String
+  end
+
+  class Locator
+    attr_reader driver: WindowDriver
+    attr_reader criteria: Criteria
+    attr_reader scope: Locator?
+    attr_reader index: Integer?
+    def find: (**untyped) ?{ (Node) -> bool } -> Locator
+    def nth: (Integer index) -> Locator
+    def first: () -> Locator
+    def last: () -> Locator
+    def candidates: (?Tree tree) -> Array[Node]
+    def resolve_all: (?Tree tree) -> Array[Node]
+    def resolve: (?Tree tree, ?strict: bool) -> Node
+    def count: () -> Integer
+    def exists?: () -> bool
+    def visible?: () -> bool
+    def text: () -> String
+    def click: (**untyped) -> untyped
+    def double_click: (**untyped) -> untyped
+    def hover: () -> untyped
+    def right_click: () -> untyped
+  end
+
+  class Event
+    attr_reader frame: Integer
+    attr_reader window: String
+    attr_reader input: untyped
+  end
+
+  class EventLog
+    include Enumerable[Event]
+    def initialize: (?limit: Integer) -> void
+    def each: () { (Event) -> void } -> untyped
+    def last: (?Integer count) -> (Event | Array[Event] | nil)
+    def add: (Integer frame, String window, untyped input) -> Event
+  end
+
+  class Session
+    attr_reader raster: Symbol
+    attr_reader strict: bool
+    attr_reader timeout: Float
+    attr_reader event_log: EventLog
+    attr_reader app: untyped
+    attr_reader event_frames: Symbol
+    attr_reader font_paths: Array[String]
+    attr_reader text_mode: untyped
+    attr_reader windows: Array[untyped]
+    attr_reader drivers: Array[WindowDriver]
+    def self.new: (**untyped) ?{ (untyped) -> untyped } -> Session
+    def self.attach: (untyped window, **untyped) -> Session
+    def self.for_app: (untyped app, **untyped) { (untyped) -> untyped } -> Session
+    def self.launch_script: (String path, ?argv: Array[String], **untyped) -> Session
+    def window: (?title: String?, ?index: Integer?) -> untyped
+    def driver: () -> WindowDriver
+    def session: () -> Session
+    def settle: () -> Session
+    def advance: (Numeric seconds) -> Session
+    def wait_for: (?untyped message, ?timeout: Numeric) { () -> untyped } -> untyped
+    def screenshot_pixels: (?WindowDriver target) -> String
+    def tui?: (?WindowDriver target) -> bool
+    def output_for: (?WindowDriver target) -> untyped
+    def exit_status: () -> Integer?
+    def close: () -> bool
+    def method_missing: (Symbol name, *untyped, **untyped) -> untyped
+  end
+
+  class WindowDriver
+    attr_reader window: untyped
+    attr_reader session: Session
+    def strict: () -> bool
+    def tree: () -> Tree
+    def find: (**untyped) ?{ (Node) -> bool } -> Locator
+    def all: (**untyped) ?{ (Node) -> bool } -> Array[Node]
+    def test_id: (String | Symbol id) -> Locator
+    def text: (String | Regexp value) -> Locator
+    def texts: () -> Array[String]
+    def tooltip: () -> String?
+    def button: (String label) -> Locator
+    def at: (untyped x, ?untyped y, ?event: Symbol, ?button: Symbol) -> Node?
+    def pixel: (Integer x, Integer y) -> Array[Integer]
+    def screenshot: (?String path) -> String
+    def terminal_lines: (?colors: bool) -> Array[String]
+    def click: (?untyped target, **untyped) -> untyped
+    def double_click: (untyped target, **untyped) -> untyped
+    def right_click: (untyped target, **untyped) -> untyped
+    def hover: (untyped target) -> untyped
+    def drag: (untyped from, untyped to, **untyped) -> untyped
+    def scroll: (untyped target, **untyped) -> untyped
+    def mouse_move: (untyped point, **untyped) -> untyped
+    def mouse_down: (untyped point, **untyped) -> untyped
+    def mouse_up: (untyped point, **untyped) -> untyped
+    def press: (*String keystrokes) -> untyped
+    def key_down: (String stroke, ?held: bool) -> untyped
+    def key_up: (String stroke) -> untyped
+    def type: (String text, ?key_events: bool) -> untyped
+    def paste: (String text) -> untyped
+    def compose: (String text, ?selection: untyped) -> untyped
+    def commit: (String text) -> untyped
+    def drop_files: (Array[String] paths, at: untyped) -> untyped
+    def resize: (Numeric width, Numeric height) -> untyped
+    def close: () -> untyped
+    def feed_terminal: (String bytes) -> untyped
+    def scroll_until: (untyped list, found: Hash[Symbol, untyped], ?step: Numeric, ?max: Integer) -> Locator
+    def menu: () -> PopupDriver
+  end
+
+  class PopupDriver
+    def open?: () -> bool
+    def items: () -> Array[String]
+    def selected: () -> String?
+    def dismiss: () -> untyped
+    def select: (String label, ?via: Symbol) -> untyped
+  end
+
+  class Comparator
+    class Result
+      attr_reader width: Integer
+      attr_reader height: Integer
+      attr_reader diff_pixels: Integer
+      attr_reader diff_image: String
+      def ratio: () -> Float
+    end
+    def initialize: (?threshold: Numeric) -> void
+    def compare: (Integer width, Integer height, String expected, String actual) -> Result
+  end
+
+  class Recorder
+    def initialize: (WindowDriver driver, IO output) -> void
+    def record: (untyped event) -> untyped
+    def close: () -> untyped
+  end
+
+  module EventCodec
+    def self.dump: (untyped event, t: Numeric, ?target: Hash[String, untyped]?) -> String
+    def self.load: (String line) -> untyped
+    def self.parse: (String line) -> Hash[String, untyped]
+  end
+
+  module Codegen
+    def self.generate: (Array[String] lines, ?framework: Symbol) -> String
+  end
+
+  module Report
+    def self.generate: (?root: String?, ?output: String?) -> String
+  end
+
+  class CLI
+    def self.run: (?Array[String] argv, ?out: IO, ?err: IO) -> Integer
+  end
+
+  class RakeTask
+    def initialize: () -> void
+  end
+
+  module Minitest
+    def zaniah_session: (**untyped) { (untyped) -> untyped } -> Session
+    def ui: () -> Session
+    def assert_ui_text: (String | Regexp expected, **untyped) -> bool
+    def refute_ui_text: (String | Regexp unexpected, **untyped) -> bool
+    def assert_element: (?untyped target, **untyped) -> bool
+    def refute_element: (?untyped target, **untyped) -> bool
+    def assert_visible: (?untyped target, **untyped) -> bool
+    def assert_hidden: (?untyped target, **untyped) -> bool
+    def assert_clickable: (?untyped target, **untyped) -> bool
+    def assert_bg: (untyped target, untyped color, **untyped) -> bool
+    def assert_pixel: (Integer x, Integer y, untyped color, **untyped) -> bool
+    def assert_tooltip: (String | Regexp expected, **untyped) -> bool
+    def assert_menu_items: (Array[String] labels, **untyped) -> bool
+    def assert_screenshot: (String name, **untyped) -> bool
+    def assert_tree_snapshot: (String name, **untyped) -> bool
+    def assert_terminal_snapshot: (String name, **untyped) -> bool
+    def assert_no_text_overlap: (**untyped) -> bool
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: syrma
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zaniah
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: 'Drive Zaniah windows headlessly: locate elements, send real input events,
+  and assert text, layout, pixels, and snapshots.'
+email:
+- t.yudai92@gmail.com
+executables:
+- syrma
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/syrma
+- lib/syrma.rb
+- lib/syrma/cli.rb
+- lib/syrma/clock.rb
+- lib/syrma/codegen.rb
+- lib/syrma/configuration.rb
+- lib/syrma/diagnostics.rb
+- lib/syrma/errors.rb
+- lib/syrma/event_codec.rb
+- lib/syrma/event_log.rb
+- lib/syrma/instrumentation.rb
+- lib/syrma/internals.rb
+- lib/syrma/minitest.rb
+- lib/syrma/popup_driver.rb
+- lib/syrma/query.rb
+- lib/syrma/rake_task.rb
+- lib/syrma/recorder.rb
+- lib/syrma/report.rb
+- lib/syrma/rspec.rb
+- lib/syrma/script_launcher.rb
+- lib/syrma/session.rb
+- lib/syrma/snapshot.rb
+- lib/syrma/snapshots/store.rb
+- lib/syrma/snapshots/terminal_format.rb
+- lib/syrma/snapshots/tree_format.rb
+- lib/syrma/text_systems.rb
+- lib/syrma/version.rb
+- lib/syrma/visual/comparator.rb
+- lib/syrma/visual/image.rb
+- lib/syrma/window_driver.rb
+- sig/syrma.rbs
+homepage: https://github.com/ydah/syrma
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ydah/syrma
+  changelog_uri: https://github.com/ydah/syrma/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: UI testing toolkit for applications built with Zaniah
+test_files: []