sauce_bindings 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7512f163c74551644149ae5452bf7e8f72977cef83e90134c26bd3c1a07f352c
-  data.tar.gz: 87248ccb9a002564dc97f05380db06e55ee4cb0fb6599d5fb9fcc0dca7ee27e4
+  metadata.gz: d6fa82b7cd3b5e29fcfdb6e77f98f9dd7cb309d51523427de63e586b6094ac75
+  data.tar.gz: 8e8b4147c5a77459710f52cb36e927018050c34b4fff186960ddbb433ada23a7
 SHA512:
-  metadata.gz: 796b7da1beb7307122675d78f8b2fd698ab71c5b5ce20f887cb288a14d880e3abc1a0a2f9219962d6b3040b33c7ab26c97dc8977e04b6681da1159ca3f0ab85f
-  data.tar.gz: cafb5b1b25caf038eb537b15a552ba6242ab2493c2005c71ca8a2e15424c364ab81ca3a9a183e4606d94be7de55b06cec356e7249c78653c4f29d0a42d0f8595
+  metadata.gz: 2b0970705b477b0df8ad01f5f162b8e64731b76396cbe6c2038f10a501a4d5769aedfa00e33429ca8f0fc2e905a0efd6187b09f3d4e2ceb9262334183f596bbc
+  data.tar.gz: d4336f5ef88d197a1995142fb7ceb36c6dfe69038d8ac2204cd9fe3e04e82eeef2ad810279c9403977b1b27014f56f72ac6805d4dc5299a5917e6bbf386e4e1c

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.5.3
+  TargetRubyVersion: 2.7.5
 
 require:
   - rubocop-rspec
@@ -9,7 +9,7 @@ Layout/SpaceInsideHashLiteralBraces:
   EnforcedStyle: no_space
 
 Metrics/AbcSize:
-  Max: 25
+  Max: 27
 
 Metrics/BlockLength:
   Exclude:
@@ -22,14 +22,13 @@ Metrics/PerceivedComplexity:
   Max: 11
 
 Metrics/ClassLength:
-  Exclude:
-    - 'lib/sauce_bindings/options.rb'
+  Enabled: false
 
 Metrics/LineLength:
   Max: 120
 
 Metrics/MethodLength:
-  Max: 17
+  Max: 20
 
 Metrics/ModuleLength:
   CountComments: false
@@ -55,4 +54,11 @@ RSpec/MultipleExpectations:
   Enabled: false
 
 RSpec/DescribedClass:
-  EnforcedStyle: explicit
+  EnforcedStyle: explicit
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/BlockDelimiters:
+  EnforcedStyle: braces_for_chaining

data/CHANGES.md

@@ -1,3 +1,15 @@
+### 1.3.0 - June 15, 2022
+
+* Fix links to work all data centers
+* Manage credentials in Options instead of Session
+* Deprecate using magic strings for stopping a session
+* Implement pausing — `Session#pause`
+* Implement commenting in Sauce command list — `Session#annotate` 
+* Implement logging control — `Session#enable_logs`, `Session#disable_logs` 
+* Implement network control — `Session#stop_network`, `Session#start_network`
+* Implement updating test information — `Session#change_name`, `Session#tags=`
+* Require Selenium 4 and Ruby 2.7
+
 ### 1.2.1 - March 1, 2022
 
 * Added latest Windows and Mac platforms 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Titus Fortner
+Copyright (c) 2019-2022 Sauce Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,23 +1,13 @@
 # Sauce Bindings 
+
 ## A library for interacting with Sauce Labs using Ruby
 
 This gem is intended as a way to interact with Sauce Labs in an obvious and straightforward way. 
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'sauce_bindings'
-```
-
-And then execute:
+## User Installation & Usage
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install sauce_bindings
+Please see the [documentation on our website](https://opensource.saucelabs.com/sauce_bindings), 
+and select the "Ruby" tab for code examples. 
 
 ## Running Tests
 
@@ -25,79 +15,13 @@ To run tests for the Ruby Sauce Bindings, execute
 
     $ bundle exec rake
 
-## Usage
-
-`SauceBindings` is broken into two main components, `Options` and `Session`
-
-### Options class
-`Options` provides an easy interface to the Sauce Labs specific settings you want in your tests.
-
-If you want the default settings (the latest Chrome version on Windows 10) with no other settings,
-this is all the code you need:
-```
-sauce_opts = SauceBindings::Options.new
-```
-To specify additional 
-[Sauce Labs supported settings](https://wiki.saucelabs.com/display/DOCS/Test+Configuration+Options),
-simply pass these in as a `Hash`, or use an accessor:
-```
-sauce_options = {screen_resolution: '1080x720',
-                 browser_name: 'Firefox',
-                 platform_name: 'Mac OS'}
-sauce_opts = SauceBindings::Options.new(sauce_options)
-sauce_opts.idle_timeout = 100
-```
-if you have additional browser specific settings, or 
-[webdriver w3c spec compliant settings](http://w3c.github.io/webdriver/webdriver-spec.html#capabilities), in 
-Selenium 3.x you need to generate each of these separately; see the `Session` class below for how to use it:
-```
-sauce_options = SauceBindings::Options.new(screen_resolution: '1080x720',
-                                         browser_name: 'Firefox',
-                                         platform_name: 'Mac OS')
-
-selenium_options = Selenium::WebDriver::Remote::Capabilities.new(accept_insecure_certs: false,
-                                                                 page_load_strategy: 'eager'}
-
-browser_options = Selenium::WebDriver::Firefox::Options.new('args' => ['-foo'])
-```
-
-### Session class
-#### 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
-@session = SauceBindings::Session.new
-```
-If you want something other than the default, create a Sauce `Option` instance (as generated in the section above,
-then pass it into the constructor:
-```ruby
-@session = SauceBindings::Session.new(sauce_opts)
-```
-If you also have Selenium or Browser options as described above, then you pass them in with an `Array` like so:
-```ruby
-@session = SauceBindings::Session.new([sauce_opts, se_opts, browser_opts])
-```
-
-#### Creating a driver instance
-The `#start` method is required, and will return a `Selenium::WebDriver::<Browser>::Driver` instance,
-and the `#stop` method will automatically quit the driver as well as ending the Sauce Labs session.
-```ruby
-session = SauceBindings::Session.new
-driver = session.start
-# Use the driver
-session.stop
-```
-Note that the `Driver` instance can also be obtained at any time with the `#driver` method:
-```ruby
-session = SauceBindings::Session.new
-session.start
-driver = session.driver
-# Use the driver
-session.stop
-```
-#### Additional Session methods
-We have a number of features we plan to add; stay tuned to see what additional features are made available. If you
-have any request, please contact the Sauce Labs Solution Architect team.
+## Building and Releasing
+
+Use `gem` instead of `rake` so that it isn't auto-tagged on github
+
+* Bump `SauceBindings::VERSION`
+* `$ gem build sauce_bindings.gemspec`
+* `$ gem push pkg/sauce_bindings-<VERSION>.gem`
 
 ## Contributing
 

data/Rakefile

@@ -5,16 +5,18 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-RSpec::Core::RakeTask.new(:examples) do |spec|
-  spec.pattern = 'spec/examples/*_spec.rb'
-end
+task default: %i[examples unit integration]
 
 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'
+desc 'Run examples in parallel'
+task :examples do
+  system 'parallel_split_test spec/examples/*_spec.rb'
 end
 
-task default: %i[examples unit integration]
+desc 'Run integration tests in parallel'
+task :integration do
+  system 'parallel_split_test spec/integration/*_spec.rb'
+end

data/lib/sauce_bindings/capybara_session.rb

@@ -15,9 +15,6 @@ module SauceBindings
     end
 
     def start
-      raise ArgumentError, "needs username; use `ENV['SAUCE_USERNAME']` or `Session#username=`" unless @username
-      raise ArgumentError, "needs access_key; use `ENV['SAUCE_ACCESS_KEY']` or `Session#access_key=`" unless @access_key
-
       @capybara_driver = Capybara.current_session.driver
       @driver = @capybara_driver.browser
     end

data/lib/sauce_bindings/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  class SessionNotStartedError < RuntimeError; end
+
+  class InvalidPlatformError < RuntimeError; end
+end

data/lib/sauce_bindings/logger.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SauceBindings
+  #
+  # @example Enable full logging
+  #   SauceBindings.logger.level = :debug
+  #
+  # @example Log to file
+  #   SauceBindings.logger.output = 'webdrivers.log'
+  #
+  # @example Use logger manually
+  #   SauceBindings.logger.info('This is info message')
+  #   SauceBindings.logger.warn('This is warning message')
+  #
+  class Logger < Selenium::WebDriver::Logger
+    def initialize
+      super('SauceBindings')
+    end
+  end
+end

data/lib/sauce_bindings/options.rb

@@ -66,8 +66,9 @@ module SauceBindings
       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)'
+        SauceBindings.logger.deprecate('Using `Options.new(opts)` directly',
+                                       'static methods for desired browser',
+                                       id: :options_init) { '(e.g., `Options.chrome(opts)`)' }
       end
 
       create_variables(valid_options, opts)
@@ -86,7 +87,13 @@ module SauceBindings
         value = parse_w3c_key(key)
         caps[self.class.camel_case(key)] = value unless value.nil?
       end
+
       caps['sauce:options'] = {}
+      caps['sauce:options']['username'] = ENV['SAUCE_USERNAME'] ||
+                                          raise(ArgumentError, "needs username; use `ENV['SAUCE_USERNAME']`")
+      caps['sauce:options']['accessKey'] = ENV['SAUCE_ACCESS_KEY'] ||
+                                           raise(ArgumentError, "needs access key; use `ENV['SAUCE_ACCESS_KEY']`")
+
       SAUCE.each do |key|
         value = parse_sauce_key(key)
         caps['sauce:options'][self.class.camel_case(key)] = value unless value.nil?
@@ -105,6 +112,14 @@ module SauceBindings
       end
     end
 
+    def mac?
+      @platform_name.include?('mac') || @platform_name.include?('OS X')
+    end
+
+    def windows?
+      @platform_name.include?('Windows')
+    end
+
     private
 
     def key_value(key)
@@ -120,8 +135,11 @@ module SauceBindings
         value.as_json
       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)'
+          SauceBindings.logger.deprecate(':timeouts',
+                                         ':implicit_wait_timeout, :page_load_timeout or :script_timeout;',
+                                         id: :timeouts) do
+            '(ensure the values are set as seconds not milliseconds)'
+          end
           value.transform_keys do |old_key|
             self.class.camel_case(old_key)
           end

data/lib/sauce_bindings/session.rb

@@ -6,13 +6,13 @@ require 'selenium-webdriver'
 
 module SauceBindings
   class Session
-    DATA_CENTERS = {US_WEST: 'ondemand.us-west-1.saucelabs.com',
-                    US_EAST: 'ondemand.us-east-1.saucelabs.com',
-                    EU_CENTRAL: 'ondemand.eu-central-1.saucelabs.com',
-                    APAC_SOUTHEAST: 'ondemand.apac-southeast-1.saucelabs.com'}.freeze
+    DATA_CENTERS = {US_WEST: 'us-west-1',
+                    US_EAST: 'us-east-1',
+                    EU_CENTRAL: 'eu-central-1',
+                    APAC_SOUTHEAST: 'apac-southeast-1'}.freeze
 
     attr_writer :url
-    attr_reader :driver, :options, :data_center
+    attr_reader :driver, :options, :data_center, :session_id
     attr_accessor :http_client, :listener
 
     def initialize(options = nil, data_center: nil, http_client: nil, listener: nil)
@@ -20,27 +20,25 @@ module SauceBindings
       @http_client = http_client
       @listener = listener
 
-      @username = ENV['SAUCE_USERNAME']
-      @access_key = ENV['SAUCE_ACCESS_KEY']
       self.data_center = data_center || :US_WEST
     end
 
     def start
-      raise ArgumentError, "needs username; use `ENV['SAUCE_USERNAME']`" unless @username
-      raise ArgumentError, "needs access_key; use `ENV['SAUCE_ACCESS_KEY']`" unless @access_key
-
       @driver = Selenium::WebDriver.for :remote, to_selenium
+      @session_id = @driver.session_id
+      @driver
     end
 
     def stop(result)
       return if @driver.nil?
 
-      SauceWhisk::Jobs.change_status(@driver.session_id, result)
-      # Add output for the Sauce OnDemand Jenkins plugin
-      # The first print statement will automatically populate links on Jenkins to Sauce
-      # The second print statement will output the job link to logging/console
-      puts "SauceOnDemandSessionID=#{@driver.session_id} job-name=#{@options.name}"
-      puts "Test Job Link: https://app.saucelabs.com/tests/#{@driver.session_id}"
+      unless result.is_a?(TrueClass) || result.is_a?(FalseClass)
+        raise ArgumentError, 'Result must be a boolean value representing whether a test has passed'
+      end
+
+      SauceWhisk::Jobs.change_status(@session_id, result)
+      print_results
+
       @driver.quit
     end
 
@@ -55,19 +53,95 @@ module SauceBindings
     end
 
     def accessibility_results(js_lib: nil, frames: true, cross_origin: false)
+      validate_session_started('accessibility_results')
       sa11y = Sa11y::Analyze.new(driver, js_lib: js_lib, frames: frames, cross_origin: cross_origin)
       sa11y.results
     end
 
+    def annotate(comment)
+      validate_session_started('annotate')
+      driver.execute_script("sauce:context=#{comment}")
+    end
+
+    def pause
+      validate_session_started('pause')
+      driver.execute_script('sauce: break')
+      puts "\nThis test has been stopped; no more driver commands will be accepted"
+      puts "\nYou can take manual control of the test from the Sauce Labs UI here: #{test_link}"
+      @driver = nil
+    end
+
+    def disable_logging
+      validate_session_started('disable_logging')
+      driver.execute_script('sauce: disable log')
+    end
+
+    def enable_logging
+      validate_session_started('enable_logging')
+      driver.execute_script('sauce: enable log')
+    end
+
+    def stop_network
+      validate_session_started('stop_network')
+      unless options.mac?
+        error = "Can only start or stop the network on a Mac; current platform is: #{options.platform_name}"
+        raise InvalidPlatformError, error
+      end
+
+      driver.execute_script('sauce: stop network')
+    end
+
+    def start_network
+      validate_session_started('start_network')
+      unless options.mac?
+        error = "Can only start or stop the network on a Mac; current platform is: #{options.platform_name}"
+        raise InvalidPlatformError, error
+      end
+
+      driver.execute_script('sauce: start network')
+    end
+
+    def change_name(name)
+      validate_session_started('change_name')
+
+      driver.execute_script("sauce:job-name=#{name}")
+    end
+
+    def add_tags(tags)
+      tags = Array(tags)
+      validate_session_started('tags=')
+      @driver.execute_script("sauce:job-tags=#{tags.join(',')}")
+    end
+
     def url
-      @url ||= "https://#{@username}:#{@access_key}@#{DATA_CENTERS[data_center]}:443/wd/hub"
+      @url ||= "https://ondemand.#{DATA_CENTERS[data_center]}.saucelabs.com/wd/hub"
     end
 
     def to_selenium
-      caps = {url: url, desired_capabilities: options.capabilities}
+      caps = {url: url, capabilities: Selenium::WebDriver::Remote::Capabilities.new(options.capabilities)}
       caps[:listener] = listener if listener
       caps[:http_client] = http_client if http_client
       caps
     end
+
+    private
+
+    def test_link
+      dc = data_center == :US_WEST ? '' : "#{DATA_CENTERS[data_center]}."
+      "https://app.#{dc}saucelabs.com/tests/#{@session_id}"
+    end
+
+    def validate_session_started(method)
+      raise SessionNotStartedError, "session must be started before executing ##{method}" unless @driver
+    end
+
+    def print_results
+      # Add output for the Sauce OnDemand Jenkins plugin
+      # The first print statement will automatically populate links on Jenkins to Sauce
+      # The second print statement will output the job link to logging/console
+      puts "SauceOnDemandSessionID=#{@session_id} job-name=#{@options.name}"
+
+      puts "Test Job Link: #{test_link}"
+    end
   end
 end

data/lib/sauce_bindings/version.rb

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

data/lib/sauce_bindings.rb

@@ -2,6 +2,7 @@
 
 require 'sauce_bindings/version'
 require 'sauce_bindings/options'
+require 'sauce_bindings/errors'
 require 'sauce_bindings/session'
 require 'sauce_bindings/base_configurations'
 require 'sauce_bindings/vdc_configurations'
@@ -10,3 +11,10 @@ require 'sauce_bindings/edge_configurations'
 require 'sauce_bindings/firefox_configurations'
 require 'sauce_bindings/ie_configurations'
 require 'sauce_bindings/safari_configurations'
+require 'sauce_bindings/logger'
+
+module SauceBindings
+  def self.logger
+    @logger ||= Logger.new
+  end
+end

data/sauce_bindings.gemspec

@@ -9,7 +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.required_ruby_version = '>= 2.7.0'
 
   spec.summary       = 'Simple interface for interacting with Sauce Labs.'
   spec.description   = 'Reduces complexity in user code for running Selenium tests on Sauce Labs'
@@ -22,14 +22,14 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'capybara', '~> 3.16'
-  spec.add_development_dependency 'rake', '>= 12.3.3'
+  spec.add_development_dependency 'climate_control', '~> 1.1'
+  spec.add_development_dependency 'parallel_split_test', '~> 0.10'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop', '~> 1.0'
-  spec.add_development_dependency 'rubocop-performance'
   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.7'
+  spec.add_runtime_dependency 'sauce_whisk', '~> 0.3.2'
+  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.0'
 end

data/spec/integration/desktop_spec.rb

@@ -4,9 +4,9 @@ require 'spec_helper'
 
 module SauceBindings
   describe Session do
-    describe 'starts with data center' do
-      before { WebMock.allow_net_connect! }
+    before { WebMock.allow_net_connect! }
 
+    describe '#data_center=' do
       it 'defaults to US West' do
         @session = Session.new
         driver = @session.start
@@ -17,7 +17,8 @@ module SauceBindings
 
       it 'executes on US East' do
         options = Options.chrome(platform_name: 'Linux')
-        @session = Session.new(options, data_center: :US_EAST)
+        @session = Session.new(options)
+        @session.data_center = :US_EAST
         driver = @session.start
 
         expect(driver).not_to be_nil
@@ -25,7 +26,8 @@ module SauceBindings
       end
 
       it 'executes on EU Central' do
-        @session = Session.new(data_center: :EU_CENTRAL)
+        @session = Session.new
+        @session.data_center = :EU_CENTRAL
         driver = @session.start
 
         expect(driver).not_to be_nil
@@ -34,12 +36,30 @@ module SauceBindings
 
       it 'executes on APAC' do
         pending 'Adding Data Center to Sauce Whisk'
-        @session = Session.new(data_center: :APAC_SOUTHEAST)
+        @session = Session.new
+        @session.data_center = :APAC_SOUTHEAST
         driver = @session.start
 
         expect(driver).not_to be_nil
         expect(@session.url).to include('apac-southeast-1')
       end
     end
+
+    describe '#stop_network' do
+      it 'stops and starts the network' do
+        @session = Session.new(Options.safari)
+        driver = @session.start
+
+        @session.stop_network
+        driver.get('https://www.saucedemo.com')
+
+        expect(driver.title).to eq 'Failed to open page'
+
+        @session.start_network
+        driver.get('https://www.saucedemo.com')
+
+        expect(driver.title).to eq 'Swag Labs'
+      end
+    end
   end
 end

data/spec/spec_helper.rb

@@ -3,13 +3,51 @@
 require 'sauce_bindings'
 require 'rspec'
 require 'webmock/rspec'
+require 'climate_control'
 
 RSpec.configure do |config|
   config.expect_with :rspec do |c|
     c.syntax = :expect
   end
 
+  config.before(:suite) do
+    BUILD_ENV = {BUILD_TAG: '', BUILD_NAME: 'TEMP BUILD', BUILD_NUMBER: '11'}.freeze
+    SAUCE_ACCESS = {SAUCE_USERNAME: 'foo', SAUCE_ACCESS_KEY: '123'}.freeze
+  end
+
   config.after do |example|
-    @session&.stop(!example.exception)
+    @session&.stop(!example.exception) if @session&.session_id != '0'
+  end
+end
+
+DEPRECATION_WARNINGS = %i[options_init timeouts].freeze
+
+DEPRECATION_WARNINGS.each do |deprecation|
+  RSpec::Matchers.define "have_deprecated_#{deprecation}" do
+    match do |actual|
+      return actual.call if ENV['IGNORE_DEPRECATIONS']
+
+      warning = /\[DEPRECATION\] \[:#{deprecation}/
+      expect {
+        actual.call
+        @stdout_message = File.read $stdout if $stdout.is_a?(File)
+      }.to output(warning).to_stdout_from_any_process
+    end
+
+    failure_message do |_actual|
+      return 'unexpected exception in the custom matcher block' unless @stdout_message
+
+      deprecations_found = @stdout_message[/WARN Watir \[DEPRECATION\] ([^.*\ ]*)/, 1]
+      but_message = if deprecations_found.nil?
+                      'no Warnings were found'
+                    else
+                      "deprecation Warning of #{deprecations_found} was found instead"
+                    end
+      "expected Warning message of \"#{deprecation}\" being deprecated, but #{but_message}"
+    end
+
+    def supports_block_expectations?
+      true
+    end
   end
 end