watir 1.4.1 → 7.3.0

data/lib/watir/aliases.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Watir
+  module Container
+    alias field_set fieldset
+    alias field_sets fieldsets
+  end # Container
+end # Watir

data/lib/watir/attribute_helper.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Watir
+  #
+  # @private
+  #
+  # Extended by Element, provides methods for defining attributes on the element classes.
+  #
+
+  module AttributeHelper
+    class << self
+      private
+
+      def extended(klass)
+        klass.class_eval do
+          # undefine deprecated methods to use them for Element attributes
+          %i[id type].each { |m| undef_method m if method_defined? m }
+        end
+      end
+    end
+
+    def inherit_attributes_from(kls)
+      kls.typed_attributes.each do |type, attrs|
+        attrs.each { |method, attr| attribute type, method, attr }
+      end
+    end
+
+    def typed_attributes
+      @typed_attributes ||= Hash.new { |hash, type| hash[type] = [] }
+    end
+
+    def attribute_list
+      @attribute_list ||= (typed_attributes.values.flatten +
+                           ancestors[1..].filter_map { |e|
+                             e.attribute_list if e.respond_to?(:attribute_list)
+                           }.flatten
+                          ).uniq
+    end
+
+    alias attributes attribute_list
+
+    #
+    # YARD macro to generated friendly
+    # documentation for attributes.
+    #
+    # @macro [attach] attribute
+    #  @method $2
+    #  @return [$1] value of $3 property
+    #
+    def attribute(type, method, attr)
+      return if method_defined?(method)
+
+      typed_attributes[type] << [method, attr]
+      define_attribute(type, method, attr)
+    end
+
+    def define_attribute(type, name, attr)
+      case type.to_s
+      when 'Boolean'
+        define_boolean_attribute(name, attr)
+      when 'Integer'
+        define_int_attribute(name, attr)
+      when 'Float'
+        define_float_attribute(name, attr)
+      else
+        define_string_attribute(name, attr)
+      end
+    end
+
+    def define_string_attribute(mname, aname)
+      define_method mname do
+        attribute_value(aname).to_s
+      end
+    end
+
+    def define_boolean_attribute(mname, aname)
+      define_method mname do
+        attribute_value(aname) == 'true'
+      end
+    end
+
+    def define_int_attribute(mname, aname)
+      define_method mname do
+        value = attribute_value(aname)
+        value && Integer(value)
+      end
+    end
+
+    def define_float_attribute(mname, aname)
+      define_method mname do
+        value = attribute_value(aname)
+        value = nil if value == 'NaN'
+        value && Float(value)
+      end
+    end
+  end # AttributeHelper
+end # Watir

data/lib/watir/browser.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+module Watir
+  #
+  # The main class through which you control the browser.
+  #
+
+  class Browser
+    include Container
+    include HasWindow
+    include Waitable
+    include Navigation
+    include Exception
+    include Scrolling
+
+    attr_writer :default_context, :original_window, :locator_namespace, :timer
+    attr_reader :driver, :after_hooks, :capabilities
+    alias wd driver # ensures duck typing with Watir::Element
+
+    class << self
+      #
+      # Creates a Watir::Browser instance and goes to URL.
+      #
+      # @example
+      #   browser = Watir::Browser.start "www.google.com", :chrome
+      #   #=> #<Watir::Browser:0x..fa45a499cb41e1752 url="http://www.google.com" title="Google">
+      #
+      # @param [String] url
+      # @param [Symbol, Selenium::WebDriver] browser :firefox, :ie, :chrome, :remote or Selenium::WebDriver instance
+      # @return [Watir::Browser]
+      #
+      def start(url, browser = :chrome, *args)
+        new(browser, *args).tap { |b| b.goto url }
+      end
+    end
+
+    #
+    # Creates a Watir::Browser instance.
+    #
+    # @param [Symbol, Selenium::WebDriver] browser :firefox, :ie, :chrome, :remote or Selenium::WebDriver instance
+    # @param args Passed to the underlying driver
+    #
+
+    def initialize(browser = :chrome, *args)
+      @capabilities = browser.is_a?(Capabilities) ? browser : Capabilities.new(browser, *args)
+      @driver = browser.is_a?(Selenium::WebDriver::Driver) ? browser : Selenium::WebDriver.for(*@capabilities.to_args)
+
+      @after_hooks = AfterHooks.new(self)
+      @closed = false
+      @default_context = true
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def inspect
+      if alert.exists?
+        format('#<%<class>s:0x%<hash>x alert=true>', class: self.class, hash: hash * 2)
+      else
+        format('#<%<class>s:0x%<hash>x url=%<url>s title=%<title>s>',
+               class: self.class, hash: hash * 2, url: url.inspect, title: title.inspect)
+      end
+    rescue Selenium::WebDriver::Error::NoSuchWindowError
+      format('#<%<class>s:0x%<hash>x closed=%<closed>s>',
+             class: self.class, hash: hash * 2, closed: closed?)
+    rescue Errno::ECONNREFUSED
+      format('#<%<class>s:0x%<hash>x closed=true>', class: self.class, hash: hash * 2)
+    end
+    alias selector_string inspect
+    # rubocop:enable Metrics/AbcSize
+
+    #
+    # Returns URL of current page.
+    #
+    # @example
+    #   browser.goto "watir.com"
+    #   browser.url
+    #   #=> "http://watir.com/"
+    #
+    # @return [String]
+    #
+
+    def url
+      @driver.current_url
+    end
+
+    #
+    # Returns title of current page.
+    #
+    # @example
+    #   browser.goto "watir.github.io"
+    #   browser.title
+    #   #=> "Watir Project"
+    #
+    # @return [String]
+    #
+
+    def title
+      @driver.title
+    end
+
+    #
+    # Closes browser.
+    #
+
+    def close
+      return if closed?
+
+      @driver.quit
+      @closed = true
+    end
+    alias quit close
+
+    #
+    # Returns true if browser is closed and false otherwise.
+    #
+    # @return [Boolean]
+    #
+
+    def closed?
+      @closed
+    end
+
+    #
+    # Handles cookies.
+    #
+    # @return [Watir::Cookies]
+    #
+
+    def cookies
+      @cookies ||= Cookies.new driver.manage
+    end
+
+    #
+    # Returns browser name.
+    #
+    # @example
+    #   browser = Watir::Browser.new :chrome
+    #   browser.name
+    #   #=> :chrome
+    #
+    # @return [Symbol]
+    #
+
+    def name
+      @driver.browser
+    end
+
+    #
+    # Returns text of page body.
+    #
+    # @return [String]
+    #
+
+    def text
+      body.text
+    end
+
+    #
+    # Returns HTML code of current page.
+    #
+    # @return [String]
+    #
+
+    def html
+      @driver.page_source
+    end
+
+    #
+    # Handles JavaScript alerts, confirms and prompts.
+    #
+    # @return [Watir::Alert]
+    #
+
+    def alert
+      Alert.new(self)
+    end
+
+    #
+    # Waits until readyState of document is complete.
+    #
+    # @example
+    #   browser.wait
+    #
+    # @param [Integer] timeout
+    # @raise [Watir::Wait::TimeoutError] if timeout is exceeded
+    #
+
+    def wait(timeout = 5)
+      wait_until(timeout: timeout, message: "waiting for document.readyState == 'complete'") do
+        ready_state == 'complete'
+      end
+    end
+
+    #
+    # Returns readyState of document.
+    #
+    # @return [String]
+    #
+
+    def ready_state
+      execute_script 'return document.readyState'
+    end
+
+    #
+    # Returns the text of status bar.
+    #
+    # @return [String]
+    #
+
+    def status
+      execute_script 'return window.status;'
+    end
+
+    #
+    # Executes JavaScript snippet.
+    #
+    # If you are going to use the value snippet returns, make sure to use
+    # `return` explicitly.
+    #
+    # @example Check that Ajax requests are completed with jQuery
+    #   browser.execute_script("return jQuery.active") == 0
+    #   #=> true
+    #
+    # @param [String] script JavaScript snippet to execute
+    # @param args Arguments will be available in the given script in the 'arguments' pseudo-array
+    #
+
+    def execute_script(script, *args, function_name: nil)
+      args.map! do |e|
+        e.is_a?(Element) ? e.wait_until(&:exists?).wd : e
+      end
+      Watir.logger.info "Executing Script on Browser: #{function_name}" if function_name
+      wrap_elements_in(self, @driver.execute_script(script, *args))
+    end
+
+    #
+    # Sends sequence of keystrokes to currently active element.
+    #
+    # @example
+    #   browser.goto "www.google.com"
+    #   browser.send_keys "Watir", :return
+    #
+    # @param [String, Symbol] args
+    #
+
+    def send_keys(*args)
+      @driver.switch_to.active_element.send_keys(*args)
+    end
+
+    #
+    # Handles screenshots of current pages.
+    #
+    # @return [Watir::Screenshot]
+    #
+
+    def screenshot
+      Screenshot.new self
+    end
+
+    #
+    # Returns true if browser is not closed and false otherwise.
+    #
+    # @return [Boolean]
+    #
+
+    def exist?
+      !closed? && window.present?
+    end
+    alias exists? exist?
+
+    def locate
+      raise Error, 'browser was closed' if closed?
+
+      ensure_context
+    end
+
+    def ensure_context
+      return if @default_context
+
+      driver.switch_to.default_content
+      @default_context = true
+    end
+
+    def browser
+      self
+    end
+
+    #
+    # Whether the locators should be used from a different namespace.
+    # Defaults to Watir::Locators.
+    #
+
+    def locator_namespace
+      @locator_namespace ||= Locators
+    end
+
+    #
+    # @api private
+    #
+
+    def wrap_elements_in(scope, obj)
+      case obj
+      when Selenium::WebDriver::Element
+        wrap_element(scope, obj)
+      when Array
+        obj.map { |e| wrap_elements_in(scope, e) }
+      when Hash
+        obj.each { |k, v| obj[k] = wrap_elements_in(scope, v) }
+      else
+        obj
+      end
+    end
+
+    def timer
+      @timer ||= Wait::Timer.new
+    end
+
+    private
+
+    def wrap_element(scope, element)
+      Watir.element_class_for(element.tag_name.downcase).new(scope, element: element)
+    end
+  end # Browser
+end # Watir

data/lib/watir/capabilities.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Watir
+  class Capabilities
+    attr_reader :options, :selenium_browser, :selenium_args
+
+    def initialize(browser = nil, options = {})
+      @options, @browser = case browser
+                           when Selenium::WebDriver::Driver
+                             return
+                           when ::Symbol, String
+                             [options.dup, browser&.to_sym]
+                           when Hash
+                             [browser.dup, infer_browser(browser)]
+                           when nil
+                             [{}, infer_browser]
+                           else
+                             raise ArgumentError,
+                                   "expected Driver, String, Symbol or Hash, but received: #{browser.class}"
+                           end
+      validate_options
+
+      @selenium_browser = @options.key?(:url) ? :remote : @browser
+    end
+
+    def to_args
+      Watir.logger.info "Creating Browser instance of #{@browser} with user provided options: #{@options.inspect}"
+      @selenium_args = process_arguments
+      raise ArgumentError, "#{@options} are unrecognized arguments for Browser constructor" unless @options.empty?
+
+      Watir.logger.info "Selenium options generated by Watir: #{@selenium_args.inspect}"
+      [@selenium_browser, @selenium_args]
+    end
+
+    private
+
+    def process_arguments
+      selenium_opts = {}
+      selenium_opts[:listener] = @options.delete(:listener) if @options.key?(:listener)
+
+      if @options.key?(:url)
+        selenium_opts[:url] = @options.delete(:url)
+      else
+        service = process_service
+        selenium_opts[:service] = service if service
+      end
+
+      selenium_opts[:http_client] = process_http_client
+      if @options.key?(:capabilities)
+        Watir.logger.deprecate(':capabilities argument in Browser constructor',
+                               ':options argument with Selenium Options instance or Hash',
+                               id: :capabilities)
+        selenium_opts[:capabilities] = @options.delete(:capabilities)
+      else
+        selenium_opts[:options] = process_browser_options
+      end
+
+      selenium_opts
+    end
+
+    def process_http_client
+      http_client = @options.delete(:http_client) || Watir::HttpClient.new
+
+      case http_client
+      when Hash
+        Watir::HttpClient.new(**http_client)
+      when Watir::HttpClient
+        http_client
+      when Selenium::WebDriver::Remote::Http::Common
+        Watir.logger.warn 'Check out the new Watir::HttpClient and let us know if there are missing features you need',
+                          id: [:watir_client]
+        http_client
+      else
+        raise TypeError, ':http_client must be a Hash or a Selenium HTTP Client instance'
+      end
+    end
+
+    def process_browser_options
+      browser_options = @options.delete(:options).dup || {}
+
+      options = if browser_options.is_a? Selenium::WebDriver::Options
+                  browser_options
+                else
+                  convert_timeouts(browser_options)
+                  Selenium::WebDriver::Options.send(@browser, **browser_options)
+                end
+
+      options.unhandled_prompt_behavior ||= :ignore
+      process_proxy_options(options)
+      browser_specific_options(options)
+
+      options
+    end
+
+    def process_proxy_options(options)
+      proxy = @options.delete(:proxy)
+      return if proxy.nil?
+
+      proxy &&= Selenium::WebDriver::Proxy.new(proxy) if proxy.is_a?(Hash)
+
+      unless proxy.is_a?(Selenium::WebDriver::Proxy)
+        raise TypeError, "#{proxy} needs to be Selenium Proxy or Hash instance"
+      end
+
+      options.proxy = proxy
+    end
+
+    def convert_timeouts(browser_options)
+      browser_options[:timeouts] ||= {}
+      browser_options[:timeouts].each_key do |key|
+        raise(ArgumentError, 'do not set implicit wait, Watir handles waiting automatically') if key.to_s == 'implicit'
+
+        Watir.logger.deprecate('using timeouts directly in options',
+                               ":#{key}_timeout",
+                               id: :timeouts)
+      end
+      if browser_options.key?(:page_load_timeout)
+        browser_options[:timeouts][:page_load] = browser_options.delete(:page_load_timeout) * 1000
+      end
+
+      return unless browser_options.key?(:script_timeout)
+
+      browser_options[:timeouts][:script] = browser_options.delete(:script_timeout) * 1000
+    end
+
+    def browser_specific_options(options)
+      case @browser
+      when :chrome, :edge, :microsoftedge
+        if @options.delete(:headless)
+          options.args << '--headless'
+          options.args << '--disable-gpu'
+          options.args << '--no-sandbox'
+        end
+      when :firefox
+        options.args << '-headless' if @options.delete(:headless)
+      when :safari
+        Selenium::WebDriver::Safari.technology_preview! if @options.delete(:technology_preview)
+      end
+    end
+
+    def process_service
+      service = @options.delete(:service)
+
+      case service
+      when nil
+        nil
+      when Hash
+        return if service.empty?
+
+        Selenium::WebDriver::Service.send(@browser, **service)
+      when Selenium::WebDriver::Service
+        service
+      else
+        raise TypeError, "#{service} needs to be Selenium Service or Hash instance"
+      end
+    end
+
+    def infer_browser(options = nil)
+      options ||= {}
+      inferred = if options.key?(:capabilities)
+                   options[:capabilities].browser_name.tr(' ', '_').downcase.to_sym
+                 elsif options[:options].is_a?(Selenium::WebDriver::Options)
+                   options[:options].class.to_s.split('::')[-2].downcase.to_sym
+                 elsif options.key?(:options)
+                   options.dig(:options, :browser_name).tr(' ', '_').downcase.to_sym
+                 else
+                   :chrome
+                 end
+      %i[msedge microsoftedge].include?(inferred) ? :edge : inferred
+    end
+
+    def validate_options
+      if @options.key?(:capabilities) && @options.key?(:options)
+        raise(ArgumentError, ':capabilities and :options are not both allowed')
+      end
+      raise(ArgumentError, ':url and :service are not both allowed') if @options.key?(:service) && @options.key?(:url)
+    end
+  end
+end

data/lib/watir/cell_container.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Watir
+  module CellContainer
+    #
+    # Returns table cell.
+    #
+    # @return [Cell]
+    #
+
+    def cell(opts = {})
+      Cell.new(self, opts)
+    end
+
+    #
+    # Returns table cells collection.
+    #
+    # @return [Cell]
+    #
+
+    def cells(opts = {})
+      CellCollection.new(self, opts)
+    end
+  end # CellContainer
+end # Watir

data/lib/watir/container.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Watir
+  module Container
+    include JSSnippets
+
+    #
+    # Returns element.
+    #
+    # @example
+    #   browser.element(data_bind: 'func')
+    #
+    # @return [HTMLElement]
+    #
+
+    def element(opts = {})
+      HTMLElement.new(self, opts)
+    end
+
+    #
+    # Returns element collection.
+    #
+    # @example
+    #   browser.elements(data_bind: 'func')
+    #
+    # @return [HTMLElementCollection]
+    #
+
+    def elements(opts = {})
+      HTMLElementCollection.new(self, opts)
+    end
+  end # Container
+end # Watir