bugsnag-maze-runner 6.27.0

data/lib/maze/driver/resilient_appium.rb

@@ -0,0 +1,51 @@
+require 'appium_lib'
+require_relative '../logger'
+
+module Maze
+  module Driver
+    # Handles Appium driver restarts and retries in the case of failure. BrowserStack's iOS 10 and 11 iOS devices in
+    # particular seemed prone to the underlying Appium connection failing.
+    #
+    # For methods available on this class, @see AppAutomateDriver.
+    class ResilientAppium
+      # Creates the Appium Driver
+      #
+      # @param server_url [String] URL of the Appium server
+      # @param capabilities [Hash] a hash of capabilities to be used in this test run
+      # @param locator [Symbol] the primary locator strategy Appium should use to find elements
+      def initialize(server_url, capabilities, locator = :id)
+        @driver = Appium.new server_url,
+                             capabilities,
+                             locator
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @driver.respond_to_missing? method_name, include_private
+      end
+
+      def method_missing(method, *args, &block)
+        return super unless @driver.respond_to?(method)
+
+        retries = 0
+        until retries >= 5
+          begin
+            return @driver.send(method, *args, &block)
+          rescue Selenium::WebDriver::Error::UnknownError, Selenium::WebDriver::Error::WebDriverError => error
+            retries += 1
+            $logger.warn 'Appium Error occurred - restarting driver:'
+            $logger.warn error
+            sleep 3
+            restart
+          end
+        end
+
+        # Re-raise the last error, although it might be better to re-raise the
+        # first error instead.  Review based on whether we ever hit this.
+        return if error.nil?
+
+        $logger.error 'Maximum retries exceeded - raising the last error'
+        raise error
+      end
+    end
+  end
+end

data/lib/maze/errors.rb

@@ -0,0 +1,20 @@
+module Maze
+  module Error
+    # An error raised when an appium element cannot be found
+    class AppiumElementNotFoundError < StandardError
+
+      # @# @!attribute [r] element
+      #   @return [String] The named element that could not be found
+      attr_reader :element
+
+      # Creates the error
+      #
+      # @param message [String] The error to display
+      # @param element [String] The name of the element that could not be located
+      def initialize(message='Element not found', element='No element specified')
+        @element = element
+        super(message)
+      end
+    end
+  end
+end

data/lib/maze/helper.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+require 'json'
+
+# A collection of helper routines
+module Maze
+  # Miscellaneous helper functions.
+  module Helper
+    class << self
+      # Parses a request's query string, because WEBrick doesn't in POST requests
+      #
+      # @param request [Hash] The received request
+      #
+      # @return [Hash] The parsed query string.
+      def parse_querystring(request)
+        CGI.parse(request[:request].query_string)
+      end
+
+      # Enables traversal of a hash using Mongo-style dot notation.
+      #
+      # @example hash["array"][0]["item"] becomes "hash.array.0.item"
+      #
+      # @param hash [Hash] The hash to traverse
+      # @param key_path [String] The dot notation path within the hash
+      #
+      # @return [Any] The value found by the key path
+      def read_key_path(hash, key_path)
+        value = hash
+        key_path.split('.').each do |key|
+          if key =~ /^(\d+)$/
+            key = key.to_i
+            if value.length > key
+              value = value[key]
+            else
+              return nil
+            end
+          else
+            if value.key? key
+              value = value[key]
+            else
+              return nil
+            end
+          end
+        end
+        value
+      end
+
+      # Determines if the Bugsnag-Integrity header is valid.
+      # Whether a missing header is deemed valid depends on @see Maze.config.enforce_bugsnag_integrity.
+      #
+      # @return [Boolean] True if the header is present and valid, or not present and not enforced.  False otherwise.
+      def valid_bugsnag_integrity_header(request)
+        header = request[:request]['Bugsnag-Integrity']
+        return !Maze.config.enforce_bugsnag_integrity if header.nil?
+
+        digests = request[:digests]
+        if header.start_with?('sha1')
+          computed_digest = "sha1 #{digests[:sha1]}"
+        elsif header.start_with?('simple')
+          computed_digest = "simple #{digests[:simple]}"
+        else
+          return false
+        end
+        header == computed_digest
+      end
+
+      # Nil-safe version of File.expand_path
+      #
+      # @param path [String] Path to expand
+      #
+      # @return [String] Expanded path, or nil if path is nil.
+      def expand_path(path)
+        return nil unless path
+
+        File.expand_path path
+      end
+
+      # Helps interpret "@file" arguments.  I.e. if the argument starts with an "@",
+      # read the contents of the filename given.
+      def read_at_arg_file(argument)
+        return nil if argument.nil?
+        return argument unless argument.start_with? '@'
+
+        file = argument[1..argument.size]
+        File.read file
+      end
+
+      # Returns the current platform all lower-case.
+      # @return Typically 'ios', 'android', 'mac' or 'browser'
+      def get_current_platform
+        if Maze.mode == :browser
+          os = 'browser'
+        else
+          os = case Maze.config.farm
+               when :bs
+                 Maze.config.capabilities['os']
+               when :sl
+                 Maze.driver.capabilities['platformName']
+               else
+                 Maze.config.os
+               end
+          os = os&.downcase
+        end
+
+        raise('Unable to determine the current platform') if os.nil?
+
+        os
+      end
+
+      # Returns the name of the scenario to
+      # @param string [String] a string to convert to a file name
+      def to_friendly_filename(string)
+        string.gsub(/[:"& ]/, "_").gsub(/_+/, "_")
+      end
+    end
+  end
+end

data/lib/maze/hooks/appium_hooks.rb

@@ -0,0 +1,216 @@
+# Contains logic for the Cucumber hooks when in Appium mode
+module Maze
+  module Hooks
+    # Hooks for Appium mode use
+    class AppiumHooks < InternalHooks
+      def before_all
+        # Setup Appium capabilities.  Note that the 'app' capability is
+        # set in a hook as it will change if uploaded to BrowserStack.
+
+        config = Maze.config
+        case config.farm
+        when :bs
+          tunnel_id = SecureRandom.uuid
+          config.app = Maze::BrowserStackUtils.upload_app config.username,
+                                                          config.access_key,
+                                                          config.app
+          Maze::BrowserStackUtils.start_local_tunnel config.bs_local,
+                                                     tunnel_id,
+                                                     config.access_key
+        when :sl
+          config.app = Maze::SauceLabsUtils.upload_app config.username,
+                                                       config.access_key,
+                                                       config.app
+          tunnel_id = SecureRandom.uuid
+          Maze::SauceLabsUtils.start_sauce_connect config.sl_local,
+                                                   tunnel_id,
+                                                   config.username,
+                                                   config.access_key
+        when :bb
+          if ENV['BUILDKITE']
+            credentials = Maze::BitBarUtils.account_credentials config.tms_uri
+            config.username = credentials[:username]
+            config.access_key = credentials[:access_key]
+          end
+          config.app = Maze::BitBarUtils.upload_app config.access_key,
+                                                    config.app
+          Maze::SmartBearUtils.start_local_tunnel config.sb_local,
+                                                  config.username,
+                                                  config.access_key
+        when :local
+          # Attempt to start the local appium server
+          appium_uri = URI(config.appium_server_url)
+          Maze::AppiumServer.start(address: appium_uri.host, port: appium_uri.port) if config.start_appium
+        end
+
+        start_driver(config, tunnel_id)
+
+        # Ensure the device is unlocked
+        Maze.driver.unlock
+
+        # Write links to device farm sessions, where applicable
+        write_session_link
+      end
+
+      def before
+        Maze.driver.start_driver if Maze.config.farm != :none && Maze.config.appium_session_isolation
+
+        # Launch the app on macOS, if Appium is being used
+        Maze.driver.get(Maze.config.app) if Maze.driver && Maze.config.os == 'macos'
+      end
+
+      def after
+        if Maze.config.appium_session_isolation
+          Maze.driver.driver_quit
+        elsif Maze.config.os == 'macos'
+          # Close the app - without the sleep, launching the app for the next scenario intermittently fails
+          system("killall -KILL #{Maze.config.app} && sleep 1")
+        elsif [:bb].include? Maze.config.farm
+          Maze.driver.launch_app
+        else
+          Maze.driver.reset
+        end
+      end
+
+      def at_exit
+        # Stop the Appium session and server
+        Maze.driver.driver_quit unless Maze.config.appium_session_isolation
+        Maze::AppiumServer.stop if Maze::AppiumServer.running
+
+        if Maze.config.farm == :local && Maze.config.os == 'macos'
+          # Acquire and output the logs for the current session
+          Maze::Runner.run_command("log show --predicate '(process == \"#{Maze.config.app}\")' --style syslog --start '#{Maze.start_time}' > #{Maze.config.app}.log")
+        elsif Maze.config.farm == :bs
+          Maze::BrowserStackUtils.stop_local_tunnel
+        elsif Maze.config.farm == :sl
+          $logger.info 'Stopping Sauce Connect'
+          Maze::SauceLabsUtils.stop_sauce_connect
+        elsif Maze.config.farm == :bb
+          Maze::SmartBearUtils.stop_local_tunnel
+          Maze::BitBarUtils.release_account(Maze.config.tms_uri) if ENV['BUILDKITE']
+        end
+      end
+
+      def write_session_link
+        config = Maze.config
+        if config.farm == :bs && (config.device || config.browser)
+          # Log a link to the BrowserStack session search dashboard
+          build = Maze.driver.capabilities[:build]
+          url = "https://app-automate.browserstack.com/dashboard/v2/search?query=#{build}&type=builds"
+          if ENV['BUILDKITE']
+            $logger.info Maze::LogUtil.linkify url, 'BrowserStack session(s)'
+          else
+            $logger.info "BrowserStack session(s): #{url}"
+          end
+        end
+      end
+
+      def device_capabilities(config, tunnel_id = nil)
+        case config.farm
+        when :bs
+          capabilities = Maze::Capabilities.for_browser_stack_device config.device,
+                                                                     tunnel_id,
+                                                                     config.appium_version,
+                                                                     config.capabilities_option
+          capabilities['app'] = config.app
+        when :sl
+          capabilities = Maze::Capabilities.for_sauce_labs_device config.device,
+                                                                  config.os,
+                                                                  config.os_version,
+                                                                  tunnel_id,
+                                                                  config.appium_version,
+                                                                  config.capabilities_option
+          capabilities['app'] = "storage:#{config.app}"
+        when :local
+          capabilities = Maze::Capabilities.for_local config.os,
+                                                      config.capabilities_option,
+                                                      config.apple_team_id,
+                                                      config.device_id
+          capabilities['app'] = config.app
+        when :bb
+          capabilities = Maze::Capabilities.for_bitbar_device config.access_key,
+                                                              config.device,
+                                                              config.os,
+                                                              config.os_version,
+                                                              config.capabilities_option
+          capabilities['bitbar_app'] = config.app
+          capabilities['bundleId'] = config.app_bundle_id
+        end
+        capabilities
+      end
+
+      def create_driver(config)
+        if Maze.config.resilient
+          $logger.info 'Creating ResilientAppium driver instance'
+          Maze::Driver::ResilientAppium.new config.appium_server_url,
+                                            config.capabilities,
+                                            config.locator
+        else
+          $logger.info 'Creating Appium driver instance'
+          Maze::Driver::Appium.new config.appium_server_url,
+                                   config.capabilities,
+                                   config.locator
+        end
+      end
+
+      def start_driver(config, tunnel_id = nil)
+        retry_failure = config.device_list.nil? || config.device_list.empty?
+        until Maze.driver
+          begin
+            config.capabilities = device_capabilities(config, tunnel_id)
+            driver = create_driver(config)
+
+            start_driver_closure = Proc.new do
+              begin
+                driver.start_driver
+                true
+              rescue => start_error
+                raise start_error unless retry_failure
+                false
+              end
+            end
+
+            unless config.appium_session_isolation
+              if retry_failure
+                wait = Maze::Wait.new(interval: 10, timeout: 60)
+                success = wait.until(&start_driver_closure)
+
+                unless success
+                  $logger.error 'Appium driver failed to start after 6 attempts in 60 seconds'
+                  raise RuntimeError.new('Appium driver failed to start in 60 seconds')
+                end
+              else
+                start_driver_closure.call
+              end
+            end
+
+            # Infer OS version if necessary when running locally
+            if Maze.config.farm == :local && Maze.config.os_version.nil?
+              version = case Maze.config.os
+              when 'android'
+                driver.session_capabilities['platformVersion'].to_f
+              when 'ios'
+                driver.session_capabilities['sdkVersion'].to_f
+              end
+              $logger.info "Inferred OS version to be #{version}"
+              Maze.config.os_version = version
+            end
+
+            Maze.driver = driver
+          rescue Selenium::WebDriver::Error::UnknownError => original_exception
+            $logger.warn "Attempt to acquire #{config.device} device from farm #{config.farm} failed"
+            $logger.warn "Exception: #{original_exception.message}"
+            if config.device_list.empty?
+              $logger.error 'No further devices to try - raising original exception'
+              raise original_exception
+            else
+              config.device = config.device_list.first
+              config.device_list = config.device_list.drop(1)
+              $logger.warn "Retrying driver initialisation using next device: #{config.device}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/maze/hooks/browser_hooks.rb

@@ -0,0 +1,68 @@
+# Contains logic for the Cucumber hooks when in Browser mode
+module Maze
+  module Hooks
+    # Hooks for Browser mode use
+    class BrowserHooks < InternalHooks
+      def before_all
+        config = Maze.config
+        case config.farm
+        when :bs
+          # BrowserStack browser
+          tunnel_id = SecureRandom.uuid
+          config.capabilities = Maze::Capabilities.for_browser_stack_browser config.browser,
+                                                                             tunnel_id,
+                                                                             config.capabilities_option
+          Maze::BrowserStackUtils.start_local_tunnel config.bs_local,
+                                                     tunnel_id,
+                                                     config.access_key
+        when :cbt
+          # CrossBrowserTesting browser
+          tunnel_id = SecureRandom.uuid
+          config.capabilities = Maze::Capabilities.for_cbt_browser config.browser,
+                                                                   tunnel_id,
+                                                                   config.capabilities_option
+          Maze::SmartBearUtils.start_local_tunnel config.sb_local,
+                                                  config.username,
+                                                  config.access_key,
+                                                  tunnel_id
+        end
+
+        # Create and start the relevant driver
+        case config.farm
+        when :cbt
+          selenium_url = "http://#{config.username}:#{config.access_key}@hub.crossbrowsertesting.com:80/wd/hub"
+          Maze.driver = Maze::Driver::Browser.new :remote, selenium_url, config.capabilities
+        when :bs
+          selenium_url = "http://#{config.username}:#{config.access_key}@hub.browserstack.com/wd/hub"
+          Maze.driver = Maze::Driver::Browser.new :remote, selenium_url, config.capabilities
+        when :local
+          Maze.driver = Maze::Driver::Browser.new Maze.config.browser.to_sym
+        end
+
+        # Write links to device farm sessions, where applicable
+        write_session_link
+      end
+
+      def at_exit
+        if Maze.config.farm == :bs
+          Maze::BrowserStackUtils.stop_local_tunnel
+          Maze.driver.driver_quit
+        end
+      end
+
+      def write_session_link
+        config = Maze.config
+        if config.farm == :bs
+          # Log a link to the BrowserStack session search dashboard
+          build = Maze.driver.capabilities[:build]
+          url = "https://automate.browserstack.com/dashboard/v2/search?query=#{build}&type=builds"
+          if ENV['BUILDKITE']
+            $logger.info Maze::LogUtil.linkify url, 'BrowserStack session(s)'
+          else
+            $logger.info "BrowserStack session(s): #{url}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/maze/hooks/command_hooks.rb

@@ -0,0 +1,9 @@
+# Contains logic for the Cucumber hooks when in Command mode
+module Maze
+  module Hooks
+    # Hooks for Command mode use
+    class CommandHooks < InternalHooks
+      # Nothing required at present
+    end
+  end
+end

data/lib/maze/hooks/hooks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Maze
+  module Hooks
+    # Provides the ability for callbacks to be provided as part of running Cucumber.
+    # These are akin to Cucumber's BeforeAll, Before, After and AfterAll hooks, but are invoked in such a way that
+    # Maze Runner's hooks do not interfere with callbacks registered by clients.
+    class Hooks
+      def initialize
+        @before_all = []
+        @before = []
+        @after = []
+      end
+
+      # Register blocks to be called from a Cucumber BeforeAll hook (after MazeRunner does everything it needs to)
+      def before_all(&block)
+        @before_all << block
+      end
+
+      # Register blocks to be called from a Cucumber Before hook (after MazeRunner does everything it needs to)
+      def before(&block)
+        @before << block
+      end
+
+      # Register blocks to be called from a Cucumber After hook (before MazeRunner does everything it needs to)
+      def after(&block)
+        @after << block
+      end
+
+      # For MazeRunner use only, call the registered BeforeAll blocks
+      def call_before_all
+        @before_all.each(&:call)
+      end
+
+      # For MazeRunner use only, call the registered Before blocks
+      # @param scenario The current Cucumber scenario
+      def call_before(scenario)
+        @before.each { |block| block.call(scenario) }
+      end
+
+      # For MazeRunner use only, call the registered After blocks
+      # @param scenario The current Cucumber scenario
+      def call_after(scenario)
+        @after.each { |block| block.call(scenario) }
+      end
+    end
+
+    # Base class for hooks internal to Maze Runner
+    class InternalHooks
+      def before_all; end
+
+      def before; end
+
+      def after; end
+
+      def after_all; end
+
+      def at_exit; end
+    end
+  end
+end