automation_helpers 4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e31fd999ded8a53243daee17b49c7d85c65c54c0c75ab657669b4e8753f0efc4
+  data.tar.gz: e0abb956e546004f43b9367f0c5e5bf6dbb51770f575642d6e00bfd1b5b0bcbf
+SHA512:
+  metadata.gz: 8f981fb29c66cd31b7a08459f4804cdf0917550547aeafddc1397b861b9f0935d03270db452e7cccbabd954425ab5d19e96b8c307a727b1123c842688cb5d558
+  data.tar.gz: 61a8a6dcbb015412438984f39983ea02073f15c9097428ba8cde64cfb4716b50c6dc73e68d0da9efea64b4cd86a197dfdea5e1030642c8c365191c734445a5ee

data/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright (c) 2020-2021, The SitePrism team & Marcelo Nicolosi Santos
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,49 @@
+# Automation Helpers
+
+#### The new OSS name for the gem formerly known as ca_testing
+
+This package will allow you to extend your automated testing frameworks with the following
+- Driver creation: Allowing you to simply reference your drivers with a simple method
+(**No more confusing capability classes / methods**)
+- Simple extensions to regular classes (A bit like ActiveSupport where it's needed / common)
+- Extensions to the commonly used Automation Packages (Selenium / Capybara e.t.c.), DSL's
+(Think of things like enhancing `Capybara::Node::Element` e.t.c.)
+- Patches required to allow instant fixing of bugs in upstream repos whilst fixes are
+in PR and being reviewed / merged
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'automation_helpers'
+```
+
+And then execute:
+
+```shell
+$ bundle
+```
+
+## Usage
+
+Either require all of the extensions required, or require individual bits and pieces
+
+## Development
+
+```
+$ bundle
+# Code anything relevant - Add tests for each public method!
+$ bundle exec rake
+# Ensure it's all green! Then commit and push
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/site-prism/automation_helpers
+
+## Verbose Documentation
+
+This will come in time. Meanwhile if you check the gem code some of the methods are now
+beginning to get documented. Also check the specs

data/lib/automation_helpers/drivers/browserstack.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'automation_helpers/drivers/v4/browserstack'
+
+module AutomationHelpers
+  module Drivers
+    Browserstack = V4::Browserstack
+  end
+end

data/lib/automation_helpers/drivers/local.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'automation_helpers/drivers/v4/local'
+
+module AutomationHelpers
+  module Drivers
+    Local = V4::Local
+  end
+end

data/lib/automation_helpers/drivers/remote.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'automation_helpers/drivers/v4/remote'
+
+module AutomationHelpers
+  module Drivers
+    Remote = V4::Remote
+  end
+end

data/lib/automation_helpers/drivers/v4/browserstack.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'selenium/webdriver'
+
+require 'automation_helpers/drivers/v4/capabilities'
+require 'automation_helpers/drivers/v4/options'
+
+module AutomationHelpers
+  module Drivers
+    module V4
+      #
+      # {AutomationHelpers::Drivers::V4::Browserstack}
+      #
+      # The Browserstack Driver that will connect to a hosted grid
+      # Requires a series of pre-set values to be passed in
+      #
+      class Browserstack
+        attr_reader :browser, :browserstack_options, :device_options
+        private :browser, :browserstack_options, :device_options
+
+        # #### Initial setup options
+        #
+        # - **browser** (required) - When instantiating, the first argument must be the symbol that represents what browser to use
+        # - **browserstack_options** (required) - A Hash of all required options that will be parsed and used to setup the driver
+        #   - :build_name (String)               -> The build name to be stored on browserstack servers
+        #   - :project_name (String)             -> The project name to be stored on browserstack servers
+        #   - :session_name (String)             -> The session name to be stored on browserstack servers
+        #   - :browserstack_debug_mode (Boolean) -> Set this to true to run in browserstack debug mode (Note this runs slower!)
+        #   - :config (String)                   -> This is an underscore separated key that distils the granular running information
+        #     i.e. Windows_7_86 means run on Windows Operating System, OS Version 7, Browser Version 86
+        #     i.e. OSX_Mojave_12 means run on Mac Operating System, OS Version Mojave, Browser Version 12
+        #     i.e. Windows_10_92 means run on Windows Operating System, OS Version 10, Browser Version 92
+        #   - :username (String)                 -> The username for Browserstack
+        #   - :api_key (String)                  -> The api key for Browserstack
+        #
+        def initialize(browser, browserstack_options, device_options = {})
+          @browser = browser
+          @browserstack_options = browserstack_options
+          @device_options = device_options
+        end
+
+        # @return [Nil]
+        #
+        # Register a new driver with the default selenium name for use in a remote browserstack setup
+        def register
+          Capybara.register_driver :selenium do |app|
+            Capybara::Selenium::Driver.new(
+              app,
+              browser: :remote,
+              capabilities: [desired_capabilities, options],
+              url: browserstack_hub_url
+            )
+          end
+        end
+
+        private
+
+        def desired_capabilities
+          Selenium::WebDriver::Remote::Capabilities.new(
+            ::Faraday::Utils.deep_merge(
+              # Browserstack Capabilities and General Capabilities are at different levels, so we merge first
+              browserstack_capabilities.merge(browser_version_capability),
+              # Then we deep merge with anything specifically passed into the driver registration (as these can be nested)
+              browser_specific_capabilities.as_json
+            )
+          )
+        end
+
+        def browserstack_capabilities
+          ::Faraday::Utils.deep_merge(configurable_capabilities, static_capabilities)
+        end
+
+        def configurable_capabilities
+          {
+            'bstack:options' => {
+              'buildName' => browserstack_options[:build_name],
+              'projectName' => browserstack_options[:project_name],
+              'sessionName' => browserstack_options[:session_name],
+              'debug' => browserstack_options[:browserstack_debug_mode],
+              'os' => os,
+              'osVersion' => os_version
+            }
+          }
+        end
+
+        def static_capabilities
+          {
+            'bstack:options' => {
+              'local' => 'false',
+              'seleniumVersion' => '4.0.0-alpha-6',
+              'consoleLogs' => 'verbose',
+              'networkLogs' => 'true',
+              'resolution' => '1920x1080'
+            }
+          }
+        end
+
+        def browser_specific_capabilities
+          Capabilities.for(browser, device_options)
+        end
+
+        def browser_version_capability
+          return {} if device?
+
+          { 'browserVersion' => browser_version }
+        end
+
+        def options
+          Options.for(browser)
+        end
+
+        def browserstack_hub_url
+          "https://#{browserstack_options[:username]}:#{browserstack_options[:api_key]}@hub-cloud.browserstack.com/wd/hub"
+        end
+
+        def os
+          browserstack_options[:config].split('_')[0]
+        end
+
+        def os_version
+          browserstack_options[:config].split('_')[1]
+        end
+
+        def browser_version
+          browserstack_options[:config].split('_')[2]
+        end
+
+        def device?
+          %i[android ios].include?(browser)
+        end
+      end
+    end
+  end
+end

data/lib/automation_helpers/drivers/v4/capabilities.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'selenium/webdriver'
+
+module AutomationHelpers
+  module Drivers
+    module V4
+      #
+      # {AutomationHelpers::Drivers::V4::Capabilities}
+      #
+      # The Capabilities object that will be used to instantiate whatever driver you
+      # are configuring
+      #
+      class Capabilities
+        class << self
+          # @return [Selenium::WebDriver::Remote::Capabilities]
+          #
+          # Returns the Capabilities hash relevant to the browser specified to be passed to the driver instantiation
+          def for(browser, device_options = {})
+            ::Selenium::WebDriver::Remote::Capabilities.new(capabilities_hash(browser, device_options))
+          end
+
+          private
+
+          def capabilities_hash(browser, device_options)
+            case browser
+            when :android;           then android_capabilities(device_options)
+            when :chrome;            then chrome_capabilities
+            when :firefox;           then firefox_capabilities
+            when :internet_explorer; then internet_explorer_capabilities
+            when :ios;               then ios_capabilities(device_options)
+            else {}
+            end
+          end
+
+          def android_capabilities(device_options)
+            {
+              'bstack:options' => {
+                'deviceName' => device_options[:device_name],
+                'realMobile' => 'true',
+                'appiumVersion' => android_appium_version(device_options[:os_version])
+              }
+            }
+          end
+
+          def chrome_capabilities
+            {
+              'browserName' => 'chrome',
+              'goog:loggingPrefs' => {
+                'browser' => 'ALL',
+                'driver' => 'ALL'
+              }
+            }
+          end
+
+          def firefox_capabilities
+            {
+              'browserName' => 'firefox'
+            }
+          end
+
+          def internet_explorer_capabilities
+            {
+              'browserName' => 'internet explorer',
+              'bstack:options' => {
+                'ie' => {
+                  # This is a minor hack until the IEDriver catches up and releases a V4 compliant copy
+                  # It is confirmed to be compliant with V4 selenium jars e.t.c.
+                  'driver' => '3.141.59',
+                  'arch' => 'x32'
+                }
+              }
+            }
+          end
+
+          def ios_capabilities(device_options)
+            {
+              'bstack:options' => {
+                'deviceName' => device_options[:device_name],
+                'realMobile' => 'true',
+                'appiumVersion' => ios_appium_version(device_options[:os_version])
+              }
+            }
+          end
+
+          def android_appium_version(android_version)
+            case android_version.to_f
+            when 10..; then '1.21.0'
+            when 9..;  then '1.20.2'
+            else raise ArgumentError, "Your Android Version is too low. Please don't use lower than Android Pie (9)."
+            end
+          end
+
+          def ios_appium_version(ios_version)
+            case ios_version.to_f
+            when 13..; then '1.21.0'
+            when 12..; then '1.20.2'
+            when 11..; then '1.16.0'
+            else raise ArgumentError, "Your iOS Version is too low. Please don't use lower than iOS 11."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/automation_helpers/drivers/v4/local.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'selenium/webdriver'
+
+require 'automation_helpers/drivers/v4/options'
+
+module AutomationHelpers
+  module Drivers
+    module V4
+      #
+      # {AutomationHelpers::Drivers::V4::Local}
+      #
+      # The Local Driver that will spin up and run on your machine (Without connecting to any grid)
+      #
+      class Local
+        attr_reader :browser
+        private :browser
+
+        # #### Initial setup options
+        #
+        # - **browser** (required) - When instantiating, the first argument must be the symbol that represents what browser to use
+        #
+        def initialize(browser)
+          @browser = browser
+        end
+
+        # @return [Nil]
+        #
+        # Register a new driver with the default selenium name for use locally
+        def register
+          Capybara.register_driver :selenium do |app|
+            Capybara::Selenium::Driver.new(
+              app,
+              browser: browser,
+              service: service,
+              capabilities: capabilities
+            )
+          end
+        end
+
+        # @return [Array]
+        #
+        # The order of these capabilities is important because in the internal configuration
+        # for the driver; these 2 objects are merged (And both will contain a browserName)
+        # as such we need to ensure the browserName we manually set in `desired_capabilities`
+        # is retained as this is the one required by safari
+        def capabilities
+          if safari?
+            [options, desired_capabilities]
+          else
+            [desired_capabilities, options]
+          end
+        end
+
+        private
+
+        # This is required to make local drivers work exclusively with Safari TP
+        # This is required in V13 of Safari as the driver there is notoriously flaky
+        # In V12 it doesn't hinder it
+        # Safari V11 is unsupported.
+        def service
+          return unless safari?
+
+          ::Selenium::WebDriver::Safari.technology_preview!
+          ::Selenium::WebDriver::Service.safari(args: ['--diagnose'])
+        end
+
+        # This is required because Capybara and Safari aren't quite sure what the difference
+        # is between the two browsers. So to compensate an illegal browserName value is
+        # set that allows easy distinction between the two browsers
+        #
+        # NB: Whilst using Safari TP this is required.
+        def desired_capabilities
+          ::Selenium::WebDriver::Remote::Capabilities.new.tap do |capabilities|
+            if safari?
+              capabilities['browserName'] = 'Safari Technology Preview'
+              AutomationHelpers.logger.warn('Altering Browser Name request to alleviate Capybara failure with STP.')
+            end
+          end
+        end
+
+        def options
+          Options.for(browser)
+        end
+
+        def safari?
+          browser == :safari
+        end
+      end
+    end
+  end
+end

data/lib/automation_helpers/drivers/v4/options.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'selenium/webdriver'
+
+module AutomationHelpers
+  module Drivers
+    module V4
+      #
+      # {AutomationHelpers::Drivers::V4::Options}
+      #
+      # The Options object that will be used to instantiate whatever driver you
+      # are configuring
+      #
+      class Options
+        class << self
+          # @return [Selenium::Webdriver::Options]
+          #
+          # Returns the Options payload relevant to the browser specified to be passed to the driver instantiation
+          def for(browser)
+            initial_options(browser).tap { |opts| opts.headless! if headless? }
+          end
+
+          private
+
+          def initial_options(browser)
+            case browser
+            when :chrome;             then ::Selenium::WebDriver::Chrome::Options.new
+            when :firefox;            then ::Selenium::WebDriver::Firefox::Options.new(log_level: 'trace')
+            when :edge;               then ::Selenium::WebDriver::Edge::Options.new
+            when :safari;             then ::Selenium::WebDriver::Safari::Options.new(automatic_inspection: true)
+            when :internet_explorer;  then internet_explorer_options
+            else {}
+            end
+          end
+
+          # Constantly fire mouseOver events on click actions (Should help mitigate flaky clicks)
+          def internet_explorer_options
+            ::Selenium::WebDriver::IE::Options.new(persistent_hover: true).tap do |opts|
+              # This can be removed once we migrate past Se4 proper (As the space version name is present there)
+              AutomationHelpers.logger.info('Removing `browser_name` key from options payload.')
+              opts.options.delete(:browser_name)
+            end
+          end
+
+          def headless?
+            ENV['HEADLESS'] == 'true'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/automation_helpers/drivers/v4/remote.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'automation_helpers/drivers/v4/capabilities'
+require 'automation_helpers/drivers/v4/options'
+
+module AutomationHelpers
+  module Drivers
+    module V4
+      #
+      # {AutomationHelpers::Drivers::V4::Remote}
+      #
+      # The Remote Driver that will connect to a dockerised self-hosted grid
+      # Expects the grid to be live and accepting node requests
+      #
+      class Remote
+        attr_reader :browser
+        private :browser
+
+        # #### Initial setup options
+        #
+        # - **browser** (required) - When instantiating, the first argument must be the symbol that represents what browser to use
+        # - **ENV["HUB_URL"]** (required) - The environment variable HUB_URL must be set to the actively running dockerised grid
+        #   (By default this should be +http://hub:4444/wd/hub+)
+        def initialize(browser)
+          @browser = browser
+        end
+
+        # @return [Nil]
+        #
+        # Register a new driver with the default selenium name for use in a (localised), remote grid setup
+        def register
+          Capybara.register_driver :selenium do |app|
+            Capybara::Selenium::Driver.new(
+              app,
+              browser: :remote,
+              capabilities: [browser_capabilities, options],
+              url: hub_url
+            )
+          end
+        end
+
+        private
+
+        def browser_capabilities
+          raise ArgumentError, 'You must use a supported browser' unless supported_browser?
+
+          Capabilities.for(browser)
+        end
+
+        def options
+          Options.for(browser)
+        end
+
+        def hub_url
+          ENV['HUB_URL']
+        end
+
+        def supported_browser?
+          %i[chrome firefox].include?(browser)
+        end
+      end
+    end
+  end
+end

data/lib/automation_helpers/drivers/v4.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'automation_helpers/drivers/v4/browserstack'
+require 'automation_helpers/drivers/v4/capabilities'
+require 'automation_helpers/drivers/v4/local'
+require 'automation_helpers/drivers/v4/options'
+require 'automation_helpers/drivers/v4/remote'

data/lib/automation_helpers/drivers.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'automation_helpers/drivers/browserstack'
+require 'automation_helpers/drivers/local'
+require 'automation_helpers/drivers/remote'
+require 'automation_helpers/drivers/v4'

data/lib/automation_helpers/extensions/array.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Additional useful methods to extend the Array class with
+class Array
+  # @return [Boolean]
+  #
+  # Test whether an array is wholly unique
+  def uniq?
+    uniq == self
+  end
+
+  # @return [Array]
+  #
+  # Return the non-unique items of an array
+  def non_uniq
+    tally.select { |_key, count| count > 1 }.map(&:first)
+  end
+end

data/lib/automation_helpers/extensions/capybara/node/element.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Node
+    #
+    # Additional useful methods to extend the Capybara::Node::Element class with
+    #
+    class Element
+      # @return [Integer]
+      #
+      # The Left-Most pixel's horizontal position in the DOM (From element.rect)
+      def horizontal_position
+        native.rect.x.to_i
+      end
+
+      # @return [Integer]
+      #
+      # The Left-Most pixel's vertical position in the DOM (From element.rect)
+      def vertical_position
+        native.rect.y.to_i
+      end
+
+      # @return [Boolean]
+      #
+      # Whether the element is in a stale state or not
+      def stale?
+        inspect == 'Obsolete #<Capybara::Node::Element>'
+      end
+    end
+  end
+end

data/lib/automation_helpers/extensions/cucumber/core/test/case.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Cucumber
+  module Core
+    module Test
+      #
+      # Additional useful methods to extend the Cucumber::Core::Test::Case class with
+      #
+      class Case
+        # @return [String]
+        #
+        # The file name of the feature being ran (Without the .feature extension)
+        def feature_file_name
+          feature_file_path.split('/').last&.split('.')&.first.to_s
+        end
+
+        # @return [String]
+        #
+        # The fully qualified location of the feature being ran
+        def feature_file_path
+          location.to_s
+        end
+      end
+    end
+  end
+end