watir 6.18.0 → 6.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29eeb6548d5f5f91ee744107d1e3c79f0d2baf8b688c9588752e25b75fa696ef
-  data.tar.gz: 27502c2b89585471b25751b5564c08784578585d3c196f132f56b52243645735
+  metadata.gz: 249f59d4a6bd6bff5ddd7e49d32e2cc5a3ecd887586de1a41d51aecc37c6946a
+  data.tar.gz: 407024609aa1b7e0eb052ecbcc279ebdfcb6e486e326ee8f1dd0994b79f4be75
 SHA512:
-  metadata.gz: d2a90695c68c0db0493d1fdeac5ab90ab51604a0916b4b6cbf0abeae595c6680f62269da98b9920c7ee7db4448e70c6afe31caa280ae76234bae2fc0b51c2912
-  data.tar.gz: 645305ed2b0ae8b5777995c6620055e37850dcefdb3b5a5b609d98b4ce30f8d0cd14155a79fb2032a46862d8c10ad92e9c0112fc7fe68e31dac01b6da44cbbd9
+  metadata.gz: f89c38c9bd61bef959ebb41672e729be867ad7991530f6f432dddae7900db15c31dfd717d413cc500f5f2708a3ce500b3d9687091d603ca4e4acbfbbc5af20cc
+  data.tar.gz: 34f9dc6a5e675c734c4a2e5e5c234695204b23ba887268f523c95d72f33a0b5b02c843fcd61033592c8e937b721d86bc80b790e9b06c4c9ca4d03f7b55df7357

data/.github/workflows/unit.yml

@@ -18,7 +18,13 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
       - run: bundle install
-      - run: bundle exec rake spec:unit
+      - uses: ./.github/actions/install-chrome
+      - run: Xvfb :99 &
+      - run: |
+          bundle exec rake spec:unit
+        env:
+          DISPLAY: :99
+
   linter-test:
     name: Rubocop Tests
     runs-on: ubuntu-latest

data/CHANGES.md

@@ -1,3 +1,20 @@
+### 6.19.0 (2021-03-12)
+
+* Create custom Watir HTTP Client
+* Require minimum of Selenium 3.142.7
+* Add support for starting browser with :http_client and :service hashes
+* Allow inferring desired browser from Capabilities or Options if browser not specified
+* Deprecate WindowCollection#to_a method
+* Deprecate starting browser with both Capabilities and Options
+* Deprecate starting browser with both URL and Service
+* Deprecate using :desired_capabilities
+* Deprecate starting browser service keywords in top level Hash
+* Deprecate using :remote to start a browser; browser name must be specified
+* Deprecate sending unknown keywords into the top level
+* Fix bug preventing Safari Options from being recognized
+* Fix bug preventing options provided without :remote keyword from being properly recognized (#812, #870)
+* Fix bug preventing :headless from being recognized when :options specified (#692)
+
 ### 6.18.0 (2021-02-26)
 
 * Implement `WindowCollection` to manage multiple `Window` objects

data/README.md

@@ -3,12 +3,12 @@
 Watir Powered By Selenium!
 
 [![Gem Version](https://badge.fury.io/rb/watir.svg)](http://badge.fury.io/rb/watir)
-[![Unit Tests](https://github.com/titusfortner/watir/workflows/Unit%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Unit+Tests%22)
-[![Mac Tests](https://github.com/titusfortner/watir/workflows/Mac%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Mac+Tests%22)
-[![Windows Tests](https://github.com/titusfortner/watir/workflows/Windows%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Windows+Tests%22)
-[![Linux Tests](https://github.com/titusfortner/watir/workflows/Linux%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Linux+Tests%22)
+[![Unit Tests](https://github.com/watir/watir/workflows/Unit%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Unit+Tests%22)
+[![Mac Tests](https://github.com/watir/watir/workflows/Mac%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Mac+Tests%22)
+[![Windows Tests](https://github.com/watir/watir/workflows/Windows%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Windows+Tests%22)
+[![Linux Tests](https://github.com/watir/watir/workflows/Linux%20Tests/badge.svg)](https://github.com/watir/watir/actions?query=workflow%3A%22Linux+Tests%22)
 [![Code Climate](https://codeclimate.com/github/watir/watir.svg)](https://codeclimate.com/github/watir/watir)
-[![Coverage Status](https://coveralls.io/repos/github/watir/watir/badge.svg?branch=main)](https://coveralls.io/github/watir/watir?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/watir/watir/badge.svg?branch=main)](https://coveralls.io/github/watir/watir?branch=main)
 
 ## Using Watir
 

data/lib/watir.rb

@@ -14,12 +14,14 @@ require 'watir/alert'
 require 'watir/js_snippets'
 require 'watir/container'
 require 'watir/cookies'
+require 'watir/http_client'
 require 'watir/capabilities'
 require 'watir/navigation'
 require 'watir/browser'
 require 'watir/screenshot'
 require 'watir/after_hooks'
 require 'watir/logger'
+require 'watir/version'
 
 module Watir
   @relaxed_locate = true

data/lib/watir/capabilities.rb

@@ -2,18 +2,22 @@ module Watir
   class Capabilities
     attr_reader :options
 
-    def initialize(browser, options = {})
+    def initialize(browser = nil, options = {})
+      if browser.is_a?(Hash)
+        options = browser
+        browser = nil
+      end
+
       @options = options.dup
       Watir.logger.info "Creating Browser instance of #{browser} with user provided options: #{@options.inspect}"
-      @browser = if browser == :remote && @options.key?(:browser)
-                   @options.delete(:browser)
-                 elsif browser == :remote && @options.key?(:desired_capabilities)
-                   @options[:desired_capabilities].browser_name.to_sym
-                 else
-                   browser.to_sym
-                 end
-      @selenium_browser = browser == :remote || options[:url] ? :remote : browser
 
+      deprecate_options_capabilities
+      deprecate_desired_capabilities
+      deprecate_url_service if @options.key?(:service) && @options.key?(:url)
+
+      @browser = deprecate_remote(browser) || browser.nil? && infer_browser || browser.to_sym
+
+      @selenium_browser = options[:url] ? :remote : @browser
       @selenium_opts = {}
     end
 
@@ -24,19 +28,15 @@ module Watir
     private
 
     def process_arguments
-      url = @options.delete(:url)
-      if url
-        @selenium_opts[:url] = url
-      elsif @options.key?(:service)
-        @selenium_opts[:service] = options.delete(:service)
-      end
-
-      create_http_client
-
-      @selenium_opts[:port] = @options.delete(:port) if @options.key?(:port)
-      @selenium_opts[:driver_opts] = @options.delete(:driver_opts) if @options.key?(:driver_opts)
       @selenium_opts[:listener] = @options.delete(:listener) if @options.key?(:listener)
 
+      if @options.key?(:url)
+        @selenium_opts[:url] = @options.delete(:url)
+      else
+        process_service(@options.delete(:service))
+      end
+
+      process_http_client
       process_browser_options
       process_capabilities
       Watir.logger.info "Creating Browser instance with Watir processed options: #{@selenium_opts.inspect}"
@@ -44,109 +44,254 @@ module Watir
       @selenium_opts
     end
 
-    def create_http_client
-      client_timeout = @options.delete(:client_timeout)
-      open_timeout = @options.delete(:open_timeout)
-      read_timeout = @options.delete(:read_timeout)
-
-      http_client = @options.delete(:http_client)
-
-      %i[open_timeout read_timeout client_timeout].each do |t|
-        next if http_client.nil? || !respond_to?(t)
-
-        msg = "You can pass #{t} value directly into Watir::Browser opt without needing to use :http_client"
-        Watir.logger.warn msg, ids: %i[http_client use_capabilities]
+    def process_http_client
+      http_client = @options.delete(:http_client) || Watir::HttpClient.new
+      if http_client.is_a?(Hash)
+        http_client = Watir::HttpClient.new(http_client)
+      elsif !http_client.is_a?(Selenium::WebDriver::Remote::Http::Common)
+        raise TypeError, ':http_client must be a Hash or a Selenium HTTP Client instance'
       end
 
-      http_client ||= Selenium::WebDriver::Remote::Http::Default.new
+      unless http_client.is_a?(Watir::HttpClient)
+        Watir.logger.warn 'Check out the new Watir::HttpClient and let us know if there are missing features you need',
+                          ids: [:watir_client]
+      end
 
-      http_client.timeout = client_timeout if client_timeout
-      http_client.open_timeout = open_timeout if open_timeout
-      http_client.read_timeout = read_timeout if read_timeout
+      process_http_client_timeouts(http_client)
       @selenium_opts[:http_client] = http_client
     end
 
-    # TODO: - this will get addressed with Capabilities Update
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/PerceivedComplexity:
-    # rubocop:disable Metrics/CyclomaticComplexity::
     def process_browser_options
       browser_options = @options.delete(:options) || {}
+      process_w3c_capabilities(browser_options)
 
-      case @selenium_browser
+      case @browser
       when :chrome
-        if @options.key?(:args) || @options.key?(:switches)
-          browser_options ||= {}
-          browser_options[:args] = (@options.delete(:args) || @options.delete(:switches)).dup
-        end
-        if @options.delete(:headless)
-          browser_options ||= {}
-          browser_options[:args] ||= []
-          browser_options[:args] += ['--headless', '--disable-gpu']
-        end
-        @selenium_opts[:options] = browser_options if browser_options.is_a? Selenium::WebDriver::Chrome::Options
-        @selenium_opts[:options] ||= Selenium::WebDriver::Chrome::Options.new(**browser_options)
+        process_chrome_options(browser_options)
       when :firefox
-        profile = @options.delete(:profile)
-        if browser_options.is_a? Selenium::WebDriver::Firefox::Options
-          @selenium_opts[:options] = browser_options
-          if profile
-            msg = 'Initializing Browser with both :profile and :option', ':profile as a key inside :option'
-            Watir.logger.deprecate msg, ids: [:firefox_profile]
-          end
-        end
-        if @options.delete(:headless)
-          browser_options ||= {}
-          browser_options[:args] ||= []
-          browser_options[:args] += ['--headless']
-        end
-        @selenium_opts[:options] ||= Selenium::WebDriver::Firefox::Options.new(**browser_options)
-        @selenium_opts[:options].profile = profile if profile
+        process_firefox_options(browser_options)
       when :safari
-        Selenium::WebDriver::Safari.technology_preview! if @options.delete(:technology_preview)
-      when :remote
-        if @browser == :chrome && @options.delete(:headless)
-          args = @options.delete(:args) || @options.delete(:switches) || []
-          @options['chromeOptions'] = {'args' => args + ['--headless', '--disable-gpu']}
-        end
-        if @browser == :firefox && @options.delete(:headless)
-          args = @options.delete(:args) || @options.delete(:switches) || []
-          @options[Selenium::WebDriver::Firefox::Options::KEY] = {'args' => args + ['--headless']}
-        end
-        if @browser == :safari && @options.delete(:technology_preview)
-          @options['safari.options'] = {'technologyPreview' => true}
-        end
-      when :ie
-        if @options.key?(:args)
-          browser_options ||= {}
-          browser_options[:args] = @options.delete(:args).dup
-        end
-        unless browser_options.is_a? Selenium::WebDriver::IE::Options
-          ie_caps = browser_options.select { |k| Selenium::WebDriver::IE::Options::CAPABILITIES.include?(k) }
-          browser_options = Selenium::WebDriver::IE::Options.new(**browser_options)
-          ie_caps.each { |k, v| browser_options.add_option(k, v) }
-        end
-        @selenium_opts[:options] = browser_options
+        process_safari_options(browser_options)
+      when :ie, :internet_explorer
+        process_ie_options(browser_options)
       end
     end
 
-    # rubocop:enable Metrics/MethodLength
-    # rubocop:enable Metrics/PerceivedComplexity:
-    # rubocop:enable Metrics/CyclomaticComplexity::
-
     def process_capabilities
-      caps = @options.delete(:desired_capabilities)
+      caps = @options.delete(:capabilities)
+
+      unless @options.empty?
+        Watir.logger.deprecate('passing unrecognized arguments into Browser constructor',
+                               'appropriate keyword to nest all arguments',
+                               ids: %i[unknown_keyword capabilities],
+                               reference: 'http://watir.com/guides/capabilities.html')
+      end
 
       if caps
-        msg = 'You can pass values directly into Watir::Browser opt without needing to use :desired_capabilities'
-        Watir.logger.warn msg,
-                          ids: [:use_capabilities]
         @selenium_opts.merge!(@options)
       else
-        caps = Selenium::WebDriver::Remote::Capabilities.send @browser, @options
+        caps = Selenium::WebDriver::Remote::Capabilities.send @browser, @options.merge(@w3c_caps)
       end
 
       @selenium_opts[:desired_capabilities] = caps
     end
+
+    def deprecate_desired_capabilities
+      return unless @options.key?(:desired_capabilities)
+
+      Watir.logger.deprecate(':desired_capabilities to initialize Browser',
+                             ':capabilities or preferably :options',
+                             ids: [:desired_capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+      @options[:capabilities] = @options.delete(:desired_capabilities)
+    end
+
+    def deprecate_url_service
+      Watir.logger.deprecate('allowing Browser initialization with both :url & :service',
+                             'just :service',
+                             ids: [:url_service],
+                             reference: 'http://watir.com/guides/capabilities.html')
+    end
+
+    def process_http_client_timeouts(http_client)
+      deprecate_client_timeout(http_client) if @options.key? :client_timeout
+      deprecate_open_timeout(http_client) if @options.key? :open_timeout
+      deprecate_read_timeout(http_client) if @options.key? :read_timeout
+    end
+
+    def deprecate_client_timeout(http_client)
+      Watir.logger.deprecate(':client_timeout to initialize Browser',
+                             ':open_timeout and/or :read_timeout in a Hash with :http_client key',
+                             ids: [:http_client_timeout],
+                             reference: 'http://watir.com/guides/capabilities.html')
+      timeout = @options.delete(:client_timeout)
+      http_client.open_timeout = timeout
+      http_client.read_timeout = timeout
+    end
+
+    def deprecate_open_timeout(http_client)
+      Watir.logger.deprecate(':open_timeout to initialize Browser',
+                             ':open_timeout in a Hash with :http_client key',
+                             ids: %i[http_open_timeout capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+      http_client.open_timeout = @options.delete(:open_timeout)
+    end
+
+    def deprecate_read_timeout(http_client)
+      Watir.logger.deprecate(':read_timeout to initialize Browser',
+                             ':read_timeout in a Hash with :http_client key',
+                             ids: %i[http_read_timeout capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+      http_client.read_timeout = @options.delete(:read_timeout)
+    end
+
+    def process_chrome_options(browser_options)
+      @selenium_opts[:options] = browser_options if browser_options.is_a? Selenium::WebDriver::Chrome::Options
+      @selenium_opts[:options] ||= Selenium::WebDriver::Chrome::Options.new(**browser_options)
+
+      process_args
+
+      return unless @options.delete(:headless)
+
+      @selenium_opts[:options].args << '--headless'
+      @selenium_opts[:options].args << '--disable-gpu'
+    end
+
+    def process_firefox_options(browser_options)
+      @selenium_opts[:options] = browser_options if browser_options.is_a? Selenium::WebDriver::Firefox::Options
+
+      @selenium_opts[:options] ||= Selenium::WebDriver::Firefox::Options.new(**browser_options)
+      if @options.key?(:profile)
+        new = 'Initializing Browser with both :profile and :option'
+        old = ':profile as a key inside :option'
+        Watir.logger.deprecate new, old, ids: [:firefox_profile]
+
+        @selenium_opts[:options].profile = @options.delete(:profile)
+      end
+
+      @selenium_opts[:options].args << '--headless' if @options.delete(:headless)
+    end
+
+    def process_safari_options(browser_options)
+      @selenium_opts[:options] = browser_options if browser_options.is_a? Selenium::WebDriver::Safari::Options
+      @selenium_opts[:options] ||= Selenium::WebDriver::Safari::Options.new(**browser_options)
+      Selenium::WebDriver::Safari.technology_preview! if @options.delete(:technology_preview)
+    end
+
+    def process_ie_options(browser_options)
+      @selenium_opts[:options] = browser_options if browser_options.is_a? Selenium::WebDriver::IE::Options
+      @selenium_opts[:options] ||= Selenium::WebDriver::IE::Options.new(**browser_options)
+
+      process_args
+    end
+
+    def process_service(service)
+      service = deprecate_service_keywords if service.nil?
+
+      @selenium_opts[:service] = case service
+                                 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 deprecate_service_keywords
+      service = {}
+      if @options.key?(:port)
+        Watir.logger.deprecate(':port to initialize Browser',
+                               ':port in a Hash with :service key',
+                               ids: %i[port_keyword capabilities],
+                               reference: 'http://watir.com/guides/capabilities.html')
+        service[:port] = @options.delete(:port)
+      end
+      if @options.key?(:driver_opts)
+        Watir.logger.deprecate(':driver_opts to initialize Browser',
+                               ':args as Array in a Hash with :service key',
+                               ids: %i[driver_opts_keyword capabilities],
+                               reference: 'http://watir.com/guides/capabilities.html')
+        service[:args] = @options.delete(:driver_opts)
+      end
+      service
+    end
+
+    def process_args
+      args = if @options.key?(:args)
+               deprecate_args
+               @options.delete(:args)
+             elsif @options.key?(:switches)
+               deprecate_switches
+               @options.delete(:switches)
+             else
+               []
+             end
+      args.each { |arg| @selenium_opts[:options].args << arg }
+    end
+
+    def deprecate_args
+      Watir.logger.deprecate(':args to initialize Browser',
+                             ':args inside Hash with :options key',
+                             ids: %i[args_keyword capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+    end
+
+    def deprecate_switches
+      Watir.logger.deprecate(':switches to initialize Browser',
+                             ':switches inside Hash with :options key',
+                             ids: %i[switches_keyword capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+    end
+
+    def deprecate_remote(browser)
+      return unless browser == :remote
+
+      Watir.logger.deprecate(':remote to initialize Browser',
+                             'browser key along with remote url',
+                             ids: %i[remote_keyword capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+      infer_browser
+    end
+
+    def infer_browser
+      if @options.key?(:browser)
+        @options.delete(:browser)
+      elsif @options.key?(:capabilities)
+        @options[:capabilities].browser_name.tr(' ', '_').to_sym
+      elsif @options.key?(:options)
+        @options[:options].class.to_s.split('::')[-2].downcase.to_sym
+      else
+        :chrome
+      end
+    end
+
+    def process_w3c_capabilities(opts)
+      @w3c_caps = {}
+      return unless opts.is_a?(Hash)
+
+      w3c_keys = %i[browser_version platform_name accept_insecure_certs page_load_strategy proxy set_window_rect
+                    timeouts unhandled_prompt_behavior strict_file_interactibility]
+
+      opts.each do |key, _val|
+        next unless key.to_s.include?(':') || w3c_keys.include?(key)
+
+        @w3c_caps[key] = opts.delete(key)
+      end
+    end
+
+    def deprecate_options_capabilities
+      return unless @options.key?(:capabilities) && @options.key?(:options)
+
+      old = 'initializing Browser with both options and capabilities'
+      new = 'Hash with :options, Selenium Options instance with :options or' \
+'Selenium Capabilities instance with :capabilities'
+      Watir.logger.deprecate(old,
+                             new,
+                             ids: %i[options_capabilities capabilities],
+                             reference: 'http://watir.com/guides/capabilities.html')
+    end
   end
 end