bugsnag-maze-runner 7.22.1

data/lib/maze/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'appium_lib'
+
+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
+
+    ERROR_CODES = {
+      ::Selenium::WebDriver::Error::UnknownError => {
+        retry: true,
+        error_code: 10
+      },
+      ::Selenium::WebDriver::Error::WebDriverError => {
+        retry: true,
+        error_code: 10
+      },
+      Maze::Error::AppiumElementNotFoundError => {
+        retry: true,
+        error_code: 11
+      },
+      ::Selenium::WebDriver::Error::NoSuchElementError => {
+        retry: true,
+        error_code: 12
+      },
+      ::Selenium::WebDriver::Error::TimeoutError => {
+        retry: true,
+        error_code: 13
+      },
+      ::Selenium::WebDriver::Error::StaleElementReferenceError => {
+        retry: true,
+        error_code: 14
+      },
+    }.freeze
+
+  end
+end

data/lib/maze/generator.rb

@@ -0,0 +1,55 @@
+# A thread-safe generator of values, backed by an Enumerator.
+module Maze
+  class Generator
+    def initialize(enumerator)
+      # A SizedQueue allows a set number of values to always be ready for clients
+      # and will be automatically topped up from the enumerator.
+      @queue = SizedQueue.new(10)
+
+      # The queue filler continually adds to the queue (when there is room), taking
+      # values from the Enumerator.  This ensure the enumerator is always run inside
+      # the same thread
+      @queue_filler = create_queue_filler(enumerator)
+
+      while @queue.empty? && enumerator.size != 0
+        # Wait for the queue to start filling
+      end
+    end
+
+    # @return The next value
+    def next
+      @queue.pop
+    end
+
+    # @return Whether the generator has been closed
+    def closed?
+      @queue.closed?
+    end
+
+    # Cleans up resources used by the generator
+    def close
+      @queue_filler.exit
+      @queue.close
+    end
+
+    private
+
+    # Create a thread that will constantly append to @queue with values from the
+    # given enumerator
+    #
+    # @param enumerator [Enumerator]
+    # @return [Thread]
+    def create_queue_filler(enumerator)
+      # By passing the enumerator as an argument to Thread.new, it creates a copy
+      # local to that thread and therefore we're not sharing an enumerator across
+      # threads
+      Thread.new(enumerator) do |inner|
+        loop do
+          # Add to the queue until it fills up, this will then block until there's
+          # room in the queue again
+          @queue << inner.next
+        end
+      end
+    end
+  end
+end

data/lib/maze/helper.rb

@@ -0,0 +1,122 @@
+# 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['platformName']
+               else
+                 Maze.config.os
+               end
+          os = os&.downcase
+        end
+
+        raise('Unable to determine the current platform') if os.nil?
+
+        os
+      end
+
+      # Logs the given message and exits the program with a failure status
+      def error_exit(message)
+        $logger.error message
+        exit false
+      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,55 @@
+# Contains logic for the Cucumber hooks when in Appium mode
+module Maze
+  module Hooks
+    # Hooks for Appium mode use
+    class AppiumHooks < InternalHooks
+      @client
+
+      def before_all
+        @client = Maze::Client::Appium.start
+      end
+
+      def before(scenario)
+        @client.start_scenario
+      end
+
+      def after(scenario)
+
+        if 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, :bs, :local].include? Maze.config.farm
+          write_device_logs(scenario) if scenario.failed?
+
+          # appium_lib 12 says that reset is deprecated and activate_app/terminate_app should be used
+          # instead.  However, they do not clear out app data, which we need between scenarios.
+          # install_app/remove_app might also be an option to consider.
+          Maze.driver.reset
+        end
+      end
+
+      def after_all
+        @client&.log_run_outro
+      end
+
+      def at_exit
+        @client&.stop_session
+      end
+
+      private
+
+      # Pulls the device logs using Appium and writes them to file in the maze_output folder
+      def write_device_logs(scenario)
+        log_name = case Maze::Helper.get_current_platform
+                   when 'android'
+                     'logcat'
+                   when 'ios'
+                     'syslog'
+                   end
+        logs = Maze.driver.get_log(log_name)
+
+        Maze::MazeOutput.new(scenario).write_device_logs(logs)
+      end
+    end
+  end
+end

data/lib/maze/hooks/browser_hooks.rb

@@ -0,0 +1,15 @@
+# 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
+        @client = Maze::Client::Selenium.start
+      end
+
+      def at_exit
+        @client.stop_session
+      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/error_code_hook.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Maze
+  module Hooks
+    # Registers an exit hook that will process the reason for an early exit and provide a suitable error code.
+    # Error code sets and specific code meanings are as follows:
+    #   1*: An error has occurred within browser or device drivers:
+    #     10: An unknown error has occurred
+    #     11: An expected UI element was missing
+    #     12: A UI element was missing at time of interaction
+    #     13: A command sent to the remote server timed out
+    #     14: An element was present but did not accept interaction
+    #   2*: Errors relating to potential network, test server, or payload issues
+    #     21: Expected payload(s) was not received
+    #     22: A command was not read by the test fixture
+    class ErrorCodeHook
+      class << self
+
+        attr_accessor :exit_code
+        attr_accessor :last_test_error_class
+
+        def register_exit_code_hook
+          return if @registered
+          at_exit do
+            exit_hook
+          end
+          @registered = true
+        end
+
+        private
+
+        def exit_hook
+          override_exit_code = nil
+
+          maze_errors = Maze::Error::ERROR_CODES
+          if maze_errors.include?(last_test_error_class)
+            override_exit_code = maze_errors[last_test_error_class][:error_code]
+          end
+
+          # Check if a specific error code has been registered elsewhere
+          override_exit_code = @exit_code if @exit_code
+
+          # If an override code is specified, use it, otherwise we'll use the native exit code
+          exit(override_exit_code) unless override_exit_code.nil?
+        end
+      end
+    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(_scenario); end
+
+      def after(_scenario); end
+
+      def after_all; end
+
+      def at_exit; end
+    end
+  end
+end

data/lib/maze/http_request.rb

@@ -0,0 +1,21 @@
+require 'delegate'
+
+module Maze
+  class HttpRequest < SimpleDelegator
+    def body
+      @body ||= decode_body
+    end
+
+    private
+
+    def decode_body
+      delegate = __getobj__
+      if %r{^gzip$}.match(delegate['Content-Encoding'])
+        gz_element = Zlib::GzipReader.new(StringIO.new(delegate.body))
+        gz_element.read
+      else
+        delegate.body
+      end
+    end
+  end
+end

data/lib/maze/interactive_cli.rb

@@ -0,0 +1,173 @@
+require 'pty'
+# TODO: Removed pending PLAT-6322
+# require 'boring'
+
+module Maze
+  # Encapsulates a shell session, retaining state and input streams for interactive tests
+  class InteractiveCLI
+    # @!attribute [r] stdout_lines
+    #   @return [Array] An array of output strings received from the terminals STDOUT pipe
+    attr_reader :stdout_lines
+
+    # @!attribute [r] stderr_lines
+    #   @return [Array] An array of error strings received from the terminals STDERR pipe
+    attr_reader :stderr_lines
+
+    # @!attribute [r] pid
+    #   @return [Number, nil] The PID of the running terminal
+    attr_reader :pid
+
+    # @!attribute [r] current_buffer
+    #   @return [String] A string representation of the current output present in the terminal
+    attr_reader :current_buffer
+
+    # Creates an InteractiveCLI instance
+    #
+    # @param shell [String] A path to the shell to run, defaults to `/bin/sh`
+    # @param stop_command [String] The stop command, defaults to `exit`
+    def initialize(shell = '/bin/sh', stop_command = 'exit')
+      @shell = shell
+      @stop_command = stop_command
+      @stdout_lines = []
+      @stderr_lines = []
+      @on_exit_blocks = []
+      @current_buffer = ''
+      # TODO: Removed pending PLAT-6322
+      # @boring = Boring.new
+
+      start_threaded_shell(shell)
+    end
+
+    def start(threaded: true)
+      threaded ? start_threaded_shell(@shell) : start_shell(@shell)
+    end
+
+    # Attempts to stop the shell using the preset command and wait for it to exit
+    #
+    # @return [Boolean] If the shell stopped successfully
+    def stop
+      run_command(@stop_command)
+
+      @in_stream.close
+
+      maybe_thread = @thread.join(15)
+
+      # The thread did not exit!
+      return false if maybe_thread.nil?
+
+      @pid = nil
+      true
+    end
+
+    # @return [Boolean] Whether the shell is currently running
+    def running?
+      !@pid.nil?
+    end
+
+    # Runs the given command if the shell is running
+    #
+    # @param command [String] The command to run
+    #
+    # @return [Boolean] true if the command is executed, false otherwise
+    def run_command(command)
+      return false unless running?
+
+      @in_stream.puts(command)
+
+      true
+    rescue ::Errno::EIO => err
+      $logger.debug(pid) { "EIO error: #{err}" }
+      false
+    end
+
+    def on_exit(&block)
+      @on_exit_blocks << block
+    end
+
+    private
+
+    # Starts a shell on another thread
+    #
+    # @param shell [String] A path to the shell to run
+    def start_threaded_shell(shell)
+      @thread = Thread.new do
+        start_shell(shell)
+      end
+    end
+
+    # Starts a shell
+    #
+    # @param shell [String] A path to the shell to run
+    def start_shell(shell)
+      stderr_reader, stderr_writer = IO.pipe
+
+      PTY.spawn(shell, err: stderr_writer.fileno) do |stdout, stdin, pid|
+        # We don't need to write to stderr so close it ASAP
+        stderr_writer.close
+
+        $logger.debug(pid) { 'PTY spawned!' }
+        @pid = pid
+        @in_stream = stdin
+
+        stdout_thread = Thread.new do
+          stdout.each_char do |char|
+            if char == "\n"
+              line = format_line(@current_buffer)
+
+              $logger.debug("#{pid} STDOUT") { line.dump }
+              @stdout_lines << line
+              @current_buffer.clear
+            else
+              @current_buffer << char
+            end
+          end
+        rescue ::Errno::EIO => err
+          $logger.debug(pid) { "EIO error: #{err}" }
+        end
+
+        stderr_thread = Thread.new do
+          buffer = ''
+
+          stderr_reader.each_char do |char|
+            if char == "\n"
+              line = format_line(buffer)
+
+              $logger.debug("#{pid} STDERR") { line.dump }
+              @stderr_lines << line
+              buffer.clear
+            else
+              buffer << char
+            end
+          end
+        rescue ::Errno::EIO => err
+          $logger.debug(pid) { "EIO error: #{err}" }
+        end
+
+        _, status = Process.wait2(@pid)
+        @pid = nil
+
+        # Stop the thread that's reading from stdout
+        failed = stdout_thread.join(5).nil?
+        raise 'stdout is blocked!' if failed
+
+        # Stop the thread that's reading from stderr
+        failed = stderr_thread.join(5).nil?
+        raise 'stderr is blocked!' if failed
+
+        $logger.debug(pid) { "PTY exit status: #{status.exitstatus}" }
+        @on_exit_blocks.each do |block|
+          block.call(status.exitstatus)
+        end
+      end
+    ensure
+      stderr_reader.close unless stderr_reader.closed?
+      stderr_writer.close unless stderr_writer.closed?
+    end
+
+    def format_line(line)
+      # TODO: Removed pending PLAT-6322
+      # @boring.scrub(line.strip)
+      line.strip
+    end
+  end
+end

data/lib/maze/logger.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'singleton'
+
+# Logger classes
+module Maze
+  # A logger, with level configured according to the environment
+  class Logger < Logger
+    include Singleton
+
+    attr_accessor :datetime_format
+
+    def initialize
+      if ENV['VERBOSE'] || ENV['DEBUG']
+        super(STDOUT, level: Logger::DEBUG)
+      elsif ENV['QUIET']
+        super(STDOUT, level: Logger::ERROR)
+      else
+        super(STDOUT, level: Logger::INFO)
+      end
+
+      @datetime_format = '%H:%M:%S'
+
+      @formatter = proc do |severity, time, _name, message|
+        formatted_time = time.strftime(@datetime_format)
+
+        "\e[2m[#{formatted_time}]\e[0m #{severity.rjust(5)}: #{message}\n"
+      end
+    end
+  end
+
+  $logger = Maze::Logger.instance
+
+  # A collection of logging utilities
+  class LogUtil
+    class << self
+      # Logs Hash-based data, accounting for things like file upload requests that are too big to log meaningfully.
+      #
+      # @param severity [Integer] A constant from Logger::Severity
+      # @param data [Hash] The data to log (currently needs to be a Hash)
+      def log_hash(severity, data)
+        return unless data.is_a? Hash
+
+        # Try to pretty print as JSON, if not too big
+        begin
+          json = JSON.pretty_generate data
+          if json.length < 128 * 1024
+            $logger.add severity, json
+          else
+            log_hash_by_field severity, data
+          end
+        rescue Encoding::UndefinedConversionError
+          log_hash_by_field severity, data
+        end
+      end
+
+      # Logs a hash field by field,
+      #
+      # @param severity [Integer] A Logger::Severity
+      # @param hash [Hash] The Hash
+      def log_hash_by_field(severity, hash)
+        hash.keys.each do |key|
+          value = hash[key].to_s
+          if value.length < 1024
+            $logger.add severity, "  #{key}: #{value}"
+          else
+            $logger.add severity, "  #{key} (length): #{value.length}"
+            $logger.add severity, "  #{key} (start): #{value[0, 1024]}"
+          end
+        end
+      end
+
+      # Produces a clickable link when logged in Buildkite
+      # @param url [String] Link URL
+      # @param text [String] Link text
+      def linkify(url, text)
+        if ENV['BUILDKITE']
+          "\033]1339;url='#{url}';content='#{text}'\a"
+        else
+          "#{text}: #{url}"
+        end
+      end
+    end
+  end
+end