ruby_raider 3.13.0 → 4.0.0

data/lib/ruby_raider/runtime/rspec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+require_relative '../runtime'
+require_relative 'matchers/base'
+require_relative 'matchers/element'
+require_relative 'matchers/page'
+require_relative 'matchers/presence'
+require_relative 'matchers/retrying_block'
+
+module Raider
+  # Web-first RSpec matchers that retry until the page settles.
+  # rubocop:disable Naming/PredicatePrefix -- the matcher names are RSpec's vocabulary
+  module Matchers
+    def have_text(text, exact: false, wait: nil)
+      Element::HaveText.new(text, exact: exact, wait: wait)
+    end
+
+    def have_value(value, wait: nil)
+      Element::HaveValue.new(value, wait: wait)
+    end
+
+    def have_attribute(name, value = Element::HaveAttribute::PRESENT, wait: nil)
+      Element::HaveAttribute.new(name, value, wait: wait)
+    end
+
+    def be_visible(wait: nil)
+      Element::BeVisible.new(wait: wait)
+    end
+
+    def be_hidden(wait: nil)
+      Element::BeHidden.new(wait: wait)
+    end
+
+    def be_enabled(wait: nil)
+      Element::BeEnabled.new(wait: wait)
+    end
+
+    def be_disabled(wait: nil)
+      Element::BeDisabled.new(wait: wait)
+    end
+
+    def be_checked(wait: nil)
+      Element::BeChecked.new(wait: wait)
+    end
+
+    def have_element(locator = nil, wait: nil, **by)
+      raise ArgumentError, 'have_element takes a locator, not both a hash and keywords' if locator && !by.empty?
+      raise ArgumentError, 'have_element needs a locator' if locator.nil? && by.empty?
+
+      Presence::HaveElement.new(locator || by, wait: wait)
+    end
+
+    def have_css(selector, wait: nil)
+      have_element({ css: selector }, wait: wait)
+    end
+
+    def have_xpath(selector, wait: nil)
+      have_element({ xpath: selector }, wait: wait)
+    end
+
+    def have_count(count, wait: nil)
+      Page::HaveCount.new(count, wait: wait)
+    end
+
+    def have_title(expected, wait: nil)
+      Page::HaveTitle.new(expected, wait: wait)
+    end
+
+    def have_url(expected, wait: nil)
+      Page::HaveUrl.new(expected, wait: wait)
+    end
+  end
+  # rubocop:enable Naming/PredicatePrefix
+end
+
+target = RSpec::Expectations::BlockExpectationTarget
+target.prepend(Raider::Matchers::RetryingBlock) unless target.ancestors.include?(Raider::Matchers::RetryingBlock)

data/lib/ruby_raider/runtime/selectors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+
+module Raider
+  # Builds the XPath and CSS strings behind the label, placeholder, alt,
+  # title, text and test_id locator keys. Every caller-supplied value passes
+  # through xpath_literal or the CSS escaper; nothing else is interpolated.
+  module Selectors
+    ATTRIBUTE_NAME = /\A[A-Za-z_][\w-]*\z/
+    LABEL_CONTROLS = %w[input textarea select button meter output progress]
+                     .map { |tag| "self::#{tag}" }.join(' or ').freeze
+    EXCLUDED_TEXT = 'not(self::script or self::style or self::noscript or self::template or self::title or self::head) ' \
+                    'and not(ancestor::head)'
+
+    module_function
+
+    def xpath_literal(string)
+      value = string.to_s
+      return "'#{value}'" unless value.include?("'")
+      return %("#{value}") unless value.include?('"')
+
+      parts = value.split("'", -1).map { |part| "'#{part}'" }
+      "concat(#{parts.join(%q(, "'", ))})"
+    end
+
+    def label(value, exact:)
+      literal = xpath_literal(value)
+      [
+        ".//*[@id = //label[#{match('.', literal, exact)}]/@for]",
+        ".//label[#{match('.', literal, exact)}]//*[(#{LABEL_CONTROLS}) and not(self::input[@type='hidden'])]",
+        ".//*[#{match('@aria-label', literal, exact)}]",
+        ".//*[@aria-labelledby and #{match('string(id(@aria-labelledby))', literal, exact)}]"
+      ].join(' | ')
+    end
+
+    def text(value, exact:)
+      matcher = match('.', xpath_literal(value), exact)
+      candidate = "#{EXCLUDED_TEXT} and #{matcher}"
+      ".//*[#{candidate} and not(.//*[#{candidate}])]"
+    end
+
+    def attribute_css(name, value, exact:)
+      raise ArgumentError, "invalid attribute name: #{name}" unless name.to_s.match?(ATTRIBUTE_NAME)
+
+      escaped = value.to_s.gsub('\\') { '\\\\' }.gsub('"') { '\\"' }
+      "[#{name}#{exact ? '=' : '*='}\"#{escaped}\"]"
+    end
+
+    def test_id(value)
+      attribute_css(Raider.test_id_attribute, value, exact: true)
+    end
+
+    def match(expression, literal, exact)
+      return "normalize-space(#{expression}) = #{literal}" if exact
+
+      "contains(normalize-space(#{expression}), #{literal})"
+    end
+  end
+end

data/lib/ruby_raider/runtime/strict.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'config'
+require_relative 'errors'
+require_relative 'context'
+require_relative 'finders'
+require_relative 'observer'
+
+module Raider
+  # Renders a find_element argument list for error messages.
+  module Locator
+    module_function
+
+    def describe(args)
+      how, what = args
+      args.size == 1 && how.is_a?(Hash) ? from_hash(how) : "{ #{how.to_s.inspect}: #{what.inspect} }"
+    rescue StandardError
+      args.inspect
+    end
+
+    def from_hash(hash)
+      key, value = hash.first
+      return "by_role(#{role_arguments(value)})" if key == :role && value.is_a?(Array)
+
+      "{ #{key}: #{plain_arguments(value)} }"
+    end
+
+    def role_arguments(value)
+      name, options = value
+      ["'#{name}'", *render_options(options)].join(', ')
+    end
+
+    def plain_arguments(value)
+      return value.inspect unless value.is_a?(Array)
+
+      text, options = value
+      [text.inspect, *render_options(options)].join(', ')
+    end
+
+    def render_options(options)
+      return [] unless options.is_a?(Hash)
+
+      options.map { |key, option| "#{key}: #{option.inspect}" }
+    end
+  end
+
+  # Prepended to SearchContext: find_element must match exactly one element, and
+  # both finds wait for a match.
+  module StrictFinder
+    def find_element(*args)
+      Finders.ensure_registered
+      attempt = element_attempt(args) { super(*args) }
+      Observer.stamp(await_element(args, attempt), args, self)
+    end
+
+    def find_elements(*args)
+      return Observer.stamp_all(super, args, self) if Wait.immediate?
+
+      attempt = elements_attempt(args) { super(*args) }
+      found = []
+      begin
+        Wait.until(timeout: Raider.timeout) { (found = attempt.call).any? }
+      rescue TimeoutError
+        nil
+      end
+      Observer.stamp_all(found, args, self)
+    end
+
+    private
+
+    def await_element(args, attempt)
+      return attempt.call || raise(Selenium::WebDriver::Error::NoSuchElementError, not_found(args)) if Wait.immediate?
+
+      started = clock
+      begin
+        Wait.until(timeout: Raider.timeout) { attempt.call }
+      rescue TimeoutError
+        raise Selenium::WebDriver::Error::NoSuchElementError,
+              "#{not_found(args)} (waited #{Describe.seconds(clock - started)}s)"
+      end
+    end
+
+    # A callable making one attempt at the element: the element, or nil when nothing
+    # matched yet. The context is decided here, once per find, not per attempt.
+    def element_attempt(args, &raw)
+      if RoleFinder.role_args?(args)
+        queried = role_attempt(args)
+        strict = Raider.strict
+        return -> { sole(args, queried.call, strict) }
+      end
+      return -> { native_or_nil(&raw) } unless Raider.strict && Context.web?(bridge)
+
+      -> { sole(args, Wait.immediately { find_elements(*args) }, true) }
+    end
+
+    def elements_attempt(args, &raw)
+      RoleFinder.role_args?(args) ? role_attempt(args) : raw
+    end
+
+    # Validates the role locator and checks the context once, then queries the engine directly.
+    def role_attempt(args)
+      role, options = RoleFinder.parse(args)
+      raise NotSupported, RoleFinder::NATIVE_MESSAGE unless Context.web?(bridge)
+
+      scope = is_a?(Selenium::WebDriver::Driver) ? nil : self
+      -> { RoleQuery.run(bridge, scope, role, options) }
+    end
+
+    def sole(args, found, strict)
+      raise AmbiguousMatch.new(Locator.describe(args), found) if strict && found.size > 1
+
+      found.first
+    end
+
+    def native_or_nil
+      yield
+    rescue Selenium::WebDriver::Error::NoSuchElementError
+      nil
+    end
+
+    def not_found(args)
+      "no such element: #{Locator.describe(args)}"
+    end
+
+    def clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end
+
+# Selenium aliases `first` to find_element on Driver and Element, which
+# bypasses the prepend above; `find_elements(...).first` stays the non-strict escape.
+module Raider
+  # Routes Selenium's `first` alias through the strict find_element.
+  module StrictFirst
+    def first(*args) = find_element(*args)
+  end
+end
+
+Selenium::WebDriver::SearchContext.prepend(Raider::StrictFinder)
+[Selenium::WebDriver::Driver, Selenium::WebDriver::Element].each { |klass| klass.prepend(Raider::StrictFirst) }

data/lib/ruby_raider/runtime/wait.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'config'
+require_relative 'errors'
+
+module Raider
+  # The runtime wait loop. Nested waits share one deadline through DEADLINE_KEY
+  # (the same key the generated wait helper uses).
+  module Wait
+    DEADLINE_KEY = :raider_wait_deadline
+    # Like DEADLINE_KEY, fiber-scoped on purpose (Thread.current[] is per fiber).
+    IMMEDIATE_KEY = :raider_wait_immediate
+
+    class << self
+      def deadline
+        Thread.current[DEADLINE_KEY]
+      end
+
+      # Runs the block with finds making one attempt each (the caller does the waiting).
+      def immediately
+        previous = Thread.current[IMMEDIATE_KEY]
+        Thread.current[IMMEDIATE_KEY] = true
+        yield
+      ensure
+        Thread.current[IMMEDIATE_KEY] = previous
+      end
+
+      def immediate?
+        Thread.current[IMMEDIATE_KEY] == true
+      end
+
+      # Polls until the block returns a truthy value. The block may
+      # `throw :not_ready, reason` to say why it is not ready yet.
+      def until(timeout: nil, interval: 0.1)
+        limit, = limits(timeout)
+        within(limit) do
+          reason = nil
+          loop do
+            result = nil
+            thrown = catch(:not_ready) do
+              result = yield
+              nil
+            end
+            return result if result
+
+            reason = thrown || reason
+            raise TimeoutError, reason || 'condition not met' if now >= limit
+
+            pause(limit, interval)
+          end
+        end
+      end
+
+      private
+
+      # Inside an enclosing deadline, a call without timeout waits for what is left;
+      # one with timeout waits that long, never past the enclosing deadline.
+      def limits(timeout)
+        started = now
+        enclosing = deadline
+        own = started + (timeout || Raider.timeout) if timeout || !enclosing
+        limit = [own, enclosing].compact.min
+        [limit, limit - started]
+      end
+
+      def within(limit)
+        enclosing = deadline
+        Thread.current[DEADLINE_KEY] = limit
+        yield
+      ensure
+        Thread.current[DEADLINE_KEY] = enclosing
+      end
+
+      def pause(limit, interval)
+        sleep([[interval, limit - now].min, 0].max)
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/ruby_raider/runtime.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require_relative 'runtime/config'
+require_relative 'runtime/errors'
+require_relative 'runtime/by_role'
+require_relative 'runtime/wait'
+require_relative 'runtime/context'
+require_relative 'runtime/selectors'
+require_relative 'runtime/locator_converter'
+require_relative 'runtime/finders'
+require_relative 'runtime/role_finder'
+require_relative 'runtime/observer'
+require_relative 'runtime/actionability'
+require_relative 'runtime/strict'
+require_relative 'runtime/actionable'
+
+Raider::Finders.check_api
+Raider::Finders.install
+Raider::Finders.guard

data/lib/scaffolding/name_normalizer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NameNormalizer
-  SUFFIXES = %w[_page _spec _steps _helper _test _feature].freeze
+  SUFFIXES = %w[_page _spec _helper _test].freeze
 
   module_function
 

data/lib/scaffolding/project_detector.rb

@@ -4,21 +4,13 @@ require 'yaml'
 
 module ScaffoldProjectDetector
   AUTOMATION_GEMS = {
-    'watir' => 'watir',
     'selenium-webdriver' => 'selenium',
     'appium_lib' => 'appium',
     'eyes_selenium' => 'selenium',
-    'axe-core-rspec' => 'selenium',
-    'axe-core-cucumber' => 'selenium'
-  }.freeze
-
-  FRAMEWORK_GEMS = {
-    'rspec' => 'rspec',
-    'cucumber' => 'cucumber'
+    'axe-core-rspec' => 'selenium'
   }.freeze
 
   CONFIG_PATH = 'config/config.yml'
-  WAIT_HELPER_PATH = 'helpers/wait_helper.rb'
 
   class Error < StandardError; end
 
@@ -28,9 +20,7 @@ module ScaffoldProjectDetector
     gemfile = read_gemfile
     {
       automation: detect_automation(gemfile),
-      framework: detect_framework(gemfile),
-      has_spec: Dir.exist?('spec'),
-      has_features: Dir.exist?('features')
+      has_spec: Dir.exist?('spec')
     }
   end
 
@@ -41,13 +31,6 @@ module ScaffoldProjectDetector
     'selenium'
   end
 
-  def detect_framework(gemfile = read_gemfile)
-    FRAMEWORK_GEMS.each do |gem_name, framework|
-      return framework if gemfile.include?("'#{gem_name}'") || gemfile.include?("\"#{gem_name}\"")
-    end
-    'rspec'
-  end
-
   def read_gemfile
     return '' unless File.exist?('Gemfile')
 
@@ -58,15 +41,6 @@ module ScaffoldProjectDetector
     detect_automation == 'selenium'
   end
 
-  def watir?
-    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

@@ -21,10 +21,6 @@ class Scaffolding < Thor::Group
     template('page_object.tt', default_path("page_objects/pages/#{normalized_name}.rb", '_page.rb'))
   end
 
-  def generate_feature
-    template('feature.tt', default_path("features/#{normalized_name}.feature", '.feature'))
-  end
-
   def generate_spec
     template('spec.tt', default_path("spec/#{normalized_name}_page_spec.rb", '_spec.rb'))
   end
@@ -33,10 +29,6 @@ class Scaffolding < Thor::Group
     template('helper.tt', default_path("helpers/#{normalized_name}_helper.rb", '_helper.rb'))
   end
 
-  def generate_steps
-    template('steps.tt', default_path("features/step_definitions/#{normalized_name}_steps.rb", '_steps.rb'))
-  end
-
   def generate_component
     template('component.tt', default_path("page_objects/components/#{normalized_name}.rb", '.rb'))
   end
@@ -76,10 +68,6 @@ class Scaffolding < Thor::Group
     ScaffoldProjectDetector.detect_automation
   end
 
-  def framework_type
-    ScaffoldProjectDetector.detect_framework
-  end
-
   def project_config
     ScaffoldProjectDetector.config
   end
@@ -88,14 +76,6 @@ class Scaffolding < Thor::Group
     automation_type == 'selenium'
   end
 
-  def watir?
-    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,20 +12,6 @@ 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
-    component.text
-  end
-
-  private
-
-  # Elements
-  # Example: browser.element(css: '.selector')
 <%- end -%>
 end

data/lib/scaffolding/templates/page_object.tt

@@ -18,13 +18,7 @@ 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')
+<%= '  ' * module_parts.size %>  # Example: def submit_button = driver.find_element(by_role('button', name: 'Submit'))
 <%- end -%>
 <%= '  ' * module_parts.size %>end
 <% module_parts.each_with_index do |_mod, i| -%>
@@ -44,13 +38,7 @@ 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')
+  # Example: def submit_button = driver.find_element(by_role('button', name: 'Submit'))
 <%- end -%>
 end
 <% end -%>

data/lib/scaffolding/templates/spec.tt

@@ -5,18 +5,10 @@ require_relative '../page_objects/pages/<%= normalized_name %>'
 describe '<%= page_class_name %>' do
 <%- if selenium? -%>
   let(:page) { <%= page_class_name %>.new(driver) }
-<%- elsif watir? -%>
-  let(:page) { <%= page_class_name %>.new(browser) }
 <%- end -%>
 <%- if project_config['url'] -%>
 
-  before do
-<%- if selenium? -%>
-    driver.navigate.to "\#{project_config['url']}/<%= normalized_name %>"
-<%- elsif watir? -%>
-    browser.goto "\#{project_config['url']}/<%= normalized_name %>"
-<%- end -%>
-  end
+  before { page.visit }
 <%- end -%>
 
   it 'loads successfully' do

data/lib/utilities/utilities.rb

@@ -23,10 +23,6 @@ module Utilities
       set('spec_path', path)
     end
 
-    def feature_path=(path)
-      set('feature_path', path)
-    end
-
     def helper_path=(path)
       set('helper_path', path)
     end
@@ -68,6 +64,14 @@ module Utilities
       set('headless', enabled)
     end
 
+    def strict=(enabled)
+      set('strict', enabled)
+    end
+
+    def actionability=(enabled)
+      set('actionability', enabled)
+    end
+
     def video_enabled=(enabled)
       reload_config
       video = @config['video']
@@ -91,13 +95,11 @@ module Utilities
     end
 
     def run(opts = nil)
-      command = File.directory?('spec') ? 'rspec spec/' : 'cucumber features'
-      system "#{command} #{opts}"
+      system "rspec spec/ #{opts}"
     end
 
     def parallel_run(opts = nil, _settings = nil)
-      command = File.directory?('spec') ? 'parallel_rspec spec/' : 'parallel_cucumber features'
-      system "#{command} #{opts}"
+      system "parallel_rspec spec/ #{opts}"
     end
 
     private

data/lib/version

@@ -1 +1 @@
-3.13.0
+4.0.0

data/ruby_raider.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |s|
   s.bindir = 'bin'
   s.executables << 'raider'
   s.add_development_dependency 'bundler-audit', '~> 0.9'
+  s.add_development_dependency 'chunky_png', '~> 1.4'
   s.add_development_dependency 'rake', '~> 13.0.6'
   s.add_development_dependency 'reek', '~> 6.5'
   s.add_development_dependency 'rspec', '~> 3.11.0'
@@ -22,9 +23,9 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rubocop-rspec', '~> 2.9.0'
   s.add_development_dependency 'ruby_audit', '~> 3.1'
   s.add_development_dependency 'rubyzip', '>= 2.3', '< 4'
-  s.add_development_dependency 'selenium-webdriver', '~> 4.0'
   s.add_development_dependency 'steep', '~> 1.9'
 
+  s.add_runtime_dependency 'selenium-webdriver', '>= 4.30', '< 5'
   s.add_runtime_dependency 'thor', '~> 1.2.1'
   s.add_runtime_dependency 'tty-prompt', '~> 0.23.1'
 end

data/sig/commands/scaffolding_commands.rbs

@@ -1,10 +1,8 @@
 # Type definitions for ScaffoldingCommands
 class ScaffoldingCommands < Thor
   def page: (String name) -> void
-  def feature: (String name) -> void
   def spec: (String name) -> void
   def helper: (String name) -> void
-  def steps: (String name) -> void
   def component: (String name) -> void
   def scaffold: (*String names) -> void
 

data/sig/commands/utility_commands.rbs

@@ -4,6 +4,8 @@ class UtilityCommands < Thor
   def url: (String default_url) -> void
   def browser: (?String? default_browser) -> void
   def browser_options: (*String opts) -> void
+  def strict: (String toggle) -> void
+  def actionability: (String toggle) -> void
   def raid: () -> void
   def timeout: (String seconds) -> void
   def viewport: (String dimensions) -> void
@@ -16,4 +18,8 @@ class UtilityCommands < Thor
   def video_toggle: (bool enabled) -> void
   def trace: (String action) -> void
   def trace_toggle: (bool enabled) -> void
+
+  private
+
+  def on?: (String toggle) -> bool
 end