ruby_raider 3.13.0 → 4.0.0

data/lib/ruby_raider/runtime/actionability.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'config'
+require_relative 'errors'
+require_relative 'wait'
+require_relative 'context'
+
+module Raider
+  # Waits for an element to be actionable before an action runs. On web contexts
+  # the checks run in the browser (js/actionability.js); on native ones the gate
+  # polls displayed?/enabled?. This module owns the check tables and the poll loops.
+  # :reek:TooManyConstants { max_constants: 6 } -- one table per check set, the script and the notice
+  module Actionability
+    CHECKS = {
+      click: %w[visible enabled inert stable events],
+      send_keys: %w[visible enabled editable inert],
+      clear: %w[visible enabled editable inert],
+      submit: %w[visible enabled inert]
+    }.freeze
+
+    NATIVE_CHECKS = {
+      click: %w[visible enabled],
+      send_keys: %w[visible enabled],
+      clear: %w[visible enabled],
+      submit: []
+    }.freeze
+
+    PHRASES = {
+      'visible' => 'be visible',
+      'enabled' => 'be enabled',
+      'editable' => 'be editable',
+      'inert' => 'not be inert',
+      'stable' => 'be stable',
+      'events' => 'receive events'
+    }.freeze
+
+    SCRIPT = File.read(File.join(__dir__, 'js', 'actionability.js')).freeze
+    FIRST_POLL = { 'check' => 'stable', 'first' => true }.freeze
+    NOTICE = '[raider] actionability on (Raider.actionability = false or force: true to skip)'
+
+    class << self
+      # Returns the number of not-ready polls (0 when skipped or ready at once).
+      def ensure(element, action, force:)
+        return 0 unless Raider.actionability
+
+        announce
+        web = Context.web_for?(element)
+        return attached(element, web) if force
+
+        poll(element) { web ? polled(element, action) : native_failure(element, action) }
+      end
+
+      def check(element, action)
+        element.instance_variable_get(:@bridge).execute_script(SCRIPT, element, CHECKS.fetch(action))
+      end
+
+      def reset_notice
+        @announced = false
+      end
+
+      private
+
+      # force skips every check but attached: a stale element raises here.
+      def attached(element, web)
+        web ? element.tag_name : element.displayed?
+        0
+      end
+
+      # Counts the polls whose block returns a failing check; the last one names the timeout.
+      def poll(element)
+        last = nil
+        retries = 0
+        started = clock
+        Wait.until(timeout: Raider.timeout) do
+          last = yield
+          next true unless last
+
+          retries += 1
+          throw :not_ready, last['check']
+        end
+        retries
+      rescue TimeoutError
+        raise not_actionable(element, last, clock - started, retries)
+      end
+
+      # Plain Appium commands, no script: the first check that fails, else nil.
+      def native_failure(element, action)
+        failing = NATIVE_CHECKS.fetch(action).find { |name| !native_ready?(element, name) }
+        failing && { 'check' => failing }
+      end
+
+      # The first poll only stores a rect for stable to compare with, so a short pause
+      # (inside the block; Wait.until's interval is fixed) replaces the full poll interval.
+      def polled(element, action)
+        result = check(element, action)
+        return result unless result == FIRST_POLL
+
+        sleep 0.02
+        check(element, action)
+      end
+
+      def native_ready?(element, name)
+        name == 'visible' ? element.displayed? : element.enabled?
+      end
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def not_actionable(element, last, waited, retries)
+        check = last.fetch('check')
+        NotActionable.new(Describe.element(element), PHRASES.fetch(check, check), covering: covering(last), waited: waited, retries: retries)
+      end
+
+      def covering(last)
+        found = last['covering']
+        found&.transform_keys(&:to_sym)
+      end
+
+      def announce
+        return if @announced || ENV['RAIDER_QUIET'] == '1'
+
+        @announced = true
+        $stderr.puts NOTICE # rubocop:disable Style/StderrPuts -- the notice must not be silenced by -W0
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/actionable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'observer'
+require_relative 'actionability'
+
+module Raider
+  # Waits for actionability before each Element action. force: true skips the
+  # checks except that the element must still be attached.
+  module Actionable
+    def click(force: false)
+      Observer.emit_action(self, :click) do |run|
+        raider_gate(run, :click, force)
+        super()
+      end
+    end
+
+    def send_keys(*keys, force: false)
+      Observer.emit_action(self, :send_keys, keys) do |run|
+        raider_gate(run, :send_keys, force)
+        super(*keys)
+      end
+    end
+    alias send_key send_keys
+
+    def clear(force: false)
+      Observer.emit_action(self, :clear) do |run|
+        raider_gate(run, :clear, force)
+        super()
+      end
+    end
+
+    def submit(force: false)
+      Observer.emit_action(self, :submit) do |run|
+        raider_gate(run, :submit, force)
+        super()
+      end
+    end
+
+    private
+
+    def raider_gate(run, action, force)
+      retries = Actionability.ensure(self, action, force: force)
+      run&.ready(retries)
+    end
+  end
+end
+
+Selenium::WebDriver::Element.prepend(Raider::Actionable)

data/lib/ruby_raider/runtime/by_role.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Raider
+  # The WAI-ARIA 1.2 concrete roles, plus generic.
+  ROLES = %w[
+    alert alertdialog application article banner blockquote button caption cell checkbox code columnheader
+    combobox complementary contentinfo definition deletion dialog directory document emphasis feed figure form
+    generic grid gridcell group heading img insertion link list listbox listitem log main marquee math menu
+    menubar menuitem menuitemcheckbox menuitemradio meter navigation none note option paragraph presentation
+    progressbar radio radiogroup region row rowgroup rowheader scrollbar search searchbox separator slider
+    spinbutton status strong subscript superscript switch tab table tablist tabpanel term textbox time timer
+    toolbar tooltip tree treegrid treeitem
+  ].freeze
+
+  # Builds the role locator: a Hash the finders turn into a raider role query.
+  module RoleLocator
+    module_function
+
+    def build(role, name, exact, include_hidden, level = nil)
+      token = validated_role(role)
+      raise ArgumentError, "name must be a String, got #{name.class}" unless name.nil? || name.is_a?(String)
+
+      validated_level(token, level)
+      options = { name: name, exact: (true if exact), include_hidden: (true if include_hidden), level: level }.compact
+      { role: options.empty? ? [token] : [token, options] }
+    end
+
+    # level: filters headings by h1-h6 or aria-level; nil means any level.
+    def validated_level(token, level)
+      return if level.nil?
+      raise ArgumentError, "level: only applies to the heading role, not '#{token}'" unless token == 'heading'
+      return if level.is_a?(Integer) && level.between?(1, 6)
+
+      raise ArgumentError, "level: must be an Integer from 1 to 6, got #{level.inspect}"
+    end
+
+    def validated_role(role)
+      token = role.to_s
+      return token if ROLES.include?(token)
+
+      raise ArgumentError, "unknown role '#{token}'; roles are the ARIA role names such as button, link, textbox"
+    end
+  end
+
+  def self.by_role(role, name: nil, exact: false, include_hidden: false, level: nil)
+    RoleLocator.build(role, name, exact, include_hidden, level)
+  end
+
+  # Locator helpers for page objects and wait helpers.
+  module Helpers
+    def by_role(role, **options)
+      Raider.by_role(role, **options)
+    end
+  end
+end

data/lib/ruby_raider/runtime/config.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+# Runtime configuration. Precedence per key: explicit setter, then env,
+# then config/config.yml, then the default.
+module Raider
+  CONFIG_FILE = 'config/config.yml'
+  FALSY = %w[off false 0 no].freeze
+
+  # Load-order and configuration mistakes.
+  class Error < StandardError; end
+
+  class << self
+    def strict
+      resolve(:strict, 'RAIDER_STRICT', true) { |value| truthy?(value) }
+    end
+
+    def actionability
+      resolve(:actionability, 'RAIDER_ACTIONABILITY', true) { |value| truthy?(value) }
+    end
+
+    def timeout
+      resolve(:timeout, 'RAIDER_TIMEOUT', 10) { |value| number(value) }
+    end
+
+    def test_id_attribute
+      resolve(:test_id_attribute, 'RAIDER_TEST_ID_ATTRIBUTE', 'data-testid', &:to_s)
+    end
+
+    attr_writer :strict, :actionability, :timeout, :test_id_attribute
+
+    # Any object (or nil) receiving action events; see Raider::Observer.
+    attr_accessor :observer
+
+    def reset
+      @strict = @actionability = @timeout = @test_id_attribute = nil
+      @observer = nil
+      @file_config = nil
+    end
+
+    private
+
+    def resolve(key, env_name, default)
+      explicit = instance_variable_get("@#{key}")
+      return explicit unless explicit.nil?
+
+      raw = ENV.fetch(env_name, nil)
+      raw = file_config[key.to_s] if raw.nil? || raw.empty?
+      raw.nil? ? default : yield(raw)
+    end
+
+    def file_config
+      @file_config ||= load_file
+    end
+
+    def load_file
+      return {} unless File.exist?(CONFIG_FILE)
+
+      data = YAML.safe_load_file(CONFIG_FILE, permitted_classes: [Symbol])
+      data.is_a?(Hash) ? data : {}
+    rescue Psych::Exception => e
+      raise Error, "cannot read #{CONFIG_FILE}: #{e.message}"
+    end
+
+    def truthy?(value)
+      return value if [true, false].include?(value)
+
+      !FALSY.include?(value.to_s.strip.downcase)
+    end
+
+    def number(value)
+      return value if value.is_a?(Numeric)
+
+      float = Float(value)
+      float == float.to_i ? float.to_i : float
+    end
+  end
+end

data/lib/ruby_raider/runtime/context.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+module Raider
+  # Decides whether strictness and actionability apply: on for Selenium drivers
+  # and Appium webviews, off on an Appium NATIVE_APP context.
+  module Context
+    NATIVE = 'NATIVE_APP'
+
+    class << self
+      def web?(bridge)
+        return true unless contextual?(bridge)
+
+        bridge.current_context != NATIVE
+      end
+
+      def web_for?(search_context)
+        bridge = search_context.instance_variable_get(:@bridge)
+        bridge.nil? || web?(bridge)
+      end
+
+      private
+
+      # Appium bridges answer current_context; an event-firing wrapper delegates it.
+      def contextual?(bridge)
+        # selenium 4.30's event-firing wrapper lacks respond_to_missing?, so look at its delegate.
+        bridge = bridge.instance_variable_get(:@delegate) if event_firing?(bridge)
+        bridge.respond_to?(:current_context)
+      end
+
+      def event_firing?(bridge)
+        defined?(Selenium::WebDriver::Support::EventFiringBridge) &&
+          bridge.is_a?(Selenium::WebDriver::Support::EventFiringBridge)
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/errors.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'config'
+
+module Raider
+  # Formats elements and durations for error messages.
+  module Describe
+    TEXT_LIMIT = 30
+    CLASS_LIMIT = 2
+
+    module_function
+
+    def seconds(value)
+      rounded = value.round(2)
+      rounded == rounded.to_i ? rounded.to_i : rounded
+    end
+
+    def element(element)
+      tag = element.tag_name
+      id = element.attribute('id').to_s
+      classes = element.attribute('class').to_s.split.first(CLASS_LIMIT).join(' ')
+      text = element.text.to_s.strip[0, TEXT_LIMIT]
+      open = "<#{tag}#{attribute_part('id', id)}#{attribute_part('class', classes)}>"
+      text.empty? ? open : "#{open}#{text}</#{tag}>"
+    rescue Selenium::WebDriver::Error::WebDriverError
+      '<element>'
+    end
+
+    def attribute_part(name, value)
+      value.empty? ? '' : %( #{name}="#{value}")
+    end
+  end
+
+  # A strict finder matched more than one element.
+  class AmbiguousMatch < Selenium::WebDriver::Error::WebDriverError
+    SHOWN = 3
+
+    attr_reader :elements
+
+    def initialize(locator_description, elements)
+      @elements = elements
+      listed = elements.first(SHOWN).map { |element| "`#{Describe.element(element)}`" }.join(', ')
+      more = [elements.size - SHOWN, 0].max
+      super("`#{locator_description}` matched #{elements.size} elements: #{listed} (+#{more} more); " \
+            'use find_elements, or narrow the locator')
+    end
+  end
+
+  # An element did not become actionable within the timeout.
+  class NotActionable < Selenium::WebDriver::Error::ElementNotInteractableError
+    attr_reader :check, :covering, :retries
+
+    def initialize(element_description, check, covering: nil, waited: Raider.timeout, retries: 0)
+      @check = check
+      @retries = retries
+      @covering = covering
+      message = "waited #{Describe.seconds(waited)}s for `#{element_description}` to #{check}"
+      message += "; `#{covering[:element]}` covers it at (#{covering[:x]}, #{covering[:y]})" if covering
+      super(message)
+    end
+  end
+
+  # The requested operation is not supported.
+  class NotSupported < Selenium::WebDriver::Error::UnsupportedOperationError; end
+
+  # A runtime wait timed out.
+  class TimeoutError < Selenium::WebDriver::Error::TimeoutError; end
+end

data/lib/ruby_raider/runtime/finders.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'errors'
+require_relative 'locator_converter'
+
+module Raider
+  FINDERS = {
+    label: 'raider label',
+    placeholder: 'raider placeholder',
+    alt: 'raider alt',
+    title: 'raider title',
+    text: 'raider text',
+    test_id: 'raider test id',
+    role: 'raider role'
+  }.freeze
+
+  # Registers the Raider locator keys and converter on Selenium and Appium.
+  module Finders
+    BRIDGE = 'Selenium::WebDriver::Remote::Bridge'
+    SEARCH_CONTEXT = 'Selenium::WebDriver::SearchContext'
+    SELENIUM_BRIDGES = %w[Selenium::WebDriver::Remote::Bridge Selenium::WebDriver::Remote::BiDiBridge].freeze
+    APPIUM_BRIDGES = %w[Appium::Core::Base::Bridge Appium::Core::Base::BiDiBridge].freeze
+
+    module_function
+
+    def register
+      context = Selenium::WebDriver::SearchContext
+      context.extra_finders = (context.extra_finders || {}).merge(FINDERS)
+    end
+
+    # Covers a late `require 'appium_lib'`, which overwrites the finder table
+    # and assigns its own bridge converter. Bridges created before the wrap keep
+    # the converter they copied; require the runtime before creating a driver.
+    def ensure_registered
+      register unless Selenium::WebDriver::SearchContext.finders.key?(:label)
+      install_appium_converters
+    end
+
+    def install_converter(bridge_class)
+      return if bridge_class.locator_converter.is_a?(LocatorConverter)
+
+      bridge_class.locator_converter = LocatorConverter.new(bridge_class.locator_converter)
+    end
+
+    def install
+      register
+      SELENIUM_BRIDGES.each { |name| install_converter(Object.const_get(name)) }
+      install_appium_converters
+    end
+
+    # Each bridge class keeps its own converter, so the BiDi subclasses need
+    # their own wrap. Appium classes are only touched when Appium is loaded.
+    def install_appium_converters
+      APPIUM_BRIDGES.each do |name|
+        install_converter(Object.const_get(name)) if Object.const_defined?(name)
+      end
+    end
+
+    def check_api
+      bridge = Selenium::WebDriver::Remote::Bridge
+      context = Selenium::WebDriver::SearchContext
+      raise Error, "#{BRIDGE} must respond to locator_converter=" unless bridge.respond_to?(:locator_converter=)
+      raise Error, "#{SEARCH_CONTEXT} must respond to extra_finders=" unless context.respond_to?(:extra_finders=)
+    end
+
+    def guard
+      return unless ObjectSpace.each_object(Selenium::WebDriver::Remote::Bridge).any?
+
+      raise Error, "require 'ruby_raider/runtime' before creating the driver"
+    end
+  end
+end

data/lib/ruby_raider/runtime/js/actionability.js

@@ -0,0 +1,134 @@
+// Actionability checks for Raider::Actionability. Runs as an execute_script body:
+// arguments[0] is the element, arguments[1] the Array of check names to run.
+// Returns null when every check passes, else { check, covering? } for the first failure.
+// Read-only apart from scrolling: it never sets styles, focuses, or dispatches events.
+const el = arguments[0];
+const names = arguments[1];
+const isOption = el.tagName === 'OPTION';
+const typing = names.includes('editable');
+
+const describe = (node) => {
+  let text = node.tagName.toLowerCase();
+  if (node.id) text += '#' + node.id;
+  const classes = Array.from(node.classList || []).slice(0, 2);
+  classes.forEach((name) => { text += '.' + name; });
+  return text;
+};
+
+// One step up the composed tree: the parent, or the host when leaving a shadow root.
+const up = (node) => node.parentNode || node.host || null;
+
+// First element on the composed path from node to the root (node included) that passes test.
+const composedClosest = (node, test) => {
+  for (let current = node; current; current = up(current)) {
+    if (current.nodeType === 1 && test(current)) return current;
+  }
+  return null;
+};
+
+const composedContains = (ancestor, node) => composedClosest(node, (current) => current === ancestor) !== null;
+
+// Not display: none on the node or any ancestor (a file input may have an empty rect).
+const displayed = (node) => {
+  if (node.checkVisibility) return node.checkVisibility();
+  return !composedClosest(node, (current) => window.getComputedStyle(current).display === 'none');
+};
+
+const visible = () => {
+  const target = isOption ? (el.closest('select') || el) : el;
+  const style = window.getComputedStyle(target);
+  if (target.tagName === 'INPUT' && target.type === 'file') {
+    // File inputs are routinely hidden behind a styled label, so typing a path skips visible.
+    return typing || displayed(target);
+  }
+  const rect = target.getBoundingClientRect();
+  if (!(rect.width > 0 && rect.height > 0)) return false;
+  if (target.checkVisibility) return target.checkVisibility({ visibilityProperty: true });
+  return style.visibility !== 'hidden';
+};
+
+const enabled = () => {
+  if (el.disabled) return false;
+  const fieldset = composedClosest(el, (node) => node.tagName === 'FIELDSET' && node.hasAttribute('disabled'));
+  if (!fieldset) return true;
+  const legend = fieldset.querySelector(':scope > legend');
+  return !!legend && composedContains(legend, el);
+};
+
+// Keys can go to any element (body for Escape, a button for Enter); only a readonly field refuses them.
+const editable = () => !((el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.readOnly);
+
+const modalDialog = () => {
+  try {
+    const modal = document.querySelector('dialog:modal');
+    if (modal) return modal;
+  } catch (error) {
+    // :modal is not supported; fall through to the open-dialog scan.
+  }
+  return Array.from(document.querySelectorAll('dialog[open]')).find((dialog) => {
+    try { return dialog.matches(':modal'); } catch (error) { return false; }
+  }) || null;
+};
+
+const notInert = () => {
+  if (composedClosest(el, (node) => node.hasAttribute('inert'))) return false;
+  const dialog = modalDialog();
+  return !dialog || composedContains(dialog, el);
+};
+
+const stable = () => {
+  if (isOption) return true;
+  window.__raiderRects = window.__raiderRects || new WeakMap();
+  const box = el.getBoundingClientRect();
+  const now = [box.x + window.scrollX, box.y + window.scrollY, box.width, box.height].map(Math.round).join(',');
+  const before = window.__raiderRects.get(el);
+  window.__raiderRects.set(el, now);
+  return before === undefined ? 'first' : before === now;
+};
+
+const clamp = (value, max) => Math.max(0, Math.min(Math.round(value), Math.max(max - 1, 0)));
+
+// Returns null when the centre point reaches the element, else a failure with covering.
+const events = () => {
+  if (isOption) return null;
+  const box = el.getBoundingClientRect();
+  const x = clamp(box.x + box.width / 2, window.innerWidth);
+  const y = clamp(box.y + box.height / 2, window.innerHeight);
+  const root = el.getRootNode();
+  const hit = (root.elementFromPoint ? root : document).elementFromPoint(x, y);
+  if (hit && el.contains(hit)) return null;
+  return hit ? { check: 'events', covering: { element: describe(hit), x: x, y: y } } : { check: 'events' };
+};
+
+const within = (box, outer) => (
+  box.top >= outer.top && box.left >= outer.left && box.bottom <= outer.bottom && box.right <= outer.right
+);
+
+// Inside the viewport (without scrollbars) and inside every clipping ancestor (overflow not visible).
+const unclipped = () => {
+  const box = el.getBoundingClientRect();
+  const root = document.documentElement;
+  if (!within(box, { top: 0, left: 0, bottom: root.clientHeight, right: root.clientWidth })) return false;
+  return !composedClosest(up(el) || el, (node) => {
+    if (node === root || node === document.body) return false;
+    const style = window.getComputedStyle(node);
+    if (style.overflowX === 'visible' && style.overflowY === 'visible') return false;
+    return !within(box, node.getBoundingClientRect());
+  });
+};
+
+if (!isOption && !unclipped()) el.scrollIntoView({ block: 'center', inline: 'center' });
+
+const simple = { visible: visible, enabled: enabled, editable: editable, inert: notInert, stable: stable };
+
+for (const name of names) {
+  if (name === 'events') {
+    const failure = events();
+    if (failure) return failure;
+  } else {
+    const result = simple[name]();
+    if (result === 'first') return { check: name, first: true };
+    if (!result) return { check: name };
+  }
+}
+return null;