syrma 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9ef547e116ba3d928630699b7ae95646b0604108499429bc978bf31faa502bf
+  data.tar.gz: 01de9448ef8c33a18af96280ba15a993cf08be62292408de956aa8be78572a8c
+SHA512:
+  metadata.gz: 15af45c54231f18c6c10b7db2354a644bc206c584c515a169672ad562db43753f5753ececea2c829b04d418b83181c6689c0571be115dea91109425b74bc0342
+  data.tar.gz: 15c60ea282171fb9e17427769fd81b5510218590afb0126d51349bf16a73c5b5a58b9657fe0a27e3d1140a3fcfc3e70270c013c02445dbedc71ce0cbb93b2640

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-11
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# Syrma
+
+Syrma drives [Zaniah](https://github.com/noxdea/zaniah) GUI and TUI applications from Ruby tests. It locates rendered elements, sends input through Zaniah's real event path, waits for redraws, and compares text, trees, terminal output, pixels, and screenshots.
+
+## Installation
+
+Add Syrma to the test group in your `Gemfile`:
+
+```ruby
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "syrma"
+end
+```
+
+Then run `bundle install` and `bundle exec syrma doctor`.
+
+## Minimal test
+
+Keep window creation separate from the code that mounts your UI:
+
+```ruby
+module Counter
+  def self.mount(window)
+    count = 0
+    window.draw do
+      Zaniah::Div.new
+        .child(Zaniah::Text.new("Count: #{count}"))
+        .child(Zaniah::Div.new.test_id("increment").on_click { count += 1 })
+    end
+  end
+end
+```
+
+```ruby
+require "syrma/minitest"
+
+class CounterTest < Minitest::Test
+  include Syrma::Minitest
+
+  def setup
+    zaniah_session(width: 320, height: 200) { |window| Counter.mount(window) }
+  end
+
+  def test_increment
+    ui.find(test_id: "increment").click
+    assert_ui_text "Count: 1"
+  end
+end
+```
+
+`test_id` is provided by Zaniah 0.2 and is safe to use in application code.
+
+## API at a glance
+
+| Task | API |
+| --- | --- |
+| Locate | `find`, `all`, `test_id`, `text`, `button`, nested `find`, `nth`, `first`, `last` |
+| Pointer | `click`, `double_click`, `right_click`, `hover`, `drag`, `scroll` |
+| Keyboard/text | `press`, `type`, `paste`, `compose`, `commit` |
+| Window/input | `resize`, `close`, `drop_files`, `feed_terminal` |
+| Synchronize | `settle`, `wait_for`, `advance` |
+| Inspect | `tree`, `texts`, `at`, `pixel`, `screenshot`, `terminal_lines`, `menu`, `tooltip` |
+| Assert | text, element, visibility, clickability, background, pixel, tooltip, menu, tree/terminal/image snapshots |
+
+Locators are lazy: every operation resolves them against the latest rendered frame. Actions wait for visibility and an unobscured matching event handler, then send events through `Window#input`.
+
+## Snapshots and diagnostics
+
+```ruby
+assert_tree_snapshot "sidebar"
+assert_screenshot "saved", region: ui.test_id("panel"), mask: [ui.test_id("clock")]
+assert_terminal_snapshot "main"
+```
+
+New goldens are created locally and rejected on CI. Set `SYRMA_UPDATE_SNAPSHOTS=1` to update them. A failed UI test writes its screenshot, element tree, hit regions, text runs, recent events, and summary below `tmp/syrma`.
+
+```sh
+bundle exec syrma snapshots update
+bundle exec syrma snapshots prune --dry-run
+bundle exec syrma report
+```
+
+## Determinism and speed
+
+The default text renderer uses only Zaniah's bundled Abel font plus files passed in `fonts:`. Add a repository-owned font for non-Latin screenshot tests. `text: :none` is faster but does not draw glyphs.
+
+On Ruby 4.0 arm64 macOS, the included 101-element benchmark measured `event_frames: :gesture` at 3.1 ms per click/check with `text: :none` and 7.9 ms with deterministic text; Syrma's tree build plus locator resolution was about 0.28 ms. Run `bundle exec ruby -Ilib bench/click_bench.rb gesture` on the target CI host for relevant numbers.
+
+See [the guide](docs/guide.md) and [recipes](docs/recipes.md) for the full workflow.
+
+## Development
+
+```sh
+bundle exec rake
+bundle exec ruby -Ilib:test script/test_gesture.rb
+bundle exec rbs -I sig validate
+gem build --strict syrma.gemspec
+```
+
+Syrma supports Ruby 3.1+ and Zaniah `~> 0.2.0`. Virtual time is scoped to each session.
+
+## License
+
+Syrma is available under the [MIT License](LICENSE.txt).

data/exe/syrma

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "syrma/cli"
+
+exit Syrma::CLI.run

data/lib/syrma/cli.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require_relative "../syrma"
+
+module Syrma
+  class CLI
+    def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv.dup)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(arguments)
+      command = arguments.shift
+      case command
+      when "doctor" then doctor
+      when "snapshots" then snapshots(arguments)
+      when "report" then report(arguments)
+      when "record" then record(arguments)
+      when "codegen" then codegen(arguments)
+      when nil, "help", "--help", "-h" then help
+      else
+        @err.puts "Unknown command: #{command}"
+        help(@err)
+        1
+      end
+    rescue OptionParser::ParseError, ArgumentError, Error => error
+      @err.puts error.message
+      1
+    end
+
+    private
+
+    def doctor
+      checks = {
+        "Ruby" => "#{RUBY_VERSION} (#{RUBY_PLATFORM})",
+        "zaniah" => Zaniah::VERSION,
+        "Bundled font" => File.file?(Internals.bundled_font_path) ? Internals.bundled_font_path : nil,
+        "YJIT" => defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled? ? "enabled" : "disabled",
+        "External encoding" => Encoding.default_external.name
+      }
+      checks.each { |name, value| @out.puts format("%-14s %s", name, value || "NG") }
+      checks.values.all? ? 0 : 1
+    end
+
+    def snapshots(arguments)
+      subcommand = arguments.shift
+      case subcommand
+      when "update" then update_snapshots(arguments)
+      when "prune" then prune_snapshots(arguments)
+      else raise ArgumentError, "Usage: syrma snapshots update [test files] | prune [--dry-run]"
+      end
+    end
+
+    def update_snapshots(files)
+      Snapshots::Store.new.reset_usage!(full: files.empty?)
+      env = {"SYRMA_UPDATE_SNAPSHOTS" => "1"}
+      command = ["bundle", "exec", "rake", "test"]
+      command << "TEST=#{files.join(' ')}" unless files.empty?
+      system(env, *command) ? 0 : 1
+    end
+
+    def prune_snapshots(arguments)
+      dry_run = arguments.delete("--dry-run")
+      raise ArgumentError, "Unknown arguments: #{arguments.join(' ')}" unless arguments.empty?
+
+      files = Snapshots::Store.new.unused
+      files.each { |path| @out.puts(dry_run ? "would remove #{path}" : "removed #{path}") }
+      files.each { |path| FileUtils.rm_f(path) } unless dry_run
+      0
+    end
+
+    def report(arguments)
+      open_report = arguments.delete("--open")
+      raise ArgumentError, "Unknown arguments: #{arguments.join(' ')}" unless arguments.empty?
+
+      path = Report.generate
+      @out.puts path
+      open_path(path) if open_report
+      0
+    end
+
+    def record(arguments)
+      output = "recording.jsonl"
+      parser = OptionParser.new { |options| options.on("--out PATH") { |path| output = path } }
+      parser.parse!(arguments)
+      script = arguments.shift or raise ArgumentError, "Usage: syrma record SCRIPT [--out PATH]"
+      raise ArgumentError, "Unknown arguments: #{arguments.join(' ')}" unless arguments.empty?
+
+      sessions = []
+      recorders = []
+      File.open(output, "w", encoding: "UTF-8") do |file|
+        Instrumentation.install!
+        Instrumentation.capture_windows(backend: nil, on_open: lambda { |window|
+          session = Session.attach(window, text: :native, raster: :eager)
+          sessions << session
+          recorders << Recorder.new(session.driver, file)
+        }) { load(File.expand_path(script)) }
+      end
+      @out.puts output
+      0
+    ensure
+      recorders&.each(&:close)
+      sessions&.each(&:close)
+    end
+
+    def codegen(arguments)
+      framework = :minitest
+      parser = OptionParser.new { |options| options.on("--framework NAME") { |name| framework = name.to_sym } }
+      parser.parse!(arguments)
+      raise ArgumentError, "framework must be minitest or rspec" unless %i[minitest rspec].include?(framework)
+
+      path = arguments.shift or raise ArgumentError, "Usage: syrma codegen RECORDING [--framework minitest|rspec]"
+      raise ArgumentError, "Unknown arguments: #{arguments.join(' ')}" unless arguments.empty?
+
+      @out.write(Codegen.generate(File.readlines(path, encoding: "UTF-8"), framework: framework))
+      0
+    end
+
+    def open_path(path)
+      command = if RUBY_PLATFORM.include?("darwin")
+                  ["open", path]
+                elsif RUBY_PLATFORM.match?(/mswin|mingw/)
+                  ["cmd", "/c", "start", "", path]
+                else
+                  ["xdg-open", path]
+                end
+      system(*command)
+    end
+
+    def help(io = @out)
+      io.puts <<~HELP
+        Usage: syrma COMMAND
+          doctor
+          snapshots update [test files]
+          snapshots prune [--dry-run]
+          report [--open]
+          record SCRIPT [--out recording.jsonl]
+          codegen RECORDING [--framework minitest|rspec]
+      HELP
+      0
+    end
+  end
+end

data/lib/syrma/clock.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Syrma
+  class Clock
+    def self.real_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def initialize = @now = self.class.real_now
+    def call = @now
+
+    def advance(seconds)
+      raise ArgumentError, "time cannot be negative" unless seconds.is_a?(Numeric) && seconds >= 0
+
+      @now += seconds.to_f
+    end
+  end
+
+  class VirtualKeymap
+    def initialize(keymap, clock) = (@keymap, @clock = keymap, clock)
+
+    def dispatch(key, context: {})
+      @keymap.dispatch(key, context: context, now: @clock.call)
+    end
+  end
+end

data/lib/syrma/codegen.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Syrma
+  module Codegen
+    module_function
+
+    def generate(lines, framework: :minitest)
+      records = lines.filter_map { |line| EventCodec.parse(line) unless line.strip.empty? }
+      body = operations(records).map { |line| "    #{line}" }.join("\n")
+      framework == :rspec ? rspec(body) : minitest(body)
+    end
+
+    def operations(records)
+      output = []
+      text = +""
+      flush = -> { output << "ui.type(#{text.dump})" unless text.empty?; text.clear }
+      records.each_with_index do |record, index|
+        if record["type"] == "TextInput"
+          text << record.fetch("fields").fetch("text")
+          next
+        end
+        next if record["type"] == "KeyUp" || typing_key?(records, index)
+
+        flush.call
+        operation = operation(record)
+        output << operation if operation
+      end
+      flush.call
+      output << "# TODO: add assertions"
+    end
+
+    def operation(record)
+      fields = record.fetch("fields")
+      case record["type"]
+      when "MouseDown"
+        target = locator(record["target"], fields.fetch("position"))
+        return fields["button"].to_s == "right" ? "#{target}.right_click" : "#{target}.click" if target
+
+        point = fields.fetch("position")
+        method = fields["button"].to_s == "right" ? "right_click" : "click"
+        "ui.#{method}([#{point.fetch('x')}, #{point.fetch('y')}])"
+      when "KeyDown" then "ui.press(#{fields.fetch('keystroke').dump})"
+      when "ScrollWheel"
+        point = fields.fetch("position")
+        delta = fields.fetch("delta")
+        "ui.scroll([#{point.fetch('x')}, #{point.fetch('y')}], dx: #{delta.fetch('x')}, dy: #{delta.fetch('y')})"
+      when "Composition" then "ui.compose(#{fields.fetch('text').dump}, selection: #{fields['selection'].inspect})"
+      when "FileDrop"
+        point = fields.fetch("position")
+        "ui.drop_files(#{fields.fetch('paths').inspect}, at: [#{point.fetch('x')}, #{point.fetch('y')}])"
+      end
+    end
+
+    def locator(target, point)
+      return "ui.find(test_id: #{target['test_id'].dump})" if target&.fetch("test_id", nil)
+      return "ui.button(#{target['text'].dump})" if target&.fetch("text", nil)&.then { |text| !text.empty? }
+
+      nil
+    end
+
+    def typing_key?(records, index)
+      records[index]["type"] == "KeyDown" && records[index + 1]&.fetch("type") == "TextInput"
+    end
+
+    def minitest(body)
+      <<~RUBY
+        require "syrma/minitest"
+
+        class RecordedUiTest < Minitest::Test
+          include Syrma::Minitest
+
+          def test_recorded_flow
+        #{body}
+          end
+        end
+      RUBY
+    end
+
+    def rspec(body)
+      <<~RUBY
+        require "syrma/rspec"
+
+        RSpec.describe "recorded UI", type: :zaniah do
+          it "replays the flow" do
+        #{body}
+          end
+        end
+      RUBY
+    end
+  end
+end

data/lib/syrma/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Syrma
+  class Configuration
+    attr_accessor :timeout, :strict, :event_frames, :text, :fonts, :snapshot_dir, :artifacts_dir
+
+    def initialize
+      @timeout = 2.0
+      @strict = true
+      @event_frames = :each
+      @text = :deterministic
+      @fonts = []
+      @snapshot_dir = "test/syrma_snapshots"
+      @artifacts_dir = "tmp/syrma"
+    end
+  end
+end

data/lib/syrma/diagnostics.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Syrma
+  module Diagnostics
+    module_function
+
+    def dir_for(test_class, test_name)
+      root = ENV["SYRMA_ARTIFACTS"] || Syrma.configuration.artifacts_dir
+      File.join(root, sanitize(test_class), sanitize(test_name))
+    end
+
+    def write(session, dir, message: nil)
+      FileUtils.mkdir_p(dir)
+      tree = session.tree
+      size = session.window.content_size
+      Zaniah::PNG.write(File.join(dir, "screenshot.png"), size.width.to_i, size.height.to_i, session.screenshot_pixels)
+      File.write(File.join(dir, "tree.txt"), tree.root ? TreeFormat.dump(tree.root) : "(nothing rendered)\n", encoding: "UTF-8")
+      File.write(File.join(dir, "hits.txt"), hits(tree), encoding: "UTF-8")
+      File.write(File.join(dir, "text_runs.txt"), text_runs(tree), encoding: "UTF-8")
+      File.write(File.join(dir, "events.log"), events(session), encoding: "UTF-8")
+      File.write(File.join(dir, "terminal.txt"), session.terminal_lines.join("\n") + "\n", encoding: "UTF-8") if session.tui?
+      File.write(File.join(dir, "summary.md"), summary(session, dir, message, tree, size), encoding: "UTF-8")
+      dir
+    rescue StandardError => error
+      warn "syrma: failed to write diagnostics: #{error.class}: #{error.message}"
+      nil
+    end
+
+    def sanitize(value) = value.to_s.gsub(/[^A-Za-z0-9_-]/, "_")
+
+    def hits(tree)
+      tree.hits.each_with_index.map do |(bounds, node), index|
+        "#{index}: [#{bounds.x},#{bounds.y} #{bounds.width}x#{bounds.height}] #{node ? node.inspect : '(unknown)'}"
+      end.join("\n") + "\n"
+    end
+
+    def text_runs(tree)
+      tree.text_runs.map { |x, y, text, color| "#{x},#{y} #{color} #{text.inspect}" }.join("\n") + "\n"
+    end
+
+    def events(session)
+      session.event_log.last(100).map do |event|
+        "frame=#{event.frame} window=#{event.window.inspect} #{event.input.inspect}"
+      end.join("\n") + "\n"
+    end
+
+    def summary(_session, dir, message, tree, size)
+      links = %w[screenshot.png tree.txt hits.txt text_runs.txt events.log terminal.txt expected.png actual.png diff.png]
+        .select { |name| File.exist?(File.join(dir, name)) }
+        .map { |name| "[#{name}](#{name})" }.join(" / ")
+      <<~MARKDOWN
+        # #{File.basename(dir)}
+
+        #{message}
+
+        - zaniah #{Zaniah::VERSION} / Ruby #{RUBY_VERSION} / #{RUBY_PLATFORM}
+        - window #{size.width}x#{size.height}, frame #{tree.frame}
+        - #{links}
+      MARKDOWN
+    end
+  end
+end

data/lib/syrma/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Syrma
+  class Error < Zaniah::Error; 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(locator, tree)
+      texts = tree.text_runs.map { |run| run[2] }.uniq.first(10)
+      super("Element not found: #{locator}\n  Visible text: #{texts.inspect}")
+    end
+  end
+
+  class AmbiguousMatch < Error
+    def initialize(locator, nodes)
+      super("Matched #{nodes.length} elements: #{locator}\n  " +
+            nodes.first(5).map(&:inspect).join("\n  ") + "\n  Refine with nth, first, or within")
+    end
+  end
+
+  class NotActionable < Error
+    attr_reader :reason
+
+    def initialize(reason, message)
+      @reason = reason
+      super(message)
+    end
+  end
+end

data/lib/syrma/event_codec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Syrma
+  module EventCodec
+    I = Zaniah::Input
+    TYPES = {
+      "MouseDown" => I::MouseDown,
+      "MouseUp" => I::MouseUp,
+      "MouseMove" => I::MouseMove,
+      "ScrollWheel" => I::ScrollWheel,
+      "KeyDown" => I::KeyDown,
+      "KeyUp" => I::KeyUp,
+      "TextInput" => I::TextInput,
+      "Composition" => I::Composition,
+      "FileDrop" => I::FileDrop
+    }.freeze
+    SYMBOLS = %i[button phase].freeze
+
+    module_function
+
+    def dump(event, t:, target: nil)
+      type = TYPES.key(event.class) or raise ArgumentError, "Unsupported event: #{event.class}"
+      fields = event.to_h.transform_values { |value| encode(value) }
+      JSON.generate({"t" => Float(t), "type" => type, "fields" => fields}.tap { |record| record["target"] = target if target })
+    end
+
+    def load(line)
+      data = parse(line)
+      klass = TYPES.fetch(data["type"]) { raise ArgumentError, "Unknown event type: #{data['type'].inspect}" }
+      fields = data.fetch("fields")
+      values = klass.members.map do |member|
+        value = decode(fields.fetch(member.to_s))
+        SYMBOLS.include?(member) && value ? value.to_s.to_sym : value
+      end
+      klass.new(*values)
+    end
+
+    def parse(line)
+      data = JSON.parse(line)
+      raise ArgumentError, "Recording must be a JSON object" unless data.is_a?(Hash)
+      raise ArgumentError, "Unknown event type: #{data['type'].inspect}" unless TYPES.key?(data["type"])
+      raise ArgumentError, "Missing fields" unless data["fields"].is_a?(Hash)
+
+      data
+    rescue JSON::ParserError => error
+      raise ArgumentError, "Invalid JSON: #{error.message}"
+    end
+
+    def encode(value)
+      return {"x" => value.x, "y" => value.y} if value.is_a?(Zaniah::Point)
+
+      value
+    end
+
+    def decode(value)
+      return Zaniah::Point.new(value.fetch("x"), value.fetch("y")) if value.is_a?(Hash) && value.keys.sort == %w[x y]
+
+      value
+    end
+  end
+end

data/lib/syrma/event_log.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Syrma
+  Event = Data.define(:frame, :window, :input)
+
+  class EventLog
+    include Enumerable
+
+    def initialize(limit: 100)
+      @limit = limit
+      @events = []
+    end
+
+    def each(&block) = @events.each(&block)
+    def last(count = nil) = count ? @events.last(count) : @events.last
+
+    def add(frame, window, input)
+      @events.shift if @events.length >= @limit
+      @events << Event.new(frame: frame, window: window, input: input)
+    end
+  end
+end