ruby_raider 3.11.0 → 3.12.0

data/lib/generators/templates/helpers/wait_helper.tt

@@ -0,0 +1,470 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require 'yaml'
+require_relative 'raider_element'
+
+<%- if mobile? -%>
+# Waits before it acts. Each method takes a locator ({ accessibility_id: 'name' },
+# with or without braces, or { ios: {...}, android: {...} }), a RaiderElement or a
+# raw element, polls every 0.1s until the element is ready, then acts on it:
+#   tap({ accessibility_id: 'login' })
+#   send_keys({ accessibility_id: 'user' }, 'admin')
+#   swipe('left', { accessibility_id: 'card' })
+#   scroll_to({ accessibility_id: 'footer' })
+#   eventually { expect(text(accessibility_id: 'welcome')).to eq('Hi') }
+<%- else -%>
+# Waits before it acts. Each method takes a locator ({ id: 'name' }, with or
+# without braces), a RaiderElement or a raw element, polls every 0.1s until the
+# element is ready, then calls the Selenium method of the same name:
+#   click({ id: 'login' })
+#   send_keys({ id: 'user' }, 'admin')
+#   eventually { expect(text(css: '.welcome')).to eq('Hi') }
+<%- end -%>
+# The wait is config/config.yml `timeout` seconds, or `timeout:` for one call.
+module WaitHelper
+  class TimeoutError < Selenium::WebDriver::Error::TimeoutError; end
+
+  CONFIG_FILE = 'config/config.yml'
+  DEFAULT_TIMEOUT = 10
+
+  def self.default_timeout
+    @default_timeout ||= begin
+      config = File.exist?(CONFIG_FILE) ? YAML.load_file(CONFIG_FILE) : nil
+      (config.is_a?(Hash) && config['timeout']) || DEFAULT_TIMEOUT
+    end
+  end
+
+  def self.element(driver, locator, by = {})
+    RaiderElement.new(driver, Lookup.for(driver, locator, by))
+  end
+
+<%- if mobile? -%>
+  # Swipes or scrolls the element, or the whole screen without a locator.
+  def self.gesture(driver, kind, direction, locator, timeout)
+    return element(driver, locator).public_send(kind, direction, timeout: timeout) if locator
+
+    gesture = Gesture.new(driver, kind, direction)
+    Waiter.new(driver, timeout: timeout).perform_action(kind, Lookup.screen(driver), Waiter::PRESENT) do
+      gesture.perform(nil)
+    end
+    nil
+  end
+
+<%- end -%>
+  def find_element(locator = nil, visible: true, timeout: nil, **by)
+    Waiter.new(driver, timeout: timeout).find_element(Lookup.for(driver, locator, by), visible)
+  end
+
+  def find_elements(locator = nil, timeout: nil, **by)
+    Waiter.new(driver, timeout: timeout).find_elements(Lookup.for(driver, locator, by))
+  end
+
+<%- if mobile? -%>
+  %i[click clear text displayed? enabled? selected?].each do |action|
+<%- else -%>
+  %i[click clear submit hover scroll_into_view text displayed? enabled? selected?].each do |action|
+<%- end -%>
+    define_method(action) do |locator = nil, timeout: nil, **by|
+      WaitHelper.element(driver, locator, by).public_send(action, timeout: timeout)
+    end
+  end
+
+<%- if mobile? -%>
+  # tap is Appium's word for click and waits the same way. With a block and no
+  # locator it stays Ruby's Object#tap.
+  def tap(locator = nil, timeout: nil, **by, &block)
+    return super(&block) if block && locator.nil? && by.empty?
+
+    WaitHelper.element(driver, locator, by).tap(timeout: timeout)
+  end
+
+<%- end -%>
+  def send_keys(locator, *keys, timeout: nil)
+    WaitHelper.element(driver, locator).send_keys(*keys, timeout: timeout)
+  end
+
+<%- unless mobile? -%>
+  def select_by(locator, how, what, timeout: nil)
+    WaitHelper.element(driver, locator).select_by(how, what, timeout: timeout)
+  end
+
+<%- end -%>
+  def attribute(locator, name, timeout: nil)
+    WaitHelper.element(driver, locator).attribute(name, timeout: timeout)
+  end
+
+<%- if mobile? -%>
+  # direction: 'up', 'down', 'left' or 'right'.
+  def swipe(direction, locator = nil, timeout: nil)
+    WaitHelper.gesture(driver, :swipe, direction, locator, timeout)
+  end
+
+  def scroll(direction, locator = nil, timeout: nil)
+    WaitHelper.gesture(driver, :scroll, direction, locator, timeout)
+  end
+
+  # Scrolls the screen until the element is visible, then returns its RaiderElement.
+  def scroll_to(locator, direction: 'down', max_scrolls: 10, timeout: nil)
+    WaitHelper.element(driver, locator).scroll_to(direction: direction, max_scrolls: max_scrolls, timeout: timeout)
+  end
+<%- else -%>
+  def drag_and_drop(source, target, timeout: nil)
+    WaitHelper.element(driver, source).drag_and_drop(target, timeout: timeout)
+  end
+<%- end -%>
+
+  def eventually(timeout: nil, &block)
+    Waiter.new(nil, timeout: timeout).eventually(&block)
+  end
+
+  # How an element is found: a locator in a scope (the driver or a parent
+  # Lookup), or an element given as is. The found element is cached until reset.
+  class Lookup
+    OS_KEYS = %i[android ios].freeze
+    PASSED_HINT = 'it was passed in as an element, so it cannot be found again; ' \
+                  "pass its locator (for example { id: 'name' }) instead"
+    MEMBER_HINT = 'it came from find_elements, which keeps no locator per element; call find_elements again to re-query'
+
+    attr_reader :hint
+
+    def self.for(driver, locator, by, scope: driver)
+      raise ArgumentError, 'pass the locator in braces or as keywords, not both' if locator && !by.empty?
+
+      given = locator || by
+      # A wrapper keeps how it was found, so it can still re-find itself.
+      return given.__send__(:lookup) if given.is_a?(RaiderElement)
+      return new(scope, element: given, hint: PASSED_HINT) if !given.is_a?(Hash) && given.respond_to?(:displayed?)
+
+      new(scope, locator: normalize(driver, given))
+    end
+<%- if mobile? -%>
+
+    # No locator and no element: a whole-screen gesture, which locates nothing.
+    def self.screen(driver)
+      new(driver)
+    end
+<%- end -%>
+
+    def self.normalize(driver, given)
+      locator = symbolize(given)
+      per_os = !locator.empty? && (locator.keys - OS_KEYS).empty?
+      locator = symbolize(locator.fetch(driver.appium_device.to_s.downcase.to_sym, nil), given) if per_os
+      return locator if locator.size == 1
+
+      raise ArgumentError, "a locator is a Hash with one key, such as { id: 'name' }; got #{given.inspect}"
+    end
+
+    def self.symbolize(hash, given = hash)
+      return hash.transform_keys(&:to_sym) if hash.is_a?(Hash)
+
+      raise ArgumentError, "a locator is a Hash with one key, such as { id: 'name' }; got #{given.inspect}"
+    end
+
+    def initialize(scope, locator: nil, element: nil, hint: nil, many: false)
+      @scope = scope
+      @locator = locator
+      @element = element
+      @last_found = element
+      @hint = hint
+      @many = many
+      @scope_stale = false
+    end
+
+    # The last element found. A reset only drops the re-find cache, so a wrapper
+    # keeps its element (and its == and hash) after a timed-out wait.
+    def element
+      @element || @last_found
+    end
+
+    def many
+      Lookup.new(@scope, locator: @locator, element: @element, many: true)
+    end
+
+    def locate
+      return find_all if @many
+
+      return @element if @element || !@locator
+
+      @element = @last_found = in_scope { |context| context.find_element(**@locator) }
+    end
+
+    # A stale element may mean its parent was re-rendered too, so stale resets the chain.
+    def reset(stale: false)
+      @element = nil if @locator
+      @scope_stale = false
+      @scope.reset(stale: true) if stale && @scope.is_a?(Lookup)
+    end
+
+    # After a stale error: the Lookup up the chain whose element went stale and cannot be
+    # found again (passed in, or from find_elements), or nil when re-finding can heal it.
+    def lost
+      return self unless @locator
+
+      @scope.lost if @scope_stale
+    end
+
+    def describe
+      return 'the element' unless @locator
+
+      "{#{@locator.map { |key, value| "#{key}: #{value.inspect}" }.join(', ')}}"
+    end
+
+    private
+
+    # A stale error while searching inside the parent means the parent, or one above it, went stale.
+    def in_scope
+      return yield(@scope) unless @scope.is_a?(Lookup)
+
+      begin
+        yield(@scope.locate)
+      rescue Selenium::WebDriver::Error::StaleElementReferenceError
+        @scope_stale = true
+        raise
+      end
+    end
+
+    def find_all
+      return [@element] unless @locator
+
+      found = in_scope { |context| context.find_elements(**@locator) }
+      raise Selenium::WebDriver::Error::NoSuchElementError, 'no match' if found.empty?
+
+      found
+    end
+  end
+
+  # Polls until a Lookup is ready, then yields the raw element. perform_action
+  # is the one choke point every public method (bar eventually) goes through.
+  class Waiter
+    POLL_INTERVAL = 0.1
+    DEADLINE_KEY = :raider_wait_deadline
+    VISIBLE_ENABLED = %i[visible enabled].freeze
+    PRESENT = [].freeze
+<%- if mobile? -%>
+    CLICK = %i[visible enabled stable].freeze
+    VISIBLE = %i[visible].freeze
+    CHECKS = {
+      click: CLICK, tap: CLICK,
+      send_keys: VISIBLE_ENABLED, clear: VISIBLE_ENABLED,
+      swipe: VISIBLE, scroll: VISIBLE, scroll_to: VISIBLE,
+      text: PRESENT, attribute: PRESENT, displayed?: PRESENT, enabled?: PRESENT, selected?: PRESENT
+    }.freeze
+<%- else -%>
+    CHECKS = {
+      click: %i[visible enabled stable].freeze,
+      send_keys: VISIBLE_ENABLED, clear: VISIBLE_ENABLED, submit: VISIBLE_ENABLED, select_by: VISIBLE_ENABLED,
+      hover: %i[visible stable].freeze,
+      drag_and_drop: %i[visible enabled stable].freeze,
+      scroll_into_view: PRESENT, text: PRESENT, attribute: PRESENT,
+      displayed?: PRESENT, enabled?: PRESENT, selected?: PRESENT
+    }.freeze
+<%- end -%>
+    TARGET_CHECKS = %i[visible].freeze
+    STALE = 'stale element'
+    RETRIED = [Selenium::WebDriver::Error::StaleElementReferenceError,
+               Selenium::WebDriver::Error::ElementClickInterceptedError,
+               Selenium::WebDriver::Error::ElementNotInteractableError].freeze
+    HELPER_FILES = [__FILE__, File.expand_path('raider_element.rb', __dir__)].freeze
+
+    def initialize(driver, timeout: nil)
+      @driver = driver
+      @timeout = timeout
+      @last_rect = nil
+    end
+
+    def find_element(lookup, visible)
+      perform_action(:find_element, lookup, visible ? TARGET_CHECKS : PRESENT) { RaiderElement.new(@driver, lookup) }
+    end
+
+    def find_elements(lookup)
+      perform_action(:find_elements, lookup.many, PRESENT) do |elements|
+        elements.map { |found| RaiderElement.new(@driver, Lookup.new(@driver, element: found, hint: Lookup::MEMBER_HINT)) }
+      end
+    rescue TimeoutError
+      []
+    end
+
+    # checks: a subset of %i[visible enabled stable]; present is always checked.
+    # target: a second Lookup (the drop target) that must be visible in the same poll.
+    # between: called after each poll that was not ready (scroll_to scrolls there); once it
+    # returns false the wait stops, and the timeout message ends with its to_s.
+    def perform_action(action, locator, checks, target: nil, between: nil)
+      lookup = locator.is_a?(Lookup) ? locator : Lookup.for(@driver, locator, {})
+      deadline, waited = deadline_and_wait
+      loop do
+        seen = catch(:not_ready) do
+          elements = [ready(lookup, checks)]
+          elements << ready(target, TARGET_CHECKS, 'drop target ') if target
+          return yield(*elements)
+        rescue *RETRIED => e
+          retry_reason(lookup, e, action)
+        end
+        lookup.reset(stale: seen == STALE)
+        target&.reset
+        if now >= deadline || (between && !between.call)
+          seen = [seen, between].compact.join(' ')
+          raise TimeoutError, timeout_message(lookup, checks, seen, [waited, waited + now - deadline].min), backtrace
+        end
+
+        pause(deadline)
+      end
+    end
+
+    # Retries the block until it passes. Calls inside it share its deadline (see deadline_and_wait).
+    def eventually
+      enclosing = Thread.current[DEADLINE_KEY]
+      require 'rspec/expectations'
+      retried = [RSpec::Expectations::ExpectationNotMetError, Selenium::WebDriver::Error::NoSuchElementError,
+                 Selenium::WebDriver::Error::StaleElementReferenceError, TimeoutError]
+      deadline, waited = deadline_and_wait
+      Thread.current[DEADLINE_KEY] = deadline
+      loop do
+        return yield
+      rescue *retried => e
+        raise e.exception("(still failing after #{seconds(waited)}s)\n#{e.message}") if now >= deadline
+
+        pause(deadline)
+      end
+    ensure
+      Thread.current[DEADLINE_KEY] = enclosing
+    end
+
+    private
+
+    # Inside eventually, a call without timeout: waits for what is left of eventually's
+    # deadline; one with timeout: waits that long per attempt, never past eventually's deadline.
+    def deadline_and_wait
+      started = now
+      enclosing = Thread.current[DEADLINE_KEY]
+      own = started + (@timeout || WaitHelper.default_timeout) if @timeout || !enclosing
+      deadline = [own, enclosing].compact.min
+      [deadline, deadline - started]
+    end
+
+    def ready(lookup, checks, prefix = '')
+      element = lookup.locate
+      reason = unready(element, checks)
+      throw :not_ready, "#{prefix}#{reason}" if reason
+
+      element
+    rescue Selenium::WebDriver::Error::NoSuchElementError
+      throw :not_ready, "#{prefix}not found"
+    end
+
+    def unready(element, checks)
+      return 'present but not visible' if checks.include?(:visible) && !element.displayed?
+      return 'visible but disabled' if checks.include?(:enabled) && !element.enabled?
+
+      'still moving' if checks.include?(:stable) && !stable?(element)
+    end
+
+    # Stable: the same rect on two consecutive polls.
+    def stable?(element)
+      rect = element.rect
+      steady = rect == @last_rect
+      @last_rect = rect
+      steady
+    end
+
+    def retry_reason(lookup, error, action)
+      detail = error.message.lines.first.to_s.strip
+      case error
+      when Selenium::WebDriver::Error::StaleElementReferenceError
+        lost = lookup.lost
+        raise error.class, "#{detail} (during #{action}): #{lost.hint}", backtrace if lost
+
+        STALE
+      when Selenium::WebDriver::Error::ElementClickInterceptedError then "click intercepted: #{detail}"
+      else "not interactable: #{detail}"
+      end
+    end
+
+    def timeout_message(lookup, checks, seen, waited)
+      names = checks.map(&:to_s)
+      wanted = names.empty? ? 'present' : [names[0..-2].join(', '), names.last].reject(&:empty?).join(' and ')
+      "Waited #{seconds(waited)}s for #{lookup.describe} to be #{wanted}; last seen: #{seen}"
+    end
+
+    def seconds(value)
+      rounded = value.round(2)
+      rounded == rounded.to_i ? rounded.to_i : rounded
+    end
+
+    # Drops this helper's frames so the error points at the page object or spec line.
+    def backtrace
+      caller.reject { |line| HELPER_FILES.any? { |file| line.start_with?(file) } }
+            .drop_while { |line| line.start_with?('<internal:') }
+    end
+
+    def pause(deadline)
+      sleep([[POLL_INTERVAL, deadline - now].min, 0].max)
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+<%- if mobile? -%>
+
+  # A swipe or scroll through the platform's own mobile: command, as appium_lib issues them.
+  class Gesture
+    DIRECTIONS = %w[up down left right].freeze
+    COMMANDS = {
+      ios: { swipe: 'mobile: swipe', scroll: 'mobile: scroll' }.freeze,
+      android: { swipe: 'mobile: swipeGesture', scroll: 'mobile: scrollGesture' }.freeze
+    }.freeze
+    PERCENT = 0.75
+
+    def initialize(driver, kind, direction)
+      @driver = driver
+      @device = driver.appium_device.to_s.downcase.to_sym
+      @command = COMMANDS.dig(@device, kind)
+      raise NotImplementedError, "#{kind} has no gesture for #{driver.appium_device.inspect}; only :ios and :android" unless @command
+
+      @direction = direction.to_s
+      raise ArgumentError, "direction must be up, down, left or right; got #{direction.inspect}" unless DIRECTIONS.include?(@direction)
+    end
+
+    # element: the raw element to act on, or nil for the whole screen.
+    def perform(element)
+      @driver.execute_script(@command, arguments(element))
+    end
+
+    private
+
+    def arguments(element)
+      return { direction: @direction, element: element&.id }.compact if @device == :ios
+
+      area = element ? { elementId: element.id } : screen
+      area.merge(direction: @direction, percent: PERCENT)
+    end
+
+    def screen
+      rect = @driver.window_rect
+      { left: rect.x, top: rect.y, width: rect.width, height: rect.height }
+    end
+  end
+
+  # Scrolls the screen once per call, between scroll_to's polls, up to max_scrolls times.
+  class Scroller
+    def initialize(gesture, max_scrolls)
+      @gesture = gesture
+      @max_scrolls = max_scrolls
+      @scrolls = 0
+    end
+
+    # False once every scroll is used up.
+    def call
+      return false if @scrolls >= @max_scrolls
+
+      @gesture.perform(nil)
+      @scrolls += 1
+    end
+
+    def to_s
+      "after #{@scrolls} scrolls"
+    end
+  end
+<%- end -%>
+end

data/lib/ruby_raider/ffmpeg.rb

@@ -192,18 +192,18 @@ module RubyRaider
         [nil, true]
       end
 
-      def verified_cached?(path, sha256)
-        key = verification_key(path, sha256)
+      def verified_cached?(path, digest)
+        key = verification_key(path, digest)
         return true if @verified[key]
 
-        ok = verified?(path, sha256)
+        ok = verified?(path, digest)
         @verified[key] = true if ok
         ok
       end
 
-      def verification_key(path, sha256)
+      def verification_key(path, digest)
         stat = File.stat(path)
-        [path, stat.ino, stat.mtime.to_f, stat.ctime.to_f, stat.size, sha256]
+        [path, stat.ino, stat.mtime.to_f, stat.ctime.to_f, stat.size, digest]
       end
 
       def provision(env, manifest, fetch, warn, platform)
@@ -257,8 +257,8 @@ module RubyRaider
         nil
       end
 
-      def verified?(path, sha256)
-        Digest::SHA256.file(path).hexdigest.casecmp?(sha256)
+      def verified?(path, digest)
+        Digest::SHA256.file(path).hexdigest.casecmp?(digest)
       end
 
       def executable_file?(path)

data/lib/ruby_raider.rb

@@ -52,7 +52,9 @@ module RubyRaider
     map 'u' => 'utility'
 
     no_tasks do
+      # -p values arrive as strings; only examples:false turns the example tests off
       def generate_from_parameters(params)
+        params[:examples] = params[:examples].to_s.downcase != 'false' if params.key?(:examples)
         InvokeGenerators.generate_framework(params)
       end
 

data/lib/scaffolding/project_detector.rb

@@ -18,6 +18,7 @@ module ScaffoldProjectDetector
   }.freeze
 
   CONFIG_PATH = 'config/config.yml'
+  WAIT_HELPER_PATH = 'helpers/wait_helper.rb'
 
   class Error < StandardError; end
 
@@ -61,6 +62,11 @@ module ScaffoldProjectDetector
     detect_automation == 'watir'
   end
 
+  # Projects made before WaitHelper, or whose owner removed it, do not have the file.
+  def wait_helper?
+    File.exist?(WAIT_HELPER_PATH)
+  end
+
   # Validates that the current directory looks like a Ruby Raider project.
   # Returns an array of warning messages (empty = valid project).
   def validate_project

data/lib/scaffolding/scaffolding.rb

@@ -92,6 +92,10 @@ class Scaffolding < Thor::Group
     automation_type == 'watir'
   end
 
+  def wait_helper?
+    ScaffoldProjectDetector.wait_helper?
+  end
+
   def default_path(standard_path, file_type)
     path ? "#{path}/#{normalized_name}#{file_type}" : standard_path
   end

data/lib/scaffolding/templates/component.tt

@@ -12,7 +12,11 @@ class <%= class_name %> < Component
   private
 
   # Elements
+<%- if wait_helper? -%>
+  # Example: component.find_element(css: '.selector').click
+<%- else -%>
   # Example: driver.find_element(css: '.selector')
+<%- end -%>
 <%- elsif watir? -%>
 
   def content

data/lib/scaffolding/templates/page_object.tt

@@ -18,7 +18,11 @@ require_relative '../abstract/page'
 
 <%= '  ' * module_parts.size %>  # Elements
 <%- if selenium? -%>
+<%- if wait_helper? -%>
+<%= '  ' * module_parts.size %>  # Example: click({ id: 'element_id' })
+<%- else -%>
 <%= '  ' * module_parts.size %>  # Example: driver.find_element(id: 'element_id')
+<%- end -%>
 <%- elsif watir? -%>
 <%= '  ' * module_parts.size %>  # Example: browser.text_field(id: 'element_id')
 <%- end -%>
@@ -40,7 +44,11 @@ class <%= page_class_name %> < Page
 
   # Elements
 <%- if selenium? -%>
+<%- if wait_helper? -%>
+  # Example: click({ id: 'element_id' })
+<%- else -%>
   # Example: driver.find_element(id: 'element_id')
+<%- end -%>
 <%- elsif watir? -%>
   # Example: browser.text_field(id: 'element_id')
 <%- end -%>

data/lib/version

@@ -1 +1 @@
-3.11.0
+3.12.0

data/sig/generators/generator.rbs

@@ -19,6 +19,8 @@ class Generator < Thor::Group
   def github_ci?: () -> bool
   def selenium?: () -> bool
   def watir?: () -> bool
+  def wait_helper?: () -> bool
+  def examples?: () -> bool
   def web?: () -> bool
   def selenium_based?: () -> bool
 

data/sig/scaffolding/project_detector.rbs

@@ -9,5 +9,6 @@ module ScaffoldProjectDetector
   def self?.read_gemfile: () -> String
   def self?.selenium?: () -> bool
   def self?.watir?: () -> bool
+  def self?.wait_helper?: () -> bool
   def self?.config: () -> Hash[String, untyped]
 end

data/sig/scaffolding/scaffolding.rbs

@@ -25,5 +25,6 @@ class Scaffolding < Thor::Group
   def project_config: () -> Hash[String, untyped]
   def selenium?: () -> bool
   def watir?: () -> bool
+  def wait_helper?: () -> bool
   def default_path: (String standard_path, String file_type) -> String
 end

data/spec/commands/raider_commands_spec.rb

@@ -16,6 +16,30 @@ RSpec.describe RubyRaider::Raider do # rubocop:disable RSpec/FilePath
           hash_including(framework: 'rspec', automation: 'selenium', name: 'my_project')
         )
       end
+
+      it 'passes examples:false through as false' do
+        allow(InvokeGenerators).to receive(:generate_framework)
+
+        described_class.new.invoke(:new, nil, %w[my_project -p framework:rspec automation:selenium examples:false])
+
+        expect(InvokeGenerators).to have_received(:generate_framework).with(hash_including(examples: false))
+      end
+
+      it 'keeps the examples by default' do
+        allow(InvokeGenerators).to receive(:generate_framework)
+
+        described_class.new.invoke(:new, nil, %w[my_project -p framework:rspec automation:selenium])
+
+        expect(InvokeGenerators).to have_received(:generate_framework).with(hash_excluding(:examples))
+      end
+
+      it 'keeps the examples for any value other than false' do
+        allow(InvokeGenerators).to receive(:generate_framework)
+
+        described_class.new.invoke(:new, nil, %w[my_project -p framework:rspec automation:selenium examples:true])
+
+        expect(InvokeGenerators).to have_received(:generate_framework).with(hash_including(examples: true))
+      end
     end
 
     context 'without parameters' do