syrma 0.1.0

data/lib/syrma/instrumentation.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Syrma
+  module Instrumentation
+    Capture = Struct.new(:backend, :windows, :on_open, keyword_init: true)
+
+    module WindowCapture
+      attr_reader :testing_root, :testing_clear, :testing_frame
+      attr_accessor :testing_lazy_raster
+
+      def on_frame(&callback)
+        @testing_on_frame = callback
+        super do |element, clear|
+          @testing_root = element
+          @testing_clear = clear
+          @testing_frame = (@testing_frame || 0) + 1
+          @testing_on_frame&.call(element, clear)
+        end
+      end
+
+      def input(event)
+        testing_recorder&.record(event)
+        super
+      end
+
+      def testing_recorder = @testing_recorder
+
+      def testing_recorder=(recorder)
+        @testing_recorder = recorder
+      end
+
+      def render(element, present: true, **options)
+        super(element, present: present && !testing_lazy_raster, **options)
+      end
+    end
+
+    module BackendOverride
+      def open_window(backend: :headless, **options)
+        capture = Thread.current[:syrma_window_capture]
+        return super unless capture
+
+        window = if capture.backend
+                   allowed = options.slice(:width, :height, :title, :scale_factor, :input, :output, :keymap, :clock)
+                   super(backend: capture.backend, **allowed)
+                 else
+                   super
+                 end
+        capture.windows << window
+        capture.on_open&.call(window)
+        window
+      end
+    end
+
+    class << self
+      def install!
+        return if @installed
+
+        Zaniah::Platform.singleton_class.prepend(BackendOverride)
+        @installed = true
+      end
+
+      def capture_windows(backend: :headless, on_open: nil)
+        previous = Thread.current[:syrma_window_capture]
+        capture = Capture.new(backend: backend, windows: [], on_open: on_open)
+        Thread.current[:syrma_window_capture] = capture
+        yield
+        capture.windows
+      ensure
+        Thread.current[:syrma_window_capture] = previous
+      end
+
+      def capture(window, lazy_raster:)
+        window.extend(WindowCapture) unless window.is_a?(WindowCapture)
+        window.testing_lazy_raster = lazy_raster
+        window.on_frame
+        window
+      end
+    end
+  end
+end

data/lib/syrma/internals.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Syrma
+  module Internals
+    module_function
+
+    def style(element) = element.instance_variable_get(:@style) || {}
+    def background(element) = element.instance_variable_get(:@background)
+    def border_color(element) = element.instance_variable_get(:@border_color)
+    def radius(element) = element.instance_variable_get(:@radius)
+    def tooltip(element) = element.instance_variable_get(:@tooltip)
+    def context_menu(element) = element.instance_variable_get(:@context_menu)
+    def key(element) = element.instance_variable_get(:@key)
+    def shown_tooltip(window)
+      tip = window.instance_variable_get(:@tooltip)
+      tip && tip[:shown] ? tip[:text] : nil
+    end
+
+    def bundled_font_path
+      _, entry = $LOAD_PATH.resolve_feature_path("zaniah")
+      File.expand_path("../assets/fonts/Abel-Regular.ttf", File.dirname(entry))
+    end
+
+    def executor_idle?(executor) = executor.instance_variable_get(:@foreground).empty?
+  end
+end

data/lib/syrma/minitest.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "../syrma"
+
+module Syrma
+  module Minitest
+    def zaniah_session(**options, &mount)
+      (@zaniah_sessions ||= []) << Session.new(**options, &mount)
+      @zaniah_sessions.last
+    end
+
+    def ui = @zaniah_sessions&.last || raise(Error, "call zaniah_session first")
+
+    def assert_ui_text(expected, session: ui, timeout: session.timeout)
+      ui_eventually(session, timeout, -> { "Expected text #{expected.inspect} to appear (current: #{session.texts.inspect})" }) do
+        session.texts.any? { |text| text_match?(text, expected) }
+      end
+    end
+
+    def refute_ui_text(unexpected, session: ui, timeout: session.timeout)
+      ui_eventually(session, timeout, -> { "Expected text #{unexpected.inspect} to disappear" }) do
+        session.texts.none? { |text| text_match?(text, unexpected) }
+      end
+    end
+
+    def assert_element(target = nil, count: nil, session: ui, **criteria)
+      target = criteria unless criteria.empty?
+      locator = locator_for(target, session)
+      if count
+        ui_eventually(session, session.timeout, -> { "Expected #{count} matches for #{locator} (current: #{locator.count})" }) do
+          locator.count == count
+        end
+      else
+        ui_eventually(session, session.timeout, -> { "Could not find #{locator}" }) { locator.exists? }
+      end
+    end
+
+    def refute_element(target = nil, session: ui, **criteria)
+      target = criteria unless criteria.empty?
+      locator = locator_for(target, session)
+      ui_eventually(session, session.timeout, -> { "Expected #{locator} to disappear" }) { !locator.exists? }
+    end
+
+    def assert_visible(target = nil, session: ui, **criteria)
+      target = criteria unless criteria.empty?
+      locator = locator_for(target, session)
+      ui_eventually(session, session.timeout, -> { "Expected #{locator} to be visible" }) { locator.visible? }
+    end
+
+    def assert_hidden(target = nil, session: ui, **criteria)
+      target = criteria unless criteria.empty?
+      locator = locator_for(target, session)
+      ui_eventually(session, session.timeout, -> { "Expected #{locator} to be hidden" }) { !locator.visible? }
+    end
+
+    def assert_clickable(target = nil, session: ui, **criteria)
+      target = criteria unless criteria.empty?
+      locator = locator_for(target, session)
+      reason = nil
+      ui_eventually(session, session.timeout, -> { "#{locator} is not clickable: #{reason}" }) do
+        node = locator.resolve
+        session.driver.__send__(:check_actionable, session.tree, node, :mouse_down, :left)
+      rescue ElementNotFound, NotActionable => error
+        reason = error.message
+        false
+      end
+    end
+
+    def assert_bg(target, color, session: ui)
+      locator = locator_for(target, session)
+      ui_eventually(session, session.timeout, -> { "Expected #{locator} background to be #{color.inspect}" }) do
+        locator.resolve_all.any? { |node| Criteria.new(bg: color).match?(node) }
+      end
+    end
+
+    def assert_pixel(x, y, color, threshold: 2, session: ui)
+      expected = Zaniah::Color.parse(color).to_a.map { |channel| (channel * 255).round }
+      actual = nil
+      ui_eventually(session, session.timeout, -> { "Expected pixel (#{x}, #{y}) to be #{color.inspect} (current: #{actual.inspect})" }) do
+        actual = session.pixel(x, y)
+        actual.zip(expected).all? { |left, right| (left - right).abs <= threshold }
+      end
+    end
+
+    def assert_tooltip(expected, session: ui)
+      ui_eventually(session, session.timeout, -> { "Expected tooltip #{expected.inspect} (current: #{session.tooltip.inspect})" }) do
+        text_match?(session.tooltip, expected)
+      end
+    end
+
+    def assert_menu_items(labels, session: ui)
+      ui_eventually(session, session.timeout, -> { "Expected menu items #{labels.inspect} (current: #{session.menu.items.inspect})" }) do
+        session.menu.items == labels
+      end
+    end
+
+    def assert_screenshot(name, session: ui, **options)
+      warn "syrma: text: :none does not render text in images" if session.text_mode == :none
+      store = Snapshots::Store.new
+      path = snapshot_path(store, name, "png")
+      status = Visual.check_screenshot(session, store: store, path: path,
+                                       artifacts: Diagnostics.dir_for(self.class.name, self.name), **options)
+      warn_snapshot(status, path)
+      pass
+    rescue SnapshotMismatch, SnapshotMissing => error
+      flunk error.message
+    end
+
+    def assert_tree_snapshot(name, root: nil, attributes: TreeFormat::DEFAULT, session: ui)
+      node = root ? (root.is_a?(Locator) ? root.resolve : root) : session.tree.root
+      assert_text_snapshot(name, "tree.txt", TreeFormat.dump(node, attributes: attributes))
+    end
+
+    def assert_terminal_snapshot(name, colors: false, session: ui)
+      assert_text_snapshot(name, "term.txt", session.terminal_lines(colors: colors).join("\n") + "\n")
+    end
+
+    def assert_no_text_overlap(session: ui)
+      overlaps = TerminalFormat.overlaps(session.tree.text_runs)
+      assert_empty overlaps, "Terminal text overlaps: #{overlaps.map { |a, b, row| "#{a.inspect} / #{b.inspect} (row #{row})" }.join(', ')}"
+    end
+
+    def after_teardown
+      unless passed? || skipped?
+        @zaniah_sessions&.each_with_index do |session, index|
+          suffix = index.zero? ? "" : "-#{index}"
+          Diagnostics.write(session, Diagnostics.dir_for(self.class.name, "#{name}#{suffix}"),
+                            message: failures.map(&:message).join("\n\n"))
+        end
+      end
+      @zaniah_sessions&.each(&:close)
+      @zaniah_sessions = nil
+      super
+    end
+
+    private
+
+    def locator_for(target, session)
+      return session.find(**target) if target.is_a?(Hash)
+
+      target
+    end
+
+    def text_match?(actual, expected)
+      return false if actual.nil?
+
+      expected.is_a?(Regexp) ? expected.match?(actual) : actual == expected
+    end
+
+    def ui_eventually(session, timeout, message, &condition)
+      session.wait_for(message, timeout: timeout, &condition)
+      pass
+    rescue WaitTimeout => error
+      flunk error.message
+    end
+
+    def snapshot_path(store, name, extension)
+      test_file = self.class.instance_method(self.name.to_sym).source_location&.first || "unknown"
+      store.path(test_file: test_file, test_class: self.class.name, name: name, ext: extension)
+    end
+
+    def assert_text_snapshot(name, extension, actual)
+      store = Snapshots::Store.new
+      path = snapshot_path(store, name, extension)
+      if !File.exist?(path) || store.update?
+        existed = File.exist?(path)
+        flunk "Snapshot not found: #{path}" if !File.exist?(path) && store.ci? && !store.update?
+
+        store.write(path, actual)
+        warn_snapshot(existed ? :updated : :created, path)
+        return pass
+      end
+      assert_equal File.read(path, encoding: "UTF-8"), actual, "Snapshot mismatch: #{path}"
+    end
+
+    def warn_snapshot(status, path)
+      return if status == :matched
+
+      warn "syrma: #{status == :created ? 'created' : 'updated'} snapshot: #{path}"
+    end
+  end
+end

data/lib/syrma/popup_driver.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Syrma
+  class PopupDriver
+    def initialize(driver) = @driver = driver
+    def open? = !@driver.tree.menu.nil?
+    def items = @driver.tree.menu || []
+    def selected = open? ? items[@driver.tree.menu_index] : nil
+    def dismiss = @driver.press("esc")
+
+    def select(label, via: :keyboard)
+      index = items.index(label) or raise Error, "Menu item not found: #{label.inspect} (#{items.inspect})"
+      unless @driver.window.popup.enabled[index]
+        raise NotActionable.new(:disabled, "Menu item #{label.inspect} is disabled")
+      end
+
+      via == :mouse ? select_by_mouse(index) : select_by_keyboard(index)
+    end
+
+    private
+
+    def select_by_keyboard(index)
+      items.length.times do
+        break if @driver.tree.menu_index == index
+
+        @driver.press("down")
+      end
+      @driver.press("enter")
+    end
+
+    def select_by_mouse(index)
+      bounds = @driver.window.popup.bounds
+      y = bounds.y + bounds.height.fdiv(items.length) * (index + 0.5)
+      @driver.mouse_down(Zaniah::Point.new(bounds.x + bounds.width / 2.0, y))
+    end
+  end
+end

data/lib/syrma/query.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Syrma
+  class Criteria
+    KEYS = %i[test_id key text has_text type clickable handler tooltip visible bg].freeze
+
+    def initialize(conditions, predicate = nil)
+      unknown = conditions.keys - KEYS
+      raise ArgumentError, "Unknown search criteria: #{unknown.join(', ')}" unless unknown.empty?
+
+      @conditions = conditions.freeze
+      @predicate = predicate
+    end
+
+    def match?(node)
+      @conditions.all? { |name, expected| __send__(:"match_#{name}", node, expected) } &&
+        (@predicate.nil? || @predicate.call(node))
+    end
+
+    def to_s = @conditions.map { |key, value| "#{key}: #{value.inspect}" }.join(", ") + (@predicate ? " + block" : "")
+
+    private
+
+    def text_match(actual, expected)
+      return false if actual.nil?
+
+      expected.is_a?(Regexp) ? expected.match?(actual) : actual == expected
+    end
+
+    def match_test_id(node, value) = node.test_id == value.to_s
+    def match_key(node, value) = node.key == value
+    def match_text(node, value) = text_match(node.text, value)
+    def match_has_text(node, value) = value.is_a?(Regexp) ? value.match?(node.content_text) : node.content_text.include?(value)
+    def match_type(node, value) = value.is_a?(Class) ? node.element.is_a?(value) : node.type == value
+    def match_clickable(node, value) = node.clickable? == value
+    def match_handler(node, value) = node.handlers.include?(value)
+    def match_tooltip(node, value) = text_match(node.tooltip, value)
+    def match_visible(node, value) = node.visible? == value
+    def match_bg(node, value) = !node.background.nil? && Zaniah::Color.parse(node.background).to_a == Zaniah::Color.parse(value).to_a
+  end
+
+  class Locator
+    attr_reader :driver, :criteria, :scope, :index
+
+    def initialize(driver, criteria, scope: nil, index: nil)
+      @driver = driver
+      @criteria = criteria
+      @scope = scope
+      @index = index
+    end
+
+    def find(**conditions, &predicate) = Locator.new(driver, Criteria.new(conditions, predicate), scope: self)
+    def nth(index) = Locator.new(driver, criteria, scope: scope, index: index)
+    def first = nth(0)
+    def last = nth(-1)
+
+    def candidates(tree = driver.tree)
+      pool = scope ? scope.resolve_all(tree).flat_map(&:descendants) : tree.nodes
+      pool.select { |node| criteria.match?(node) }
+    end
+
+    def resolve_all(tree = driver.tree)
+      found = candidates(tree)
+      index.nil? ? found : [found[index]].compact
+    end
+
+    def resolve(tree = driver.tree, strict: driver.strict)
+      found = resolve_all(tree)
+      raise ElementNotFound.new(self, tree) if found.empty?
+      raise AmbiguousMatch.new(self, found) if strict && found.length > 1
+
+      found.first
+    end
+
+    def count = resolve_all.length
+    def exists? = count.positive?
+    def visible? = resolve_all.any?(&:visible?)
+    def text = resolve.content_text
+    def click(**options) = driver.click(self, **options)
+    def double_click(**options) = driver.double_click(self, **options)
+    def hover = driver.hover(self)
+    def right_click = driver.right_click(self)
+    def to_s = "#{scope ? "#{scope} >> " : ''}find(#{criteria})#{index.nil? ? '' : "[#{index}]"}"
+  end
+end

data/lib/syrma/rake_task.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rake"
+require_relative "cli"
+
+module Syrma
+  class RakeTask
+    include Rake::DSL
+
+    def initialize
+      namespace :syrma do
+        desc "Check the Syrma and Zaniah environment"
+        task(:doctor) { abort unless CLI.run(["doctor"]).zero? }
+
+        namespace :snapshots do
+          desc "Update snapshot goldens"
+          task(:update) { abort unless CLI.run(["snapshots", "update"]).zero? }
+
+          desc "Prune unused snapshot goldens"
+          task(:prune) { abort unless CLI.run(["snapshots", "prune"]).zero? }
+        end
+
+        desc "Build an HTML failure report"
+        task(:report) { abort unless CLI.run(["report"]).zero? }
+      end
+    end
+  end
+end

data/lib/syrma/recorder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Syrma
+  class Recorder
+    def initialize(driver, output)
+      @driver = driver
+      @output = output
+      @started_at = Clock.real_now
+      driver.window.testing_recorder = self
+    end
+
+    def record(event)
+      target = target_for(event)
+      @output.puts(EventCodec.dump(event, t: Clock.real_now - @started_at, target: target))
+      @output.flush if @output.respond_to?(:flush)
+    end
+
+    def close
+      @driver.window.testing_recorder = nil if @driver.window.testing_recorder.equal?(self)
+    end
+
+    private
+
+    def target_for(event)
+      return unless event.is_a?(Zaniah::Input::MouseDown)
+
+      node = @driver.at(event.position, event: :mouse_down, button: event.button)
+      return unless node
+
+      {"test_id" => node.test_id, "text" => node.content_text}.compact
+    rescue Error
+      nil
+    end
+  end
+end

data/lib/syrma/report.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "pathname"
+
+module Syrma
+  module Report
+    module_function
+
+    def generate(root: nil, output: nil)
+      root = File.expand_path(root || ENV["SYRMA_ARTIFACTS"] || Syrma.configuration.artifacts_dir)
+      output ||= File.join(root, "report.html")
+      summaries = Dir[File.join(root, "**", "summary.md")].sort
+      FileUtils.mkdir_p(File.dirname(output))
+      File.write(output, html(root, summaries), encoding: "UTF-8")
+      output
+    end
+
+    def html(root, summaries)
+      sections = summaries.map { |path| section(root, path) }.join
+      sections = "<p>No failures recorded.</p>" if sections.empty?
+      <<~HTML
+        <!doctype html>
+        <html lang="ja">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width,initial-scale=1">
+          <title>Syrma test report</title>
+          <style>body{font:14px system-ui;max-width:1200px;margin:auto;padding:24px;color:#18202a}section{border-top:1px solid #ccd4dd;padding:20px 0}.images{display:flex;gap:12px;overflow:auto}.images figure{margin:0}.images img{max-width:360px;border:1px solid #ccd4dd}pre{white-space:pre-wrap;background:#f4f6f8;padding:12px}</style>
+        </head>
+        <body><h1>Syrma test report</h1>#{sections}</body>
+        </html>
+      HTML
+    end
+
+    def section(root, summary_path)
+      dir = File.dirname(summary_path)
+      title = File.basename(dir)
+      summary = ERB::Util.html_escape(File.read(summary_path, encoding: "UTF-8"))
+      images = %w[expected.png actual.png diff.png screenshot.png].filter_map do |name|
+        path = File.join(dir, name)
+        next unless File.exist?(path)
+
+        relative = Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
+        "<figure><figcaption>#{name}</figcaption><img src=\"#{ERB::Util.html_escape(relative)}\" alt=\"#{name}\"></figure>"
+      end.join
+      details = %w[tree.txt events.log].filter_map do |name|
+        path = File.join(dir, name)
+        next unless File.exist?(path)
+
+        "<details><summary>#{name}</summary><pre>#{ERB::Util.html_escape(File.read(path, encoding: 'UTF-8'))}</pre></details>"
+      end.join
+      "<section><h2>#{ERB::Util.html_escape(title)}</h2><pre>#{summary}</pre><div class=\"images\">#{images}</div>#{details}</section>"
+    end
+  end
+end

data/lib/syrma/rspec.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+require_relative "../syrma"
+
+module Syrma
+  module RSpec
+    module Helpers
+      def zaniah_session(**options, &mount)
+        (@zaniah_sessions ||= []) << Session.new(**options, &mount)
+        @zaniah_sessions.last
+      end
+
+      def ui = @zaniah_sessions&.last || raise(Error, "call zaniah_session first")
+      def zaniah_sessions = @zaniah_sessions || []
+    end
+
+    class << self
+      def eventually(session, timeout: session.timeout)
+        session.wait_for(timeout: timeout) { yield }
+        true
+      rescue WaitTimeout
+        false
+      end
+
+      def snapshot_path(name, extension)
+        example = ::RSpec.current_example
+        Snapshots::Store.new.path(test_file: example.file_path, test_class: example.example_group.description,
+                                  name: name, ext: extension)
+      end
+
+      def text_snapshot(name, extension, actual)
+        store = Snapshots::Store.new
+        path = snapshot_path(name, extension)
+        if !File.exist?(path) || store.update?
+          raise SnapshotMissing, "Snapshot not found: #{path}" if !File.exist?(path) && store.ci? && !store.update?
+
+          store.write(path, actual)
+          return true
+        end
+        File.read(path, encoding: "UTF-8") == actual
+      end
+    end
+
+    ::RSpec::Matchers.define :have_ui_text do |expected|
+      match do |session|
+        RSpec.eventually(session) { session.texts.any? { |text| expected.is_a?(Regexp) ? expected.match?(text) : text == expected } }
+      end
+      match_when_negated do |session|
+        RSpec.eventually(session) { session.texts.none? { |text| expected.is_a?(Regexp) ? expected.match?(text) : text == expected } }
+      end
+      failure_message { |session| "Expected text #{expected.inspect} to appear (current: #{session.texts.inspect})" }
+      failure_message_when_negated { "Expected text #{expected.inspect} to disappear" }
+    end
+
+    ::RSpec::Matchers.define :have_element do |**criteria|
+      match { |session| RSpec.eventually(session) { session.find(**criteria).exists? } }
+      match_when_negated { |session| RSpec.eventually(session) { !session.find(**criteria).exists? } }
+      failure_message { "Element not found: find(#{Criteria.new(criteria)})" }
+    end
+
+    ::RSpec::Matchers.define :be_visible do
+      match { |locator| RSpec.eventually(locator.driver.session) { locator.visible? } }
+      failure_message { |locator| "#{locator} is not visible" }
+    end
+
+    ::RSpec::Matchers.define :be_clickable do
+      match do |locator|
+        RSpec.eventually(locator.driver.session) do
+          node = locator.resolve
+          locator.driver.__send__(:check_actionable, locator.driver.tree, node, :mouse_down, :left)
+        rescue ElementNotFound, NotActionable => error
+          @reason = error.message
+          false
+        end
+      end
+      failure_message { |locator| "#{locator} is not clickable: #{@reason}" }
+    end
+
+    ::RSpec::Matchers.define :have_bg do |color|
+      match { |locator| RSpec.eventually(locator.driver.session) { locator.resolve_all.any? { |node| Criteria.new(bg: color).match?(node) } } }
+      failure_message { |locator| "Expected #{locator} background to be #{color.inspect}" }
+    end
+
+    ::RSpec::Matchers.define :have_pixel do |x, y, color, threshold: 2|
+      match do |session|
+        expected = Zaniah::Color.parse(color).to_a.map { |channel| (channel * 255).round }
+        RSpec.eventually(session) do
+          session.pixel(x, y).zip(expected).all? { |left, right| (left - right).abs <= threshold }
+        end
+      end
+      failure_message { "Expected pixel (#{x}, #{y}) to be #{color.inspect}" }
+    end
+
+    ::RSpec::Matchers.define :have_tooltip do |text|
+      match { |session| RSpec.eventually(session) { session.tooltip == text } }
+      failure_message { |session| "Expected tooltip #{text.inspect} (current: #{session.tooltip.inspect})" }
+    end
+
+    ::RSpec::Matchers.define :have_menu_items do |labels|
+      match { |session| RSpec.eventually(session) { session.menu.items == labels } }
+      failure_message { |session| "Expected menu items #{labels.inspect} (current: #{session.menu.items.inspect})" }
+    end
+
+    ::RSpec::Matchers.define :match_screenshot do |name, **options|
+      match do |session|
+        store = Snapshots::Store.new
+        path = RSpec.snapshot_path(name, "png")
+        example = ::RSpec.current_example
+        Visual.check_screenshot(session, store: store, path: path,
+                                artifacts: Diagnostics.dir_for("RSpec", "#{example.full_description}-0"), **options)
+        true
+      rescue SnapshotMismatch, SnapshotMissing => error
+        @reason = error.message
+        false
+      end
+      failure_message { @reason }
+    end
+
+    ::RSpec::Matchers.define :match_tree_snapshot do |name, root: nil, attributes: TreeFormat::DEFAULT|
+      match do |session|
+        node = root ? (root.is_a?(Locator) ? root.resolve : root) : session.tree.root
+        RSpec.text_snapshot(name, "tree.txt", TreeFormat.dump(node, attributes: attributes))
+      rescue SnapshotMissing => error
+        @reason = error.message
+        false
+      end
+      failure_message { @reason || "Tree snapshot mismatch" }
+    end
+
+    ::RSpec::Matchers.define :match_terminal_snapshot do |name, colors: false|
+      match do |session|
+        RSpec.text_snapshot(name, "term.txt", session.terminal_lines(colors: colors).join("\n") + "\n")
+      rescue SnapshotMissing => error
+        @reason = error.message
+        false
+      end
+      failure_message { @reason || "Terminal snapshot mismatch" }
+    end
+  end
+end
+
+::RSpec.configure do |config|
+  config.include Syrma::RSpec::Helpers, type: :zaniah
+  config.after(type: :zaniah) do |example|
+    zaniah_sessions.each_with_index do |session, index|
+      next unless example.exception
+
+      Syrma::Diagnostics.write(session, Syrma::Diagnostics.dir_for("RSpec", "#{example.full_description}-#{index}"),
+                               message: example.exception.message)
+    end
+    zaniah_sessions.each(&:close)
+  end
+end