watir 1.4.1 → 7.3.0

data/lib/watir/search_context.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Watir
+  module SearchContext
+    #
+    # Returns true if element exists.
+    # Checking for staleness is deprecated
+    #
+    # @return [Boolean]
+    #
+
+    def exists?
+      if located? && stale?
+        reset!
+      elsif located?
+        return true
+      end
+
+      assert_exists
+      true
+    rescue Exception::UnknownObjectException, Exception::UnknownFrameException
+      false
+    end
+    alias exist? exists?
+
+    def assert_exists
+      locate unless located?
+      return if located?
+
+      raise unknown_exception, "unable to locate: #{inspect}"
+    end
+
+    def wait_for_exists
+      return if located? # Performance shortcut
+
+      begin
+        @query_scope.wait_for_exists unless @query_scope.is_a? Browser
+        wait_until(element_reset: true, &:exists?)
+      rescue Wait::TimeoutError
+        msg = "timed out after #{Watir.default_timeout} seconds, waiting for #{inspect} to be located"
+        raise unknown_exception, msg
+      end
+    end
+
+    # TODO: - this will get addressed with Watir::Executor implementation
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength # : # ::
+    def element_call(precondition = nil, &block)
+      caller = caller_locations(1, 1)[0].label
+      already_locked = browser.timer.locked?
+      browser.timer = Wait::Timer.new(timeout: Watir.default_timeout) unless already_locked
+
+      begin
+        check_condition(precondition, caller)
+        Watir.logger.debug "-> `Executing #{inspect}##{caller}`"
+        yield
+      rescue unknown_exception => e
+        element_call(:wait_for_exists, &block) if precondition.nil?
+        raise unknown_exception, e.message + custom_message
+      rescue Selenium::WebDriver::Error::StaleElementReferenceError, Selenium::WebDriver::Error::NoSuchElementError
+        reset!
+        retry
+        # TODO: - InvalidElementStateError is deprecated, so no longer calling `raise_disabled`
+        # need a better way to handle this
+      rescue Selenium::WebDriver::Error::ElementNotInteractableError
+        raise_present unless browser.timer.remaining_time.positive?
+        raise_present unless %i[wait_for_present wait_for_enabled wait_for_writable].include?(precondition)
+        retry
+      rescue Selenium::WebDriver::Error::NoSuchWindowError
+        raise Exception::NoMatchingWindowFoundException, 'browser window was closed'
+      ensure
+        Watir.logger.debug "<- `Completed #{inspect}##{caller}`"
+        browser.timer.reset! unless already_locked
+      end
+    end
+
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
+    def check_condition(condition, caller)
+      Watir.logger.debug "<- `Verifying precondition #{inspect}##{condition} for #{caller}`"
+      begin
+        condition.nil? ? assert_exists : send(condition)
+        Watir.logger.debug "<- `Verified precondition #{inspect}##{condition || 'assert_exists'}`"
+      rescue unknown_exception
+        raise unless condition.nil?
+
+        Watir.logger.debug "<- `Unable to satisfy precondition #{inspect}##{condition}`"
+        check_condition(:wait_for_exists, caller)
+      end
+    end
+
+    def unknown_exception
+      Exception::UnknownObjectException
+    end
+  end
+end

data/lib/watir/shadow_root.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Watir
+  class ShadowRoot
+    include Container
+    include Exception
+    include SearchContext
+    include Waitable
+
+    def initialize(element)
+      @query_scope = element
+    end
+
+    def browser
+      @query_scope.browser
+    end
+
+    def located?
+      !!@shadow_root
+    end
+
+    def wd
+      assert_exists
+      @shadow_root
+    end
+
+    def execute_script(script, *args, function_name: nil)
+      browser.execute_script(script, *args, function_name: function_name)
+    end
+
+    def stale?
+      @shadow_root.find_elements(css: 'checking_stale_shadow_root')
+      false
+    rescue Selenium::WebDriver::Error::DetachedShadowRootError
+      true
+    end
+
+    def reset!
+      @shadow_root = nil
+    end
+
+    def locate
+      @shadow_root = @query_scope.wd.shadow_root
+    rescue Selenium::WebDriver::Error::NoSuchShadowRootError
+      nil
+    end
+
+    #
+    # @api private
+    #
+
+    def selector_string
+      "#{@query_scope.selector_string} --> shadow_root"
+    end
+
+    def custom_message
+      ''
+    end
+  end
+end

data/lib/watir/user_editable.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Watir
+  module UserEditable
+    #
+    # Clear the element, then type in the given value.
+    #
+    # @param [String, Symbol] args
+    #
+
+    def set(*args)
+      element_call(:wait_for_writable) do
+        @element.clear
+        @element.send_keys(*args)
+      end
+    end
+    alias value= set
+
+    #
+    # Returns true if element is user_editable because it has a content_editable attribute set
+    #
+    # @return [Boolean]
+    #
+
+    def content_editable
+      defined?(@content_editable) && content_editable?
+    end
+
+    #
+    # Uses JavaScript to enter most of the given value.
+    # Selenium is used to enter the first and last characters
+    # This might provide a performance improvement when entering a lot of text on a local machine
+    #
+    # @param [String, Symbol] args
+    #
+
+    def set!(*args)
+      msg = '#set! does not support special keys, use #set instead'
+      raise ArgumentError, msg if args.any?(::Symbol)
+
+      input_value = args.join
+      set input_value[0]
+      return content_editable_set!(*args) if content_editable
+
+      element_call { execute_js(:setValue, @element, input_value[0..-2]) }
+      append(input_value[-1])
+      return if value == input_value
+
+      raise Exception::Error, "#set! value: '#{value}' does not match expected input: '#{input_value}'"
+    end
+
+    #
+    # Appends the given value to the text in the text field.
+    #
+    # @param [String, Symbol] args
+    #
+
+    def append(*args)
+      raise NotImplementedError, '#append method is not supported with contenteditable element' if content_editable
+
+      send_keys(*args)
+    end
+    alias << append
+
+    #
+    # Clears the text field.
+    #
+
+    def clear
+      element_call(:wait_for_writable) do
+        @element.clear
+      end
+    end
+
+    private
+
+    def content_editable_set!(*args)
+      input_text = args.join
+      element_call { execute_js(:setText, @element, input_text) }
+      return if text == input_text
+
+      raise Exception::Error, "#set! text: '#{text}' does not match expected input: '#{input_text}'"
+    end
+  end # UserEditable
+end # Watir

data/lib/watir/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Watir
+  VERSION = '7.3.0'
+end

data/lib/watir/wait/timer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Watir
+  module Wait
+    class Timer
+      def initialize(timeout: nil)
+        @end_time = timeout ? current_time + timeout : nil
+        @remaining_time = @end_time - current_time if @end_time
+      end
+
+      #
+      # Executes given block until it returns true or exceeds timeout.
+      # @param [Integer] timeout
+      # @yield block
+      # @api private
+      #
+
+      def wait(timeout, &block)
+        end_time = @end_time || (current_time + timeout)
+        loop do
+          yield(block)
+          @remaining_time = end_time - current_time
+          break if @remaining_time.negative?
+        end
+      end
+
+      def remaining_time
+        @end_time - current_time
+      end
+
+      def reset!
+        @end_time = nil
+      end
+
+      def locked?
+        !@end_time.nil?
+      end
+
+      private
+
+      if defined?(Process::CLOCK_MONOTONIC)
+        def current_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      else
+        def current_time
+          ::Time.now.to_f
+        end
+      end
+    end # Timer
+  end # Wait
+end # Watir

data/lib/watir/wait.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'watir/wait/timer'
+
+module Watir
+  module Wait
+    class TimeoutError < StandardError; end
+
+    INTERVAL = 0.1
+
+    class << self
+      #
+      # @!attribute timer
+      #   Access Watir timer implementation in use.
+      #   @see Timer
+      #   @return [#wait]
+      #
+
+      attr_writer :timer
+
+      def timer
+        @timer ||= Timer.new
+      end
+
+      #
+      # Waits until the block evaluates to true or times out.
+      #
+      # @example
+      #   Watir::Wait.until { browser.text_field(name: "new_user_first_name").visible? }
+      #
+      # @param [Integer] timeout How long to wait in seconds
+      # @param [String] message Message to raise if timeout is exceeded
+      # @param [Object, NilClass] object Object to evaluate block against
+      # @raise [TimeoutError] if timeout is exceeded
+      #
+
+      def until(timeout: nil, message: nil, interval: nil, object: nil)
+        timeout ||= Watir.default_timeout
+        run_with_timer(timeout, interval) do
+          result = yield(object)
+          return result if result
+        end
+        raise TimeoutError, message_for(timeout, object, message)
+      end
+
+      #
+      # Wait while the block evaluates to true or times out.
+      #
+      # @example
+      #   Watir::Wait.while { browser.text_field(name: "abrakadbra").present? }
+      #
+      # @param [Integer] timeout How long to wait in seconds
+      # @param [String] message Message to raise if timeout is exceeded
+      # @param [Object, NilClass] object Object to evaluate block against
+      # @raise [TimeoutError] if timeout is exceeded
+      #
+
+      def while(timeout: nil, message: nil, interval: nil, object: nil)
+        timeout ||= Watir.default_timeout
+        run_with_timer(timeout, interval) { return unless yield(object) }
+        raise TimeoutError, message_for(timeout, object, message)
+      end
+
+      private
+
+      def message_for(timeout, object, message)
+        message = message.is_a?(Proc) ? message.call(object) : message || ''
+        additional = message.empty? ? '' : ", #{message}"
+        "timed out after #{timeout} seconds#{additional}"
+      end
+
+      def run_with_timer(timeout, interval)
+        if timeout.zero?
+          yield
+        else
+          timer.wait(timeout) do
+            yield
+            sleep interval || INTERVAL
+          end
+        end
+      end
+    end # self
+  end # Wait
+
+  module Waitable
+    #
+    # Waits until the condition is true.
+    #
+    # @example
+    #   browser.wait_until(timeout: 2) do |browser|
+    #     browser.windows.size == 1
+    #   end
+    #
+    # @example
+    #   browser.text_field(name: "new_user_first_name").wait_until(&:present?).click
+    #   browser.text_field(name: "new_user_first_name").wait_until(message: 'foo') { |field| field.present? }
+    #   browser.text_field(name: "new_user_first_name").wait_until(timeout: 60, &:present?)
+    #   browser.text_field(name: "new_user_first_name").wait_until(timeout: 60, name: 'new_user_first_name')
+    #
+    # @param [Integer] timeout seconds to wait before timing out
+    # @param [String] message error message for when times out
+    #
+
+    def wait_until(timeout: nil, message: nil, interval: nil, **opt, &blk)
+      message ||= proc { |obj| "waiting for true condition on #{obj.inspect}" }
+
+      # TODO: Consider throwing argument error for mixing block & options
+      proc = create_proc(opt, &blk)
+
+      Wait.until(timeout: timeout, message: message, interval: interval, object: self, &proc)
+
+      self
+    end
+
+    #
+    # Waits while the condition is true.
+    #
+    # @example
+    #   browser.wait_while(timeout: 2) do |browser|
+    #     !browser.exists?
+    #   end
+    #   browser.wait_while(timeout: 2, title: 'No')
+    #
+    # @todo add element example
+    #
+    # @param [Integer] timeout seconds to wait before timing out
+    # @param [String] message error message for when times out
+    #
+
+    def wait_while(timeout: nil, message: nil, interval: nil, **opt, &blk)
+      message ||= proc { |obj| "waiting for false condition on #{obj.inspect}" }
+
+      # TODO: Consider throwing argument error for mixing block & options
+      proc = create_proc(opt, &blk)
+
+      Wait.while(timeout: timeout, message: message, interval: interval, object: self, &proc)
+
+      self
+    end
+
+    private
+
+    def create_proc(opt)
+      proc do
+        reset! if opt.delete(:element_reset) && is_a?(Element)
+        (opt.empty? || match_attributes(opt).call) && (!block_given? || yield(self))
+      end
+    end
+
+    def match_attributes(opt)
+      proc do
+        opt.keys.all? do |key|
+          expected = opt[key]
+          actual = if is_a?(Element) && !respond_to?(key)
+                     attribute_value(key)
+                   else
+                     send(key)
+                   end
+          case expected
+          when Regexp
+            expected =~ actual
+          when Numeric
+            expected == actual
+          else
+            expected.to_s == actual
+          end
+        end
+      end
+    end
+  end # Waitable
+end # Watir