bugsnag-maze-runner 6.27.0

data/lib/maze/option/validator.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative '../option'
+require_relative '../browser_stack_devices'
+
+module Maze
+  module Option
+    # Validates command line options
+    class Validator
+      # Validates all provided options
+      # @param options [Hash] Parsed command line options
+      def validate(options)
+        errors = []
+
+        # Common options
+        farm = options[Option::FARM]
+        if farm && !%w[bs cbt sl local bb].include?(farm)
+          errors << "--#{Option::FARM} must be 'bs', 'cbt', 'sl', 'bb' or 'local' if provided"
+        end
+
+        begin
+          JSON.parse(options[Option::CAPABILITIES])
+        rescue JSON::ParserError
+          errors << "--#{Option::CAPABILITIES} must be valid JSON (given #{options[Option::CAPABILITIES]})"
+        end
+
+        # Farm specific options
+        validate_bs options, errors if farm == 'bs'
+        validate_sl options, errors if farm == 'sl'
+        validate_bitbar options, errors if farm == 'bb'
+        validate_local options, errors if farm == 'local'
+
+        errors
+      end
+
+      # Validates BrowserStack options
+      def validate_bs(options, errors)
+        # BS local binary
+        bs_local = Maze::Helper.expand_path options[Option::BS_LOCAL]
+        errors << "BrowserStack local binary '#{bs_local}' not found" unless File.exist? bs_local
+
+        # Device
+        browser = options[Option::BROWSER]
+        device = options[Option::DEVICE]
+        if browser.nil? && device.empty?
+          errors << "Either --#{Option::BROWSER} or --#{Option::DEVICE} must be specified"
+        elsif browser
+
+          browsers = YAML.safe_load(File.read("#{__dir__}/../browsers_bs.yml"))
+
+          unless browsers.include? browser
+            browser_list = browsers.keys.join ', '
+            errors << "Browser type '#{browser}' unknown on BrowserStack.  Must be one of: #{browser_list}."
+          end
+        elsif device
+          device.each do |device_key|
+            next if Maze::BrowserStackDevices::DEVICE_HASH.key? device_key
+            errors << "Device type '#{device_key}' unknown on BrowserStack.  Must be one of #{Maze::BrowserStackDevices::DEVICE_HASH.keys}"
+          end
+          # App
+          app = Maze::Helper.read_at_arg_file options[Option::APP]
+          if app.nil?
+            errors << "--#{Option::APP} must be provided when running on a device"
+          else
+            # TODO: What about Sauce Labs URLs?
+            unless app.start_with?('bs://')
+              app = Maze::Helper.expand_path app
+              errors << "app file '#{app}' not found" unless File.exist?(app)
+            end
+          end
+        end
+
+        # Credentials
+        errors << "--#{Option::USERNAME} must be specified" if options[Option::USERNAME].nil?
+        errors << "--#{Option::ACCESS_KEY} must be specified" if options[Option::ACCESS_KEY].nil?
+      end
+
+      # Validates Sauce Labs options
+      def validate_sl(options, errors)
+        # SL local binary
+        sl_local = Maze::Helper.expand_path options[Option::SL_LOCAL]
+        errors << "Sauce Connect binary '#{sl_local}' not found" unless File.exist? sl_local
+
+        # Device
+        browser = options[Option::BROWSER]
+        device = options[Option::DEVICE]
+        os = options[Option::OS]
+        os_version = options[Option::OS_VERSION]
+        if browser.nil? && device.nil? && os.nil? && os_version.nil?
+          errors << 'A device or browser option must be specified'
+        elsif browser
+          errors << 'Browsers not yet implemented on Sauce Labs'
+        else
+          # App
+          app = options[Option::APP]
+          if app.nil?
+            errors << "--#{Option::APP} must be provided when running on a device"
+          else
+            uuid_regex = /\A[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}\z/
+            unless uuid_regex.match? app
+              app = Maze::Helper.expand_path app
+              errors << "app file '#{app}' not found" unless File.exist?(app)
+            end
+          end
+
+          # OS
+          if options[Option::OS].nil?
+            errors << "--#{Option::OS} must be specified"
+          else
+            os = options[Option::OS].downcase
+            errors << 'os must be android or ios' unless %w[android ios].include? os
+          end
+
+          # OS Version
+          if options[Option::OS_VERSION].nil?
+            errors << "--#{Option::OS_VERSION} must be specified"
+          else
+            # Ensure OS version is a valid float so that notifier tests can perform numeric checks
+            # e.g 'Maze.config.os_version > 7'
+            unless /^[1-9][0-9]*(\.[0-9])?/.match? options[Option::OS_VERSION]
+              errors << "--#{Option::OS_VERSION} must be a valid version matching '/^[1-9][0-9]*(\\.[0-9])?/'"
+            end
+          end
+        end
+
+        # Credentials
+        errors << "--#{Option::USERNAME} must be specified" if options[Option::USERNAME].nil?
+        errors << "--#{Option::ACCESS_KEY} must be specified" if options[Option::ACCESS_KEY].nil?
+      end
+
+      # Validates BitBar device options
+      def validate_bitbar(options, errors)
+        if ENV['BUILDKITE']
+          errors << "--#{Option::TMS_URI} must be specified when running on Buildkite" if options[Option::TMS_URI].nil?
+        else
+          errors << "--#{Option::USERNAME} must be specified" if options[Option::USERNAME].nil?
+          errors << "--#{Option::ACCESS_KEY} must be specified" if options[Option::ACCESS_KEY].nil?
+        end
+
+        app = options[Option::APP]
+        if app.nil?
+          errors << "--#{Option::APP} must be provided when running on a device"
+        else
+          uuid_regex = /\A[0-9]+\z/
+          unless uuid_regex.match? app
+            app = Maze::Helper.expand_path app
+            errors << "app file '#{app}' not found" unless File.exist?(app)
+          end
+        end
+      end
+
+      # Validates Local device options
+      def validate_local(options, errors)
+        if options[Option::BROWSER].nil?
+          errors << "--#{Option::APP} must be specified" if options[Option::APP].nil?
+
+          # OS
+          if options[Option::OS].nil?
+            errors << "--#{Option::OS} must be specified"
+          else
+            os = options[Option::OS].downcase
+            errors << 'os must be android, ios, macos or windows' unless %w[android ios macos windows].include? os
+            if os == 'ios'
+              errors << "--#{Option::APPLE_TEAM_ID} must be specified for iOS" if options[Option::APPLE_TEAM_ID].nil?
+              errors << "--#{Option::UDID} must be specified for iOS" if options[Option::UDID].nil?
+            end
+          end
+
+          # OS Version
+          unless options[Option::OS_VERSION].nil?
+            # Ensure OS version is a valid float so that notifier tests can perform numeric checks
+            # e.g 'Maze.config.os_version > 7'
+            unless /^[1-9][0-9]*(\.[0-9])?/.match? options[Option::OS_VERSION]
+              errors << "--#{Option::OS_VERSION} must be a valid version matching '/^[1-9][0-9]*(\\.[0-9])?/'"
+            end
+          end
+        else
+          # TODO Validate browser options
+        end
+      end
+    end
+  end
+end

data/lib/maze/option.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Provides the set of Maze Runner command line options
+module Maze
+  module Option
+    # Document server options
+    DS_BIND_ADDRESS = 'document-server-bind-address'
+    DS_PORT = 'document-server-port'
+    DS_ROOT = 'document-server-root'
+
+    # Server options
+    BIND_ADDRESS = 'bind-address'
+    PORT = 'port'
+    NULL_PORT = 'null-port'
+
+    # Appium options
+    SEPARATE_SESSIONS = 'separate-sessions'
+    FARM = 'farm'
+    APP = 'app'
+    A11Y_LOCATOR = 'a11y-locator'
+    RESILIENT = 'resilient'
+    CAPABILITIES = 'capabilities'
+
+    # Generic device farm options
+    USERNAME = 'username'
+    ACCESS_KEY = 'access-key'
+    APPIUM_VERSION = 'appium-version'
+    DEVICE = 'device'
+    BROWSER = 'browser'
+    OS = 'os'
+    OS_VERSION = 'os-version'
+    LIST_DEVICES = 'list-devices'
+    APP_BUNDLE_ID = 'app-bundle-id'
+
+    # CrossBrowserTesting/Bitbar options
+    SB_LOCAL = 'sb-local'
+
+    # BrowserStack-only options
+    BS_LOCAL = 'bs-local'
+
+    # Sauce Labs-only options
+    SL_LOCAL = 'sl-local'
+
+    # BitBar-only options
+    TMS_URI = 'tms-uri'
+    TMS_TOKEN = 'tms-token'
+
+    # Local-only options
+    APPIUM_SERVER = 'appium-server'
+    START_APPIUM = 'start-appium'
+    APPIUM_LOGFILE = 'appium-logfile'
+    APPLE_TEAM_ID = 'apple-team-id'
+    UDID = 'udid'
+
+    # Logging options
+    FILE_LOG = 'file-log'
+    LOG_REQUESTS = 'log-requests'
+    ALWAYS_LOG = 'always-log'
+
+    # Runtime options
+    ENABLE_RETRIES = 'enable-retries'
+    ENABLE_BUGSNAG = 'enable-bugsnag'
+  end
+end

data/lib/maze/plugins/bugsnag_reporting_plugin.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'bugsnag'
+require 'cucumber/core/filter'
+
+# Required to access the options
+module Cucumber
+  class Configuration
+    attr_accessor :options
+  end
+end
+
+module Maze
+  module Plugins
+    class BugsnagReportingPlugin < Cucumber::Core::Filter.new(:configuration)
+
+      def test_case(test_case)
+        configuration.on_event(:test_step_finished) do |event|
+          @last_test_step = event.test_step if event.result.failed?
+        end
+
+        configuration.on_event(:test_case_finished) do |event|
+
+          # Ensure we're in the correct test case and that it's failed
+          next unless event.test_case.eql?(test_case) && event.result.failed?
+
+          Bugsnag.notify(event.result.exception) do |bsg_event|
+            unless @last_test_step.nil?
+              bsg_event.context = @last_test_step.location
+              bsg_event.grouping_hash = test_case.name + @last_test_step.location
+              bsg_event.add_metadata(:'scenario', {
+                'failing step': @last_test_step.to_s,
+                'failing step location': @last_test_step.location
+              })
+            end
+            bsg_event.add_metadata(:'scenario', {
+              'scenario name': test_case.name,
+              'scenario location': test_case.location,
+              'scenario tags': test_case.tags,
+              'scenario duration (mS)': event.result.duration.nanoseconds/1000000
+            })
+          end
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/maze/plugins/cucumber_report_plugin.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'bugsnag'
+require 'cucumber/core/filter'
+require 'json'
+
+# Required to access the options
+module Cucumber
+  class Configuration
+    attr_accessor :options
+  end
+end
+
+module Maze
+  module Plugins
+    class CucumberReportPlugin
+
+      def initialize
+        configured_data = {
+          driver_class: Maze.driver.class,
+          device_farm: Maze.config.farm,
+          device: Maze.config.device,
+          os: Maze.config.os,
+          os_version: Maze.config.os_version
+        }
+        buildkite_data = {
+          pipeline: ENV['BUILDKITE_PIPELINE_NAME'],
+          repo: ENV['BUILDKITE_REPO'],
+          build_url: ENV['BUILDKITE_BUILD_URL'],
+          branch: ENV['BUILDKITE_BRANCH'],
+          message: ENV['BUILDKITE_MESSAGE'],
+          step: ENV['BUILDKITE_LABEL'],
+          commit: ENV['BUILDKITE_COMMIT']
+        }
+        report['configuration'] = configured_data
+        report['build'] = buildkite_data
+      end
+
+      def install_plugin(cuc_config)
+        unless Maze.config.tms_uri && Maze.config.tms_token && ENV['BUILDKITE']
+          $logger.info 'No test report will be delivered for this run'
+          return
+        end
+        # Add installation hook
+        cuc_config.formats << ['json', {}, json_report_stream]
+
+        # Add exit hook
+        at_exit do
+          finish_report
+        end
+      end
+
+      def json_report_stream
+        @json_report_stream ||= StringIO.new
+      end
+
+      def report
+        @report ||= {}
+      end
+
+      private
+
+      def finish_report
+        session_hash = JSON.parse(json_report_stream.string)
+        report[:session] = session_hash
+        output_folder = File.join(Dir.pwd, 'maze_output')
+        filename = 'maze_report.json'
+        filepath = File.join(output_folder, filename)
+
+        begin
+          File.open(filepath, 'w') do |file|
+            file.puts JSON.pretty_generate(report)
+          end
+        rescue => e
+          $logger.warn 'Report could not be saved locally'
+          $logger.warn e.message
+        end
+
+        send_report
+      end
+
+      def send_report
+        uri = URI("#{Maze.config.tms_uri}/report")
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        request['Authorization'] = Maze.config.tms_token
+        request.body = JSON.generate(report)
+
+        begin
+          http = Net::HTTP.new(uri.hostname, uri.port)
+          response = http.request(request)
+        rescue => e
+          $logger.warn 'Report delivery attempt failed'
+          $logger.warn e.message
+        else
+          $logger.info 'Cucumber report delivered to test report server'
+        end
+      end
+    end
+  end
+end

data/lib/maze/plugins/global_retry_plugin.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'cucumber/core/filter'
+
+# Required to access the options
+module Cucumber
+  class Configuration
+    attr_accessor :options
+  end
+end
+
+module Maze
+  module Plugins
+    class GlobalRetryPlugin < Cucumber::Core::Filter.new(:configuration)
+
+      def test_case(test_case)
+        configuration.on_event(:test_case_finished) do |event|
+
+          # Ensure we're in the correct test case
+          next unless event.test_case == test_case
+
+          # Set retry to 0
+          configuration.options[:retry] = 0
+
+          # Guard to check if the case should be retried
+          should_retry = event.result.failed? && Maze::RetryHandler.should_retry?(test_case, event)
+
+          next unless should_retry
+
+          # Set retry to 1
+          configuration.options[:retry] = 1
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/maze/proxy.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'singleton'
+require 'webrick'
+require 'webrick/https'
+require 'webrick/httpproxy'
+
+module Maze
+  # Provides the ability to run a proxy server, using the WEBrick proxy server.
+  # Note that for an HTTPS proxy a self-signed certificate will be used.  If using curl, for example, this
+  # means having to employ the --proxy-insecure option.
+  class Proxy
+    include Singleton
+
+    # There are some constraints on the port from driving remote browsers on BrowserStack.
+    # E.g. the ports/ranges that Safari will access on "localhost" urls are restricted to the following:
+    #   80, 3000, 4000, 5000, 8000, 8080 or 9000-9999 [ from https://stackoverflow.com/a/28678652 ]
+    PORT = 9000
+
+    def initialize
+      @hosts = []
+    end
+
+    # Whether the proxy handled a request for the given host
+    #
+    # @param host [String] The destination host to test for
+    def handled_host?(host)
+      @hosts.include? host
+    end
+
+    # Whether the proxy server thread is running
+    #
+    def running?
+      @thread&.alive?
+    end
+
+    # Starts the WEBrick proxy in a separate thread
+    # If authentication if requested, then the credentials used are simply 'user' with 'password'.
+    #
+    # @param protocol [Symbol] :Http or Https
+    # @param authenticated [Boolean] Whether basic authentication should be applied.
+    def start(protocol, authenticated = false)
+      @hosts.clear
+
+      attempts = 0
+      $logger.info 'Starting proxy server'
+      loop do
+        @thread = Thread.new do
+
+          handler = proc do |req, res|
+            req.header['host'].each { |host| @hosts.append(host) }
+          end
+          config = {
+            Logger: $logger,
+            Port: PORT,
+            ProxyContentHandler: handler
+          }
+
+          # Setup protocol
+          if protocol == :Http
+            $logger.info 'Starting HTTP proxy'
+          elsif protocol == :Https
+            $logger.info 'Starting HTTPS proxy'
+            cert_name = [
+              %w[CN localhost]
+            ]
+            config[:SSLCertName] = cert_name
+            config[:SSLEnable] = true
+          else
+            raise "Unsupported protocol #{protocol}: :Http and :Https are supported"
+          end
+
+          # Authentication required?
+          if authenticated
+            # Apache compatible Password manager
+            htpasswd = WEBrick::HTTPAuth::Htpasswd.new File.expand_path('htpasswd', __dir__)
+            htpasswd.set_passwd 'Proxy Realm', 'user', 'password'
+            htpasswd.flush
+            authenticator = WEBrick::HTTPAuth::ProxyBasicAuth.new Realm: 'Proxy Realm',
+                                                                  UserDB: htpasswd
+            config[:ProxyAuthProc] = authenticator.method(:authenticate).to_proc
+          end
+
+          # Crwate and start the proxy
+          proxy = WEBrick::HTTPProxyServer.new config
+          proxy.start
+        rescue StandardError => e
+          $logger.warn "Failed to start proxy server: #{e.message}"
+        ensure
+          proxy&.shutdown
+        end
+
+        # Need a short sleep here as a dying thread is still alive momentarily
+        sleep 1
+        break if running?
+
+        # Bail out after 3 attempts
+        attempts += 1
+        raise 'Too many failed attempts to start proxy server' if attempts == 3
+
+        # Failed to start - sleep before retrying
+        $logger.info 'Retrying in 5 seconds'
+        sleep 5
+      end
+    end
+
+    # Stops the WEBrick proxy thread if it's running
+    def stop
+      @thread&.kill if @thread&.alive?
+      @thread = nil
+    end
+  end
+end

data/lib/maze/request_list.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Maze
+  # An abstraction for storing a list of requests (e.g. Errors, Sessions),
+  # keeping track of the "current" request (i.e. the one being inspected).
+  class RequestList
+    def initialize
+      @requests = []
+      @current = 0
+      @count = 0
+    end
+
+    def empty?
+      @requests.empty?
+    end
+
+    # The number of unprocessed/remaining requests in the list (not the total number actually held)
+    def size
+      @count
+    end
+
+    # The total number of requests received, including those already processed
+    def size_all
+      @requests.size
+    end
+
+    # Add a request to the list
+    #
+    # @param request The new request, from which a clone is made
+    def add(request)
+      @requests.append request.clone
+      @count += 1
+    end
+
+    # The current request
+    def current
+      @requests[@current] if @requests.size > @current
+    end
+
+    # Peek at requests yet to be processed - i.e. from current onwards.  All requests are left visible in the list.
+    # Returns an empty array if there are no requests outstanding.
+    def remaining
+      return [] if current.nil?
+
+      @requests[@current..@requests.size]
+    end
+
+    # Moves to the next request, if there is one
+    def next
+      return if @current >= @requests.size
+
+      @current += 1
+      @count -= 1
+    end
+
+    # A frozen clone of all requests held, including those already processed
+    def all
+      @requests.clone.freeze
+    end
+
+    # Clears the list
+    def clear
+      @requests.clear
+      @current = 0
+      @count = 0
+    end
+
+    # Sorts the first `count` elements of the list by the Bugsnag-Sent-At header, if present in all of those elements
+    def sort_by_sent_at!(count)
+      return unless count > 1
+
+      header = 'Bugsnag-Sent-At'
+      sub_list = @requests[@current...@current + count]
+
+      return if sub_list.any? { |r| r[:request][header].nil? }
+
+      # Sort sublist by Bugsnag-Sent-At and overwrite in the main list
+      sub_list.sort_by! { |r| DateTime.parse(r[:request][header]) }
+      sub_list.each_with_index { |r, i| @requests[@current + i] = r }
+    end
+  end
+end