sauce_bindings 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 911fcc77b89278c32496a2c1e29a8076494208a2133fa4fa854e949d5db8437d
-  data.tar.gz: c8a91543d40f08b14fd3253e7ca32ecd639c9d2c24833f63c4668da51699ed27
+  metadata.gz: 7512f163c74551644149ae5452bf7e8f72977cef83e90134c26bd3c1a07f352c
+  data.tar.gz: 87248ccb9a002564dc97f05380db06e55ee4cb0fb6599d5fb9fcc0dca7ee27e4
 SHA512:
-  metadata.gz: ce6d3809d1efd72a5b89b0130a659b4d82863b16cf14377480bdfc3989ddf6f4c4e4bf2d9105968a03ee378c295366982a00b008fe2d9a91186ca107c1ea6231
-  data.tar.gz: 6f9a7311e6c206e3ac8689d402bed4dfb7ec8f19e2380b4543e64ddcfc5ed2dbf673da00c9788b6cea8aa3f20a432ff08cf8235d9a22c72f1d585445e3e7c82d
+  metadata.gz: 796b7da1beb7307122675d78f8b2fd698ab71c5b5ce20f887cb288a14d880e3abc1a0a2f9219962d6b3040b33c7ab26c97dc8977e04b6681da1159ca3f0ab85f
+  data.tar.gz: cafb5b1b25caf038eb537b15a552ba6242ab2493c2005c71ca8a2e15424c364ab81ca3a9a183e4606d94be7de55b06cec356e7249c78653c4f29d0a42d0f8595

data/.rubocop.yml

@@ -16,10 +16,10 @@ Metrics/BlockLength:
     - "**/*_spec.rb"
 
 Metrics/CyclomaticComplexity:
-  Max: 8
+  Max: 10
 
 Metrics/PerceivedComplexity:
-  Max: 9
+  Max: 11
 
 Metrics/ClassLength:
   Exclude:

data/CHANGES.md

@@ -0,0 +1,34 @@
+### 1.2.1 - March 1, 2022
+
+* Added latest Windows and Mac platforms 
+
+### 1.2.0 - July 12, 2021
+
+* Accessibility functionality via Sa11y
+
+### 1.1.1 - July 10, 2021
+
+* `Options` class methods only allow setting valid options for the provided browser
+* `Options` class supports Edge browser
+* Support Selenium 4
+
+### 1.1.0 - May 30, 2021
+
+* Build Name support for Github Actions
+* APAC data center tentatively supported
+* Update `Options` to be constructed with class methods for browsers
+
+### 1.0.0 - April 24, 2020
+
+* Link to job on Sauce UI in STDOUT
+
+### 1.0.0.beta1 - March 10, 2020
+
+* `Options` class to construct capabilities
+* `Session` class to wrap driver instance
+* `Session#data_center=` to choose data center
+* `Options` automatically uses default value for `build` name
+* `Options` class accepts Selenium `Options` classes as argument
+* `Options` accepts serialized information via a `Hash`
+* `CapybaraSession` class for special Capybara support
+* Sauce options for `user` and `access_key` must be obtained by ENV variables

data/README.md

@@ -62,7 +62,7 @@ browser_options = Selenium::WebDriver::Firefox::Options.new('args' => ['-foo'])
 ```
 
 ### Session class
-#### Intializing a Session
+#### Initializing a Session
 `Session` class gets initialized with an `Options` instance. If you want the
 default settings (latest Chrome version on Windows 10), you don't even need to use an `Options` instance:
 ```ruby

data/Rakefile

@@ -5,4 +5,16 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+RSpec::Core::RakeTask.new(:examples) do |spec|
+  spec.pattern = 'spec/examples/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:unit) do |spec|
+  spec.pattern = 'spec/unit/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:integration) do |spec|
+  spec.pattern = 'spec/integration/*_spec.rb'
+end
+
+task default: %i[examples unit integration]

data/lib/sauce_bindings/base_configurations.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class BaseConfigurations
+    def self.valid_options
+      %i[platform_name name build tags custom_data public tunnel_identifier parent_tunnel]
+    end
+  end
+end

data/lib/sauce_bindings/chrome_configurations.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class ChromeConfigurations < VDCConfigurations
+    def self.valid_options
+      super + %i[chromedriver_version extended_debugging capture_performance set_window_rect]
+    end
+  end
+end

data/lib/sauce_bindings/edge_configurations.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class EdgeConfigurations < VDCConfigurations
+    def self.valid_options
+      super + %i[edgedriver_version selenium_version set_window_rect]
+    end
+  end
+end

data/lib/sauce_bindings/firefox_configurations.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class FirefoxConfigurations < VDCConfigurations
+    def self.valid_options
+      super + %i[geckodriver_version extended_debugging selenium_version set_window_rect]
+    end
+  end
+end

data/lib/sauce_bindings/ie_configurations.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class IEConfigurations < VDCConfigurations
+    def self.valid_options
+      super + %i[iedriver_version avoid_proxy selenium_version set_window_rect]
+    end
+  end
+end

data/lib/sauce_bindings/options.rb

@@ -11,26 +11,36 @@ module SauceBindings
 
       def chrome(**opts)
         opts[:browser_name] = 'chrome'
+        opts[:valid_options] = ChromeConfigurations.valid_options
         Options.new(**opts)
       end
 
       def edge(**opts)
+        if Selenium::WebDriver::VERSION[0] == '3'
+          raise ArgumentError, 'Selenium 3 is not compatible with the Chromium based Microsoft Edge.'
+        end
+
         opts[:browser_name] = 'MicrosoftEdge'
+        opts[:valid_options] = EdgeConfigurations.valid_options
         Options.new(**opts)
       end
 
       def firefox(**opts)
         opts[:browser_name] = 'firefox'
+        opts[:valid_options] = FirefoxConfigurations.valid_options
         Options.new(**opts)
       end
 
       def ie(**opts)
         opts[:browser_name] = 'internet explorer'
+        opts[:valid_options] = IEConfigurations.valid_options
         Options.new(**opts)
       end
 
       def safari(**opts)
         opts[:browser_name] = 'safari'
+        opts[:platform_name] ||= 'macOS 11'
+        opts[:valid_options] = SafariConfigurations.valid_options
         Options.new(**opts)
       end
     end
@@ -49,17 +59,20 @@ module SauceBindings
                record_video screen_resolution selenium_version tags time_zone tunnel_identifier video_upload_on_pass
                capture_performance].freeze
 
-    attr_accessor :browser_name, :browser_version, :platform_name, :accept_insecure_certs, :page_load_strategy, :proxy,
-                  :set_window_rect, :timeouts, :unhandled_prompt_behavior, :strict_file_interactability, :avoid_proxy,
-                  :build, :chromedriver_version, :command_timeout, :custom_data, :extended_debugging, :idle_timeout,
-                  :iedriver_version, :max_duration, :name, :parent_tunnel, :prerun, :priority, :public, :record_logs,
-                  :record_screenshots, :record_video, :screen_resolution, :selenium_version, :tags, :time_zone,
-                  :tunnel_identifier, :video_upload_on_pass, :capture_performance
-    attr_reader :selenium_options
+    attr_reader :selenium_options, :timeouts
 
     def initialize(**opts)
-      parse_selenium_options(opts.delete(:selenium_options))
-      create_variables(SAUCE + W3C, opts)
+      se_options = Array(opts.delete(:selenium_options))
+      valid_options = opts.delete(:valid_options)
+      if valid_options.nil?
+        valid_options = SAUCE + W3C
+        warn 'Using `Options.new(opts)` directly is deprecated, use static methods for desired browser instead; ' \
+        'e.g., `Options.chrome(opts)` or `Options.safari(opts)'
+      end
+
+      create_variables(valid_options, opts)
+      @selenium_options = se_options.map(&:as_json).inject(:merge) || {}
+      parse_selenium_options(se_options)
       @build ||= build_name
 
       @browser_name ||= selenium_options['browserName'] || 'chrome'
@@ -70,17 +83,13 @@ module SauceBindings
     def capabilities
       caps = selenium_options.dup
       W3C.each do |key|
-        value = send(key)
-        key = self.class.camel_case(key)
-        value = parse_w3c_key(key, value)
-        caps[key] = value unless value.nil?
+        value = parse_w3c_key(key)
+        caps[self.class.camel_case(key)] = value unless value.nil?
       end
       caps['sauce:options'] = {}
       SAUCE.each do |key|
-        value = send(key)
-        key = self.class.camel_case(key)
-        value = parse_sauce_key(key, value)
-        caps['sauce:options'][key] = value unless value.nil?
+        value = parse_sauce_key(key)
+        caps['sauce:options'][self.class.camel_case(key)] = value unless value.nil?
       end
       caps
     end
@@ -90,11 +99,7 @@ module SauceBindings
       opts.each do |key, value|
         raise ArgumentError, "#{key} is not a valid parameter for Options class" unless respond_to?("#{key}=")
 
-        if value.is_a?(Hash)
-          value = value.each_with_object({}) do |(old_key, val), updated|
-            updated[old_key.to_sym] = val
-          end
-        end
+        value = value.transform_keys(&:to_sym) if value.is_a?(Hash)
 
         send("#{key}=", value)
       end
@@ -102,59 +107,124 @@ module SauceBindings
 
     private
 
-    def parse_w3c_key(key, value)
-      if key == 'proxy' && value
+    def key_value(key)
+      send(key)
+    rescue NoMethodError
+      # Ignored
+    end
+
+    def parse_w3c_key(key)
+      value = send(key)
+
+      if key == :proxy && value
         value.as_json
-      elsif key == 'timeouts' && value
-        value.each_with_object({}) do |(old_key, val), updated|
-          updated[self.class.camel_case(old_key)] = val
+      elsif key == :timeouts
+        if value
+          warn ':timeouts is deprecated, use :implicit_wait_timeout, :page_load_timeout or :script_timeout directly; ' \
+          '(ensure the values are set as seconds not milliseconds)'
+          value.transform_keys do |old_key|
+            self.class.camel_case(old_key)
+          end
+        else
+          manage_timeouts
         end
       else
         value
       end
     end
 
-    def parse_sauce_key(key, value)
-      if key == 'prerun' && value.is_a?(Hash)
-        value.each_with_object({}) do |(old_key, val), updated|
-          updated[self.class.camel_case(old_key)] = val
-        end
-      elsif key == 'customData' && value.is_a?(Hash)
-        value.each_with_object({}) do |(old_key, val), updated|
-          updated[self.class.camel_case(old_key)] = val
-        end
+    def manage_timeouts
+      timeouts = {}
+      timeouts['implicit'] = ms_multiplier(@implicit_wait_timeout) if @implicit_wait_timeout
+      timeouts['pageLoad'] = ms_multiplier(@page_load_timeout) if @page_load_timeout
+      timeouts['script'] = ms_multiplier(@script_timeout) if @script_timeout
+      timeouts unless timeouts.empty?
+    end
+
+    def ms_multiplier(int)
+      raise(ArgumentError, 'Timeouts need to be entered as seconds not milliseconds') if int > 600
+
+      int * 1000
+    end
+
+    def parse_sauce_key(key)
+      value = key_value(key)
+
+      case key
+      when :prerun
+        camelize_keys(value)
+      when :custom_data
+        camelize_keys(value)
+      when :disable_record_video
+        !send(:record_video)
+      when :disable_video_upload_on_pass
+        !send(:video_upload_on_pass)
+      when :disable_record_screenshots
+        !send(:record_screenshots)
+      when :disable_record_logs
+        !send(:record_logs)
       else
         value
       end
     end
 
+    def camelize_keys(hash)
+      hash&.transform_keys do |old_key|
+        self.class.camel_case(old_key)
+      end
+    end
+
     def parse_selenium_options(selenium_opts)
-      opts = Array(selenium_opts)
+      selenium_opts.each do |opt|
+        W3C.each do |capability|
+          value = option_value(opt, capability)
+          next if capability == :timeouts && value&.empty?
 
-      opts.each do |opt|
-        browser = BROWSER_NAMES[opt.class]
-        if browser
-          @browser_name = browser
-        else
-          W3C.each do |capability|
-            send("#{capability}=", opt[capability]) if opt[capability]
+          if capability == :browser_name
+            @browser_name ||= BROWSER_NAMES[opt.class]
+            validate_browser_name(value || BROWSER_NAMES[opt.class])
+          elsif value
+            send("#{capability}=", value)
           end
         end
       end
+    end
+
+    def option_value(opt, capability)
+      if opt.respond_to?(capability)
+        begin
+          opt.send(capability)
+        rescue KeyError
+          # Ignored
+        end
+      elsif opt.respond_to?(:[])
+        opt[capability]
+      end
+    end
 
-      @selenium_options = opts.map(&:as_json).inject(:merge) || {}
+    def validate_browser_name(browser)
+      return if @browser_name.nil? || browser == @browser_name
+
+      raise ArgumentError, "Selenium class identifies capabilities for #{browser}, which does not match the " \
+"provided browser name: #{@browser_name}"
     end
 
     def create_variables(key, opts)
       key.each do |option|
-        self.class.__send__(:attr_accessor, option)
+        singleton_class.class_eval { attr_accessor option }
         next unless opts.key?(option)
 
         instance_variable_set("@#{option}", opts.delete(option))
       end
+
+      if opts.key?(:browser_name)
+        singleton_class.class_eval { attr_reader :browser_name }
+        @browser_name = opts.delete(:browser_name)
+      end
+
       return if opts.empty?
 
-      raise ArgumentError, "#{opts.inspect} are not valid parameters for Options class"
+      raise ArgumentError, "#{opts.inspect} are not valid parameters for Options class with #{@browser_name}"
     end
 
     def build_name

data/lib/sauce_bindings/safari_configurations.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class SafariConfigurations < VDCConfigurations
+    def self.valid_options
+      super + %i[avoid_proxy selenium_version set_window_rect]
+    end
+  end
+end

data/lib/sauce_bindings/session.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'sauce_whisk'
+require 'sa11y/analyze'
 require 'selenium-webdriver'
 
 module SauceBindings
@@ -15,7 +16,7 @@ module SauceBindings
     attr_accessor :http_client, :listener
 
     def initialize(options = nil, data_center: nil, http_client: nil, listener: nil)
-      @options = options || Options.new
+      @options = options || Options.chrome
       @http_client = http_client
       @listener = listener
 
@@ -53,6 +54,11 @@ module SauceBindings
       @data_center = data_center
     end
 
+    def accessibility_results(js_lib: nil, frames: true, cross_origin: false)
+      sa11y = Sa11y::Analyze.new(driver, js_lib: js_lib, frames: frames, cross_origin: cross_origin)
+      sa11y.results
+    end
+
     def url
       @url ||= "https://#{@username}:#{@access_key}@#{DATA_CENTERS[data_center]}:443/wd/hub"
     end

data/lib/sauce_bindings/vdc_configurations.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class VDCConfigurations < BaseConfigurations
+    def self.valid_options
+      super + %i[browser_version page_load_strategy accept_insecure_certs proxy
+                 strict_file_interactability unhandled_prompt_behavior implicit_wait_timeout
+                 page_load_timeout script_timeout record_video video_upload_on_pass
+                 record_screenshots record_logs max_duration command_timeout
+                 idle_timeout prerun priority screen_resolution time_zone]
+    end
+  end
+end

data/lib/sauce_bindings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SauceBindings
-  VERSION = '1.1.0'
+  VERSION = '1.2.1'
 end

data/lib/sauce_bindings.rb

@@ -3,3 +3,10 @@
 require 'sauce_bindings/version'
 require 'sauce_bindings/options'
 require 'sauce_bindings/session'
+require 'sauce_bindings/base_configurations'
+require 'sauce_bindings/vdc_configurations'
+require 'sauce_bindings/chrome_configurations'
+require 'sauce_bindings/edge_configurations'
+require 'sauce_bindings/firefox_configurations'
+require 'sauce_bindings/ie_configurations'
+require 'sauce_bindings/safari_configurations'

data/sauce_bindings.gemspec

@@ -9,6 +9,7 @@ Gem::Specification.new do |spec|
   spec.version       = SauceBindings::VERSION
   spec.authors       = ['Titus Fortner']
   spec.email         = ['titusfortner@gmail.com']
+  spec.required_ruby_version = '>= 2.5.0'
 
   spec.summary       = 'Simple interface for interacting with Sauce Labs.'
   spec.description   = 'Reduces complexity in user code for running Selenium tests on Sauce Labs'
@@ -23,11 +24,12 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'capybara', '~> 3.16'
   spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop', '~>0.66'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
   spec.add_development_dependency 'rubocop-performance'
-  spec.add_development_dependency 'rubocop-rspec', '~>1.32'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.0'
   spec.add_development_dependency 'webmock', '~> 3.5'
 
+  spec.add_runtime_dependency 'sa11y', '~> 0.2.0'
   spec.add_runtime_dependency 'sauce_whisk'
-  spec.add_runtime_dependency 'selenium-webdriver', '~> 3.142.0', '>= 3.142.7'
+  spec.add_runtime_dependency 'selenium-webdriver', '>= 3.142.7'
 end

data/spec/deprecated_options.yml

@@ -0,0 +1,56 @@
+example_values:
+  browser_name: 'firefox'
+  browser_version: '123'
+  platform_name: 'Mac'
+  accept_insecure_certs: true
+  page_load_strategy: 'eager'
+  set_window_rect: true
+  unhandled_prompt_behavior: "accept"
+  strict_file_interactability: true
+  timeouts:
+    implicit: 1
+    page_load: 59
+    script: 29
+  avoid_proxy: true
+  build: 'Sample Build Name'
+  capture_performance: true
+  chromedriver_version: '71'
+  command_timeout: 2
+  custom_data:
+    foo: 'foo'
+    bar: 'bar'
+  extended_debugging: true
+  idle_timeout: 3
+  iedriver_version: '3.141.0'
+  max_duration: 300
+  name: 'Sample Test Name'
+  parent_tunnel: 'Mommy'
+  prerun:
+    executable: "http://url.to/your/executable.exe"
+    args:
+      - --silent
+      - -a
+      - -q
+    background: false
+    timeout: 120
+  priority: 0
+  public: 'team'
+  record_logs: false
+  record_screenshots: false
+  record_video: false
+  screen_resolution: '10x10'
+  selenium_version: '3.141.59'
+  tags:
+    - foo
+    - bar
+    - foobar
+  time_zone: 'San Francisco'
+  tunnel_identifier: 'tunnelname'
+  video_upload_on_pass: false
+
+invalid_option:
+  foo: "bar"
+  browser_name: "firefox"
+  browser_version: "70"
+  platform_name: "MacOS 10.12"
+  record_screenshots: false

data/spec/examples/accessibility_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'sauce_bindings'
+require 'rspec'
+
+describe 'Create Session' do
+  it 'starts session' do
+    # 1. Create Session object with the desired Data Center
+    session = SauceBindings::Session.new
+
+    # 2. Start Session to get the Driver
+    driver = session.start
+
+    # 3. Use the driver in your tests just like normal
+    driver.get('https://www.saucedemo.com/')
+
+    # 4a. Get accessibility default results with frame support
+    session.accessibility_results
+
+    # 4b. Get accessibility default results without frame support
+    session.accessibility_results(frames: false)
+
+    # 4c. Get accessibility results with cross origin frame support
+    session.accessibility_results(cross_origin: true)
+
+    # 4d. Get accessibility results with a different version of Axe Core JS Library
+    session.accessibility_results(js_lib: File.read(File.expand_path('axe.min.js', __dir__)))
+
+    # 5. Stop the Session with whether the test passed or failed
+    session.stop(true)
+  end
+end

data/spec/examples/axe.min.js

@@ -0,0 +1 @@
+// Blank file

data/spec/examples/browser_options_spec.rb

@@ -4,14 +4,12 @@ require 'sauce_bindings'
 require 'rspec'
 
 describe 'Browser Options' do
-  before { WebMock.allow_net_connect! }
-
   it 'creates session' do
     # 1. Create Selenium Browser Options instance
-    browser_options = Selenium::WebDriver::Firefox::Options.new(args: ['--foo'])
+    browser_options = Selenium::WebDriver::Chrome::Options.new(args: ['--start-fullscreen'])
 
     # 2. Create Sauce Options object with the Browser Options object instance
-    sauce_options = SauceBindings::Options.firefox(selenium_options: browser_options)
+    sauce_options = SauceBindings::Options.chrome(selenium_options: browser_options)
 
     # 3. Create Session object with SauceOptions object instance
     session = SauceBindings::Session.new(sauce_options)

data/spec/examples/{basic_options_spec.rb → common_options_spec.rb}

@@ -3,13 +3,12 @@
 require 'sauce_bindings'
 require 'rspec'
 
-describe 'Basic Options' do
-  before { WebMock.allow_net_connect! }
-
+describe 'Common Options' do
   it 'creates session' do
-    # 1. Create a SauceOptions instance with the 3 primary parameters
-    sauce_options = SauceBindings::Options.firefox(browser_version: '73.0',
-                                                   platform_name: 'Windows 8')
+    # 1. Create Options instance with common w3c options
+    sauce_options = SauceBindings::Options.firefox(browser_version: '88.0',
+                                                   platform_name: 'Windows 8',
+                                                   unhandled_prompt_behavior: 'ignore')
 
     # 2. Create Session object with SauceOptions object instance
     session = SauceBindings::Session.new(sauce_options)

data/spec/examples/create_session_spec.rb

@@ -4,8 +4,6 @@ require 'sauce_bindings'
 require 'rspec'
 
 describe 'Create Session' do
-  before { WebMock.allow_net_connect! }
-
   it 'starts session' do
     # 1. Create Session object with the defaults
     session = SauceBindings::Session.new

data/spec/examples/data_center_spec.rb

@@ -4,8 +4,6 @@ require 'sauce_bindings'
 require 'rspec'
 
 describe 'Create Session' do
-  before { WebMock.allow_net_connect! }
-
   it 'starts session' do
     # 1. Create Session object with the desired Data Center
     session = SauceBindings::Session.new(data_center: :EU_CENTRAL)

data/spec/examples/sauce_options_spec.rb

@@ -4,12 +4,10 @@ require 'sauce_bindings'
 require 'rspec'
 
 describe 'Sauce Options' do
-  before { WebMock.allow_net_connect! }
-
   it 'creates session' do
     # 1. Create a SauceOptions instance with Sauce Labs Specific Options
     sauce_options = SauceBindings::Options.firefox(extended_debugging: true,
-                                                   idle_timeout: 100,
+                                                   idle_timeout: 45,
                                                    time_zone: 'Alaska')
 
     # 2. Create Session object with SauceOptions object instance