ruby_raider 3.12.1 → 3.13.0

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

@@ -28,6 +28,29 @@ module WaitHelper
   CONFIG_FILE = 'config/config.yml'
   DEFAULT_TIMEOUT = 10
 
+  class << self
+    # Follows every action and eventually when set (the trace helper does). Optional:
+    # nothing is called on it while nil, and one that raises is dropped.
+    attr_accessor :observer
+
+    # Calls the observer's hook, or returns nil without one. A broken observer must
+    # never fail a test: it is warned about once and removed.
+    # A block builds the details, so computing them is covered by the same rescue.
+    # $stderr.puts, not Kernel#warn: warn is silenced under -W0.
+    # rubocop:disable Style/StderrPuts
+    def report(hook, *args, **details)
+      current = observer
+      return unless current
+
+      details = yield if block_given?
+      current.public_send(hook, *args, **details)
+    rescue StandardError => e
+      $stderr.puts("[trace] observer stopped: #{e.class}: #{e.message}")
+      self.observer = nil
+    end
+    # rubocop:enable Style/StderrPuts
+  end
+
   def self.default_timeout
     @default_timeout ||= begin
       config = File.exist?(CONFIG_FILE) ? YAML.load_file(CONFIG_FILE) : nil
@@ -128,6 +151,9 @@ module WaitHelper
 
     attr_reader :hint
 
+    # Selenium's aliases for the locator strategies, as the trace names them.
+    STRATEGIES = { css_selector: 'css', class: 'class_name', link: 'link_text', partial_link: 'partial_link_text' }.freeze
+
     def self.for(driver, locator, by, scope: driver)
       raise ArgumentError, 'pass the locator in braces or as keywords, not both' if locator && !by.empty?
 
@@ -204,6 +230,21 @@ module WaitHelper
       @scope.lost if @scope_stale
     end
 
+    # { strategy:, selector: } for the observer, or nil when this locates nothing.
+    def trace_locator
+      return unless @locator
+
+      strategy, selector = @locator.first
+      { strategy: STRATEGIES.fetch(strategy) { strategy.to_s }, selector: selector }
+    end
+
+    # The locators this one is searched inside, outermost first.
+    def trace_within
+      return [] unless @scope.is_a?(Lookup)
+
+      [*@scope.trace_within, @scope.trace_locator].compact
+    end
+
     def describe
       return 'the element' unless @locator
 
@@ -289,13 +330,66 @@ module WaitHelper
     # 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)
+    # args: what the action acts with (send_keys' keys, select_by's how and what), for the observer.
+    def perform_action(action, locator, checks, target: nil, between: nil, args: nil, &block)
       lookup = locator.is_a?(Lookup) ? locator : Lookup.for(@driver, locator, {})
+      return poll(action, lookup, checks, target, between, nil, &block) unless WaitHelper.observer
+
+      observed(action, lookup, args) { |run| poll(action, lookup, checks, target, between, run, &block) }
+    end
+
+    # Retries the block until it passes. Calls inside it share its deadline (see deadline_and_wait).
+    def eventually(&block)
+      return retry_block(nil, &block) unless WaitHelper.observer
+
+      token = WaitHelper.report(:group_started) { { action: :eventually, source: Observation.source } }
+      run = { retries: 0, token: token }
+      begin
+        result = retry_block(run, &block)
+        WaitHelper.report(:group_finished, token, status: :passed, retries: run[:retries], error: nil) if token
+        result
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        WaitHelper.report(:group_finished, token, status: :failed, retries: run[:retries], error: e) if token
+        raise
+      end
+    end
+
+    private
+
+    # Tells the observer an action started, when its element is ready and how it ended. The
+    # block gets a run hash that poll fills with the retries it took and the ready element.
+    def observed(action, lookup, args)
+      run = { retries: 0, element: nil, token: nil }
+      token = run[:token] = WaitHelper.report(:action_started) do
+        { action: action, locator: lookup.trace_locator, within: lookup.trace_within,
+          source: Observation.source, args: args }
+      end
+      started = now
+      begin
+        result = yield(run)
+        finished(token, :passed, started, run, nil)
+        result
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        finished(token, :failed, started, run, e)
+        raise
+      end
+    end
+
+    def finished(token, status, started, run, error)
+      return unless token
+
+      WaitHelper.report(:action_finished, token, status: status, waited_ms: ((now - started) * 1000).round,
+                                                 retries: run[:retries], error: error, element: run[:element])
+    end
+
+    # run: where to count retries and keep the ready element, or nil when nobody observes.
+    def poll(action, lookup, checks, target, between, run)
       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
+          ready_to_act(run, elements.first) if run
           return yield(*elements)
         rescue *RETRIED => e
           retry_reason(lookup, e, action)
@@ -307,12 +401,19 @@ module WaitHelper
           raise TimeoutError, timeout_message(lookup, checks, seen, [waited, waited + now - deadline].min), backtrace
         end
 
+        run[:retries] += 1 if run
         pause(deadline)
       end
     end
 
-    # Retries the block until it passes. Calls inside it share its deadline (see deadline_and_wait).
-    def eventually
+    # Keeps the ready element and tells the observer, just before the action runs on it.
+    def ready_to_act(run, element)
+      run[:element] = element
+      token = run[:token]
+      WaitHelper.report(:action_ready, token, element: element) if token
+    end
+
+    def retry_block(run)
       enclosing = Thread.current[DEADLINE_KEY]
       require 'rspec/expectations'
       retried = [RSpec::Expectations::ExpectationNotMetError, Selenium::WebDriver::Error::NoSuchElementError,
@@ -324,13 +425,21 @@ module WaitHelper
       rescue *retried => e
         raise e.exception("(still failing after #{seconds(waited)}s)\n#{e.message}") if now >= deadline
 
+        retried(run, e)
         pause(deadline)
       end
     ensure
       Thread.current[DEADLINE_KEY] = enclosing
     end
 
-    private
+    # Counts a failed pass of eventually, and tells the observer a new pass starts.
+    def retried(run, error)
+      return unless run
+
+      run[:retries] += 1
+      token = run[:token]
+      WaitHelper.report(:group_retried, token, error: error) if token
+    end
 
     # 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.
@@ -405,6 +514,38 @@ module WaitHelper
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end
+
+  # Where an action was called from, for the observer.
+  module Observation
+    # helpers/ by its given and its real path (__dir__ is the real one): the wait, trace and
+    # driver helpers are never the line that called an action or a navigation.
+    HELPER_DIRS = [File.dirname(__FILE__), __dir__].uniq.map { |dir| File.join(dir, '') }.freeze
+
+    # The first frame outside helpers/, Ruby and gems, as { file:, line: } (file relative
+    # to the working directory when inside it), or nil.
+    def self.source
+      frame = caller_locations.find { |location| project?(location.absolute_path || location.path) }
+      return unless frame
+
+      { file: relative(frame.absolute_path || frame.path), line: frame.lineno }
+    end
+
+    def self.project?(path)
+      return false if path.start_with?('<internal:') || HELPER_DIRS.any? { |dir| path.start_with?(dir) }
+
+      library_paths.none? { |root| path.start_with?(root) }
+    end
+
+    def self.library_paths
+      @library_paths ||= [*RbConfig::CONFIG.values_at('rubylibdir', 'rubyarchdir'), *Gem.path]
+                         .compact.map { |dir| File.join(dir, '') }
+    end
+
+    def self.relative(path)
+      root = File.join(Dir.pwd, '')
+      path.start_with?(root) ? path.delete_prefix(root) : path
+    end
+  end
 <%- if mobile? -%>
 
   # A swipe or scroll through the platform's own mobile: command, as appium_lib issues them.

data/lib/utilities/utilities.rb

@@ -75,6 +75,13 @@ module Utilities
       overwrite_yaml
     end
 
+    def trace_enabled=(enabled)
+      reload_config
+      trace = @config['trace']
+      @config['trace'] = (trace.is_a?(Hash) ? trace : {}).merge('enabled' => enabled)
+      overwrite_yaml
+    end
+
     # Set multiple config keys in a single YAML write.
     # Usage: Utilities.batch_update(browser: 'chrome', timeout: 30)
     def batch_update(**settings)

data/lib/version

@@ -1 +1 @@
-3.12.1
+3.13.0

data/ruby_raider.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rubocop-performance', '~> 1.15.0'
   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'
 

data/sig/commands/utility_commands.rbs

@@ -14,4 +14,6 @@ class UtilityCommands < Thor
   def video_install: () -> void
   def video_status: () -> void
   def video_toggle: (bool enabled) -> void
+  def trace: (String action) -> void
+  def trace_toggle: (bool enabled) -> void
 end

data/sig/generators/generator.rbs

@@ -20,6 +20,7 @@ class Generator < Thor::Group
   def selenium?: () -> bool
   def watir?: () -> bool
   def wait_helper?: () -> bool
+  def trace_helper?: () -> bool
   def examples?: () -> bool
   def web?: () -> bool
   def selenium_based?: () -> bool
@@ -27,6 +28,9 @@ class Generator < Thor::Group
   # Add-on predicates
   def axe_addon?: () -> bool
 
+  def ruby_raider_version: () -> String
+  def ruby_raider_version_requirement: () -> String
+
   private
 
   def options_after_name: () -> Array[untyped]

data/sig/generators/helper_generator.rbs

@@ -8,4 +8,5 @@ class HelpersGenerator < Generator
   def generate_spec_helper: () -> void
   def generate_driver_helper: () -> void
   def generate_appium_helper: () -> void
+  def generate_trace_helper: () -> void
 end

data/sig/utilities/utilities.rbs

@@ -14,6 +14,7 @@ module Utilities
   def self?.browser_options=: (Array[String] opts) -> void
   def self?.delete_browser_options: () -> void
   def self?.video_enabled=: (bool enabled) -> void
+  def self?.trace_enabled=: (bool enabled) -> void
   def self?.batch_update: (**untyped settings) -> void
   def self?.run: (?String? opts) -> void
   def self?.parallel_run: (?String? opts, ?untyped? _settings) -> void

data/spec/generators/fixtures/video_helper_stubs/selenium-webdriver.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Minimal stand-in for selenium-webdriver, which is not in ruby_raider's bundle.
-# spec/generators/video_helper_spec.rb puts this directory on $LOAD_PATH so the
-# rendered video_helper.rb can `require 'selenium-webdriver'`.
+# spec/generators/video_helper_spec.rb and trace_helper_spec.rb put this directory on
+# $LOAD_PATH so the rendered helpers can `require 'selenium-webdriver'`. The listener
+# lists every callback of the real Support::AbstractEventListener (4.52).
 module Selenium
   module WebDriver
     module Error
@@ -14,6 +15,10 @@ module Selenium
       class AbstractEventListener
         def before_navigate_to(url, driver) end
         def after_navigate_to(url, driver) end
+        def before_navigate_back(driver) end
+        def after_navigate_back(driver) end
+        def before_navigate_forward(driver) end
+        def after_navigate_forward(driver) end
         def before_find(by, what, driver) end
         def after_find(by, what, driver) end
         def before_click(element, driver) end
@@ -22,6 +27,10 @@ module Selenium
         def after_change_value_of(element, driver) end
         def before_execute_script(script, driver) end
         def after_execute_script(script, driver) end
+        def before_quit(driver) end
+        def after_quit(driver) end
+        def before_close(driver) end
+        def after_close(driver) end
       end
     end
   end