ruby_raider 3.13.0 → 4.0.0

data/lib/ruby_raider/runtime/matchers/element.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Raider
+  module Matchers
+    # Matchers that read one element. Readers go through read_with_zero_wait so a
+    # template element (which takes timeout:) never waits inside the matcher's own wait.
+    module Element
+      # Collapses runs of whitespace so text compares the way it reads on the page.
+      def self.normalise(text)
+        text.to_s.strip.gsub(/\s+/, ' ')
+      end
+
+      # The text of an element, as a substring or (exact: true) as equality.
+      class HaveText < Base
+        def initialize(text, exact: false, wait: nil)
+          super(text, wait: wait, exact: exact)
+        end
+
+        def verb
+          option(:exact) ? 'have exact text' : 'have text'
+        end
+
+        def read(subject)
+          read_with_zero_wait(subject, :text)
+        end
+
+        def pass?(value)
+          actual = Element.normalise(value)
+          return expected.match?(actual) if expected.is_a?(Regexp)
+
+          wanted = Element.normalise(expected)
+          option(:exact) ? actual == wanted : actual.include?(wanted)
+        end
+      end
+
+      # The `value` attribute of a field.
+      class HaveValue < Base
+        def verb
+          'have value'
+        end
+
+        def read(subject)
+          read_with_zero_wait(subject, :attribute, 'value')
+        end
+
+        def pass?(value)
+          expected.is_a?(Regexp) ? expected.match?(value.to_s) : value.to_s == expected.to_s
+        end
+      end
+
+      # An attribute that is present, equal to a String or matching a Regexp.
+      class HaveAttribute < Base
+        PRESENT = :present
+
+        def initialize(name, value = PRESENT, wait: nil)
+          super(name, wait: wait, value: value)
+        end
+
+        def verb
+          'have attribute'
+        end
+
+        def description
+          wanted = option(:value)
+          wanted == PRESENT ? super : "#{verb} #{expected.inspect} #{wanted.inspect}"
+        end
+
+        def read(subject)
+          read_with_zero_wait(subject, :attribute, expected)
+        end
+
+        def pass?(value)
+          wanted = option(:value)
+          return !value.nil? if wanted == PRESENT
+          return false if value.nil?
+
+          wanted.is_a?(Regexp) ? wanted.match?(value.to_s) : value.to_s == wanted.to_s
+        end
+      end
+
+      # A boolean state of an element, worded by the two labels it can read as.
+      class State < Base
+        LABELS = %w[yes no].freeze
+
+        def initialize(wait: nil)
+          super(true, wait: wait)
+        end
+
+        def description
+          verb
+        end
+
+        def pass?(value)
+          value == true
+        end
+
+        private
+
+        def show(value)
+          value ? self.class::LABELS.first : self.class::LABELS.last
+        end
+      end
+
+      # Displayed on the page.
+      class BeVisible < State
+        LABELS = %w[visible hidden].freeze
+
+        def verb
+          'be visible'
+        end
+
+        def read(subject)
+          read_with_zero_wait(subject, :displayed?)
+        end
+
+        private
+
+        # Gone counts as not visible for the negated form.
+        def negated_absent_passes?
+          true
+        end
+      end
+
+      # Not displayed, or gone: absence is a pass for the positive form.
+      class BeHidden < State
+        LABELS = %w[hidden visible].freeze
+
+        def verb
+          'be hidden'
+        end
+
+        def absent_passes?
+          true
+        end
+
+        def read(subject)
+          !read_with_zero_wait(subject, :displayed?)
+        end
+      end
+
+      # Enabled for interaction.
+      class BeEnabled < State
+        LABELS = %w[enabled disabled].freeze
+
+        def verb
+          'be enabled'
+        end
+
+        def read(subject)
+          read_with_zero_wait(subject, :enabled?)
+        end
+      end
+
+      # Not enabled.
+      class BeDisabled < State
+        LABELS = %w[disabled enabled].freeze
+
+        def verb
+          'be disabled'
+        end
+
+        def read(subject)
+          !read_with_zero_wait(subject, :enabled?)
+        end
+      end
+
+      # A checked checkbox or radio, or a selected option.
+      class BeChecked < State
+        LABELS = %w[checked unchecked].freeze
+
+        def verb
+          'be checked'
+        end
+
+        def read(subject)
+          read_with_zero_wait(subject, :selected?)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/matchers/page.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Raider
+  module Matchers
+    # Matchers about the page or a collection rather than one element.
+    module Page
+      # The size of an Array (read once) or of what a block returns (re-called each poll).
+      class HaveCount < Base
+        def verb
+          'have count'
+        end
+
+        def read(subject)
+          subject.size
+        end
+
+        def pass?(value)
+          value == expected
+        end
+
+        private
+
+        # A collection already in hand cannot change, so it gets a single pass.
+        def wait_for(actual)
+          actual.is_a?(Array) ? 0 : super
+        end
+
+        def target
+          polled_actual.is_a?(Array) ? 'the array' : super
+        end
+      end
+
+      # A value read from the driver: a String is equality, a Regexp is match?.
+      class Driver < Base
+        def pass?(value)
+          expected.is_a?(Regexp) ? expected.match?(value.to_s) : value.to_s == expected.to_s
+        end
+
+        private
+
+        def target
+          'the page'
+        end
+      end
+
+      # The title of the page.
+      class HaveTitle < Driver
+        def verb
+          'have title'
+        end
+
+        def read(subject)
+          subject.title
+        end
+      end
+
+      # The current url of the page, whole: 'account' does not match '.../account'.
+      class HaveUrl < Driver
+        def verb
+          'have url'
+        end
+
+        def read(subject)
+          subject.current_url
+        end
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/matchers/presence.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../strict'
+
+module Raider
+  module Matchers
+    # Matchers about whether elements exist under a driver or element.
+    module Presence
+      # The locator matches at least one element (negated: none). `expected` is the locator.
+      class HaveElement < Base
+        def verb
+          'have element'
+        end
+
+        # Base#settled? already reads under Wait.immediately.
+        def read(subject)
+          subject.find_elements(expected)
+        end
+
+        def pass?(value)
+          !value.empty?
+        end
+
+        def description
+          "#{verb} #{Raider::Locator.describe([expected])}"
+        end
+
+        private
+
+        def target
+          polled_actual.is_a?(Selenium::WebDriver::Driver) ? 'the page' : super
+        end
+
+        def show(value)
+          value.size
+        end
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/matchers/retrying_block.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+require 'selenium-webdriver'
+require_relative '../config'
+require_relative '../errors'
+require_relative '../wait'
+require_relative 'base'
+
+module Raider
+  module Matchers
+    # Prepended to RSpec's BlockExpectationTarget: `expect { value }.to eq(x)` polls the
+    # block until the value matches. Matchers that handle blocks themselves (Raider's,
+    # raise_error, change, output, yield_*) keep stock semantics and one evaluation.
+    # A polled block is re-run on every poll, so side effects in it repeat.
+    # Under aggregate_failures RSpec's notifier records the failure without raising,
+    # so the "(waited Ns)" prefix does not appear there.
+    module RetryingBlock
+      LOOKUP_ERRORS = [Selenium::WebDriver::Error::NoSuchElementError,
+                       Selenium::WebDriver::Error::StaleElementReferenceError,
+                       Raider::AmbiguousMatch,
+                       Selenium::WebDriver::Error::TimeoutError].freeze
+
+      # One evaluation of the block and the check; remembers what it saw.
+      class Attempt
+        attr_reader :value, :error
+
+        def initialize(block, check)
+          @block = block
+          @check = check
+          @value = Base::NOT_FOUND
+        end
+
+        def read?
+          !@value.equal?(Base::NOT_FOUND)
+        end
+
+        def pass?
+          @error = nil
+          @value = Raider::Wait.immediately { @block.call }
+          @check.call(@value)
+        rescue *LOOKUP_ERRORS => e
+          @error = e
+          false
+        end
+      end
+
+      def to(matcher = nil, message = nil, &)
+        return super if stock?(matcher)
+
+        settle(matcher, message, :to, false, &)
+      end
+
+      def not_to(matcher = nil, message = nil, &)
+        return super if stock?(matcher)
+
+        settle(matcher, message, :not_to, true, &)
+      end
+
+      def to_not(...)
+        not_to(...)
+      end
+
+      private
+
+      def stock?(matcher)
+        matcher.nil? || matcher.is_a?(Raider::Matchers::Base) ||
+          (matcher.respond_to?(:supports_block_expectations?) && matcher.supports_block_expectations?)
+      end
+
+      def check(matcher, negated)
+        return matcher.method(:matches?) unless negated
+        return matcher.method(:does_not_match?) if matcher.respond_to?(:does_not_match?)
+
+        ->(value) { !matcher.matches?(value) }
+      end
+
+      def settle(matcher, message, polarity, negated, &)
+        attempt = Attempt.new(target, check(matcher, negated))
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return true if polled?(attempt)
+
+        waited = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        give_up(attempt, [matcher, message], polarity, waited, &)
+      end
+
+      def polled?(attempt)
+        Raider::Wait.until(timeout: Raider.timeout) { attempt.pass? || throw(:not_ready) }
+        true
+      rescue Raider::TimeoutError
+        false
+      end
+
+      # The last poll's error wins; the last value goes to stock RSpec only when the last poll read one.
+      def give_up(attempt, arguments, polarity, waited, &)
+        raise(attempt.error || Raider::TimeoutError.new('the block never produced a value')) if attempt.error || !attempt.read?
+
+        RSpec::Expectations::ExpectationTarget.for(attempt.value, nil).public_send(polarity, *arguments, &)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        raise e.exception("(waited #{Raider::Describe.seconds(waited)}s) #{e.message}"), cause: nil
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/observer.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'config'
+require_relative 'role_finder'
+
+# Reports to an optional observer. A failing observer is switched off, never the test.
+module Raider
+  class << self
+    # Calls hook on the observer when it answers it; the block builds the details lazily.
+    # A broken observer (even a NotImplementedError or SystemStackError) is switched off, never the test.
+    def report(hook, *args, **details)
+      watcher = observer
+      return unless watcher.respond_to?(hook)
+
+      Observer.guarded { watcher.public_send(hook, *args, **(block_given? ? yield : details)) }
+    rescue StandardError, ScriptError, SystemStackError => e
+      Observer.stop(watcher, e)
+    end
+  end
+
+  # Element actions as events, and the locator stamped on every found element.
+  module Observer
+    LIB_DIR = File.expand_path(__dir__)
+    GUARD_KEY = :raider_in_observer
+    MESSAGE_LIMIT = 200
+
+    STRATEGIES = {
+      'css_selector' => 'css', 'css selector' => 'css', 'class' => 'class_name', 'class name' => 'class_name',
+      'link' => 'link_text', 'link text' => 'link_text', 'partial_link' => 'partial_link_text',
+      'partial link text' => 'partial_link_text', 'tag name' => 'tag_name'
+    }.freeze
+
+    # One reported action. :reek:TooManyInstanceVariables { max_instance_variables: 6 } -- the event's whole state
+    class Run
+      def initialize(element, action, args)
+        @element = element
+        @action = action
+        @args = args&.dup&.freeze # an observer can read the keys, never change what gets typed
+        @retries = 0
+        @token = Raider.report(:action_started) { Observer.started(element, action, @args) }
+        @started = Observer.clock
+      end
+
+      def ready(retries)
+        @retries = retries
+        Raider.report(:action_ready, @token) { { element: @element } } unless @token.nil?
+      end
+
+      def finish(error)
+        Raider.report(:action_finished, @token) { finished(error) } unless @token.nil?
+      end
+
+      private
+
+      def finished(error)
+        @retries = error.retries if error.is_a?(NotActionable)
+        { status: error ? :failed : :passed, waited_ms: Observer.millis(@started), retries: @retries,
+          error: error, element: @element }
+      end
+    end
+
+    class << self
+      # Yields a Run (nil without an observer); reports the outcome and re-raises whatever the body raised.
+      def emit_action(element, action, args = nil)
+        return yield(nil) if Raider.observer.nil? || Thread.current[GUARD_KEY]
+
+        run = Run.new(element, action, args)
+        begin
+          result = yield(run)
+        rescue Exception => e # rubocop:disable Lint/RescueException -- reports and re-raises, never swallows
+          run.finish(e)
+          raise
+        end
+        run.finish(nil)
+        result
+      end
+
+      def started(element, action, args)
+        stamp = locator_of(element)
+        { action: action, locator: stamp&.slice(:strategy, :selector), within: stamp ? stamp[:within] : [], args: args }
+      end
+
+      def locator_of(element)
+        element.instance_variable_get(:@raider_locator)
+      end
+
+      def stamp(element, args, parent)
+        attach(element, frozen_stamp(args, parent))
+      end
+
+      # One stamp per find, shared by every element it returned.
+      def stamp_all(elements, args, parent)
+        return elements if elements.empty?
+
+        shared = frozen_stamp(args, parent)
+        elements.each { |element| attach(element, shared) }
+      end
+
+      # Marks the observer as busy so an action taken inside a hook is not reported again.
+      def guarded
+        previous = Thread.current[GUARD_KEY]
+        Thread.current[GUARD_KEY] = true
+        yield
+      ensure
+        Thread.current[GUARD_KEY] = previous
+      end
+
+      # Prints one line and clears the observer, unless the observer was replaced meanwhile.
+      def stop(watcher, error)
+        $stderr.puts "[raider] observer stopped: #{summary(error)}" # rubocop:disable Style/StderrPuts -- must not be silenced by -W0
+        Raider.observer = nil if Raider.observer.equal?(watcher)
+      end
+
+      def millis(started)
+        ((clock - started) * 1000).round
+      end
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      private
+
+      def attach(element, stamp)
+        return element if !element.is_a?(Selenium::WebDriver::Element) || element.frozen?
+
+        element.instance_variable_set(:@raider_locator, stamp)
+        element
+      end
+
+      def frozen_stamp(args, parent)
+        stamp = describe(args, parent)
+        stamp[:within].each(&:freeze).freeze
+        stamp.freeze
+      end
+
+      # The class and the first line of the message; never raises, whatever #message does.
+      def summary(error)
+        line = error.message.to_s.lines.first.to_s.chomp
+        "#{error.class}: #{line[0, MESSAGE_LIMIT]}"
+      rescue StandardError, ScriptError, SystemStackError
+        error.class.to_s
+      end
+
+      def describe(args, parent)
+        how, what = args.size == 1 && args.first.is_a?(Hash) ? args.first.first : args
+        strategy = how.to_s
+        { strategy: -STRATEGIES.fetch(strategy, strategy).to_s, selector: -selector(strategy, what, args),
+          within: chain(parent) }
+      end
+
+      def selector(strategy, what, args)
+        return role_text(args) if strategy == 'role'
+
+        (what.is_a?(Array) ? what.first : what).to_s
+      end
+
+      def role_text(args)
+        role, options = RoleFinder.parse(args)
+        [role, *options.map { |key, value| "#{key}: #{value}" }].join(', ')
+      end
+
+      def chain(parent)
+        found = parent.is_a?(Selenium::WebDriver::Element) ? locator_of(parent) : nil
+        found ? [*found[:within], found.slice(:strategy, :selector)] : []
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime/role_finder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+module Raider
+  # The in-page role engine and the query that calls it.
+  module RoleFinder
+    ENGINE = File.read(File.join(__dir__, 'js', 'role_engine.js')).freeze
+    QUERY = "if (!(window.__raider && window.__raider.role)) throw new Error('__raider not installed'); " \
+            'return window.__raider.role(arguments[0] || document, arguments[1], arguments[2])'
+
+    NATIVE_MESSAGE = 'by_role needs a web context; use accessibility_id on native screens'
+
+    # Prepended to SearchContext: sends the :role key to the engine, everything else to Selenium.
+    def find_elements(*args)
+      role, options = RoleFinder.parse(args)
+      return super unless role
+
+      raise NotSupported, NATIVE_MESSAGE unless Context.web?(bridge)
+
+      RoleQuery.run(bridge, is_a?(Selenium::WebDriver::Driver) ? nil : self, role, options)
+    end
+
+    def find_element(*args)
+      return super unless RoleFinder.role_args?(args)
+
+      find_elements(*args).first or
+        raise Selenium::WebDriver::Error::NoSuchElementError, "no such element: #{Locator.describe(args)}"
+    end
+
+    def self.role_args?(args)
+      key = args.size == 1 && args.first.is_a?(Hash) ? args.first.keys.first : args.first
+      key.to_s == 'role'
+    end
+
+    # Returns [role, symbol-keyed options] for a role locator, nil for any other.
+    def self.parse(args)
+      return unless role_args?(args)
+
+      value = args.size == 1 ? args.first.values.first : args[1]
+      role, options = value.is_a?(Array) ? value : [value, nil]
+      raise ArgumentError, 'role: needs a role name and an optional options Hash' unless options.nil? || options.is_a?(Hash)
+
+      options = (options || {}).transform_keys(&:to_sym)
+      raise ArgumentError, "role: name must be a String, got #{options[:name].class}" unless [NilClass, String].include?(options[:name].class)
+
+      token = validated(role)
+      RoleLocator.validated_level(token, options[:level])
+      [token, options]
+    end
+
+    def self.validated(role)
+      raise ArgumentError, "role: needs a role name, got #{role.inspect}" unless role.is_a?(String) || role.is_a?(Symbol)
+
+      RoleLocator.validated_role(role)
+    end
+  end
+
+  # Runs a role query through the bridge, installing the engine on first use.
+  module RoleQuery
+    module_function
+
+    def run(bridge, scope, role, options)
+      options_js = options_js(options)
+      bridge.execute_script(RoleFinder::QUERY, scope, role, options_js)
+    rescue Selenium::WebDriver::Error::JavascriptError => e
+      raise unless e.message.include?('__raider')
+
+      bridge.execute_script("#{RoleFinder::ENGINE}\n#{RoleFinder::QUERY}", scope, role, options_js)
+    end
+
+    def options_js(options)
+      {
+        'name' => options[:name],
+        'exact' => options[:exact] ? true : false,
+        'includeHidden' => options[:include_hidden] ? true : false,
+        'level' => options[:level]
+      }
+    end
+  end
+end
+
+Selenium::WebDriver::SearchContext.prepend(Raider::RoleFinder)