bugsnag-maze-runner 7.22.1

data/lib/maze/configuration.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Maze
+  # MazeRunner configuration
+  class Configuration
+
+    # Set default values
+    def initialize
+      self.receive_no_requests_wait = 30
+      self.receive_requests_wait = 30
+      self.enforce_bugsnag_integrity = true
+      self.captured_invalid_requests = Set[:errors, :sessions, :builds, :uploads, :sourcemaps]
+      @legacy_driver = false
+    end
+
+    #
+    # Server configuration
+    #
+
+    # Mock server bind address
+    attr_accessor :bind_address
+
+    # Mock server port
+    attr_accessor :port
+
+    # Terminating server bind port
+    attr_accessor :null_port
+
+    #
+    # Document server configuration
+    #
+
+    # Document server root
+    attr_accessor :document_server_root
+
+    # Document server bind address
+    attr_accessor :document_server_bind_address
+
+    # Document server port
+    attr_accessor :document_server_port
+
+    #
+    # Common configuration
+    #
+
+    # Time in seconds to wait in the `I should receive no requests` step
+    attr_accessor :receive_no_requests_wait
+
+    # Maximum time in seconds to wait in the `I wait to receive {int} error(s)/session(s)/build(s)` steps
+    attr_accessor :receive_requests_wait
+
+    # Whether presence of the Bugsnag-Integrity header should be enforced
+    attr_accessor :enforce_bugsnag_integrity
+
+    # Whether retries should be allowed
+    attr_accessor :enable_retries
+
+    # Enables bugsnag reporting
+    attr_accessor :enable_bugsnag
+
+    # The server endpoints for which invalid requests should be captured and cause tests to fail
+    attr_accessor :captured_invalid_requests
+
+    # API key to use when repeating requests
+    attr_accessor :repeater_api_key
+
+    # Enables awareness of a public IP address on Buildkite with the Elastic CI Stack for AWS.
+    attr_accessor :aws_public_ip
+
+    #
+    # General appium configuration
+    #
+
+    # Element locator strategy, :id or :accessibility_id
+    attr_accessor :locator
+
+    # Appium capabilities
+    attr_accessor :capabilities
+
+    # Appium capabilities provided via the CL
+    attr_accessor :capabilities_option
+
+    # The app that tests will be run against.  Could be one of:
+    # - a local file path
+    # - a BrowserStack url for a previously uploaded app (bs://...)
+    # - on macOS, the name of an installed or previously executed application
+    attr_accessor :app
+
+    # Device farm to be used, one of:
+    # :bs (BrowserStack)
+    # :local (Using Appium Server with a local device)
+    # :none (Cucumber-driven testing with no devices)
+    attr_accessor :farm
+
+    # Whether the device farm secure tunnel should be started
+    attr_accessor :start_tunnel
+
+    #
+    # Device farm specific configuration
+    #
+
+    # Location of the SmartBear binary (if used)
+    attr_accessor :sb_local
+
+    # Location of the BrowserStackLocal binary (if used)
+    attr_accessor :bs_local
+
+    # Bundle ID of the test application
+    attr_accessor :app_bundle_id
+
+    # Farm username
+    attr_accessor :username
+
+    # Farm access key
+    attr_accessor :access_key
+
+    # Test device type
+    attr_accessor :device
+
+    # A list of devices to attempt to connect to, in order
+    attr_accessor :device_list
+
+    # Test browser type
+    attr_accessor :browser
+
+    # Appium version to use
+    attr_accessor :appium_version
+
+    # URI of the test-management service
+    attr_accessor :tms_uri
+
+    # Access token for the test-management service
+    attr_accessor :tms_token
+
+    # Whether the legacy (JSON-WP) Appium driver should be used
+    def legacy_driver?
+      @legacy_driver
+    end
+
+    def legacy_driver=(value)
+      @legacy_driver = value
+    end
+
+    #
+    # Local testing specific configuration
+    #
+
+    # Apple Team Id
+    attr_accessor :apple_team_id
+
+    # OS
+    attr_accessor :os
+
+    # OS version
+    attr_accessor :os_version
+
+    # Device id for running on local iOS devices
+    attr_accessor :device_id
+
+    # URL of the Appium server
+    attr_accessor :appium_server_url
+
+    # Whether an appium server should be started
+    attr_accessor :start_appium
+
+    # The location of the appium server logfile
+    attr_accessor :appium_logfile
+
+    #
+    # Logging configuration
+    #
+
+    # Write received requests to disk for all scenarios
+    attr_accessor :file_log
+
+    # Console logging of received requests for a test failure
+    attr_accessor :log_requests
+
+    # Always log all received requests to the console at the end of a scenario
+    attr_accessor :always_log
+  end
+end

data/lib/maze/docker.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'runner'
+
+module Maze
+  # Responsible for running docker containers in the local environment
+  class Docker
+    class << self
+      # The default place to look for the docker-compose file
+      COMPOSE_FILENAME = 'features/fixtures/docker-compose.yml'
+
+      # @!attribute [a] last_exit_code Provides access to the exit code of the last run docker command
+      attr_accessor :last_exit_code
+
+      # @!attribute [a] last_command_logs Provides access to the output from the last run docker command
+      attr_accessor :last_command_logs
+
+      # Builds and starts a service, using a command if given.
+      # If running a command, it will be executed as an attached process, otherwise it
+      # will run detached.
+      #
+      # @param service [String] The name of the service to start
+      # @param command [String] Optional. The command to use when running the service
+      # @param interactive [Boolean] Optional. Whether to run interactively
+      def start_service(service, command: nil, interactive: false)
+        if interactive
+          run_docker_compose_command("build #{service}")
+
+          # Run the built service in an interactive session. The service _must_
+          # have an appropriate entrypoint, e.g. '/bin/sh'. We also disable ANSI
+          # escape sequences from docker-compose as they can cause issues with
+          # stderr expectations by 'leaking' into the next line
+          command = get_docker_compose_command("--no-ansi run #{service} #{command}")
+
+          cli = Runner.start_interactive_session(command)
+          cli.on_exit do |status|
+            @last_exit_code = status
+            @last_command_logs = cli.stdout_lines + cli.stderr_lines
+          end
+
+          # The logs and exit code aren't available from the interactive session
+          # at this point (we've just started it!) so we can't provide them here
+          @last_command_logs = []
+          @last_exit_code = nil
+        elsif command
+          # We build the service before running it as there is no --build
+          # option for run.
+          run_docker_compose_command("build #{service}")
+          run_docker_compose_command("run --use-aliases #{service} #{command}")
+        else
+          # TODO: Consider adding a logs command here
+          run_docker_compose_command("up -d --build #{service}")
+        end
+        @services_started = true
+      end
+
+      # Execute a command in an already running docker container. Use {start_service}
+      # to build and run the service before calling this method
+      #
+      # This is equivalent to the Docker Compose 'exec' command:
+      # https://docs.docker.com/engine/reference/commandline/compose_exec/
+      #
+      # @param service [String] The name of the service. This must already be running
+      # @param command [String] The command to run
+      # @param detach [Boolean] Optional. Whether to run detached
+      def exec(service, command, detach: false)
+        flags = detach ? " --detach" : ""
+
+        run_docker_compose_command("exec #{flags} #{service} /bin/sh -c '#{command}'")
+      end
+
+      # Copy a file or directory from a container to the local filesystem
+      #
+      # This is equivalent to the Docker Compose 'cp' command:
+      # https://docs.docker.com/engine/reference/commandline/compose_cp/
+      #
+      # @param service [String] The name of the service to copy from. This must already be running
+      # @param from [String] The path to the file/directory that should be copied
+      # @param to [String] The path to copy the file/directory to
+      def copy_from_container(service, from:, to:)
+        run_docker_compose_command("cp #{service}:#{from} #{to}", success_codes: [0])
+      end
+
+      # Copy a file or directory from the local filesystem to a container
+      #
+      # This is equivalent to the Docker Compose 'cp' command:
+      # https://docs.docker.com/engine/reference/commandline/compose_cp/
+      #
+      # @param service [String] The name of the service to copy to. This must already be running
+      # @param from [String] The path to the file/directory that should be copied
+      # @param to [String] The path to copy the file/directory to
+      def copy_to_container(service, from:, to:)
+        run_docker_compose_command("cp #{from} #{service}:#{to}", success_codes: [0])
+      end
+
+      # Kills a running service
+      #
+      # @param service [String] The name of the service to kill
+      def down_service(service)
+        # We set timeout to 0 so this kills the services rather than stopping them
+        # as its quicker and they are stateless anyway.
+        run_docker_compose_command("down -t 0 #{service}")
+      end
+
+      # Resets any state ready for the next scenario
+      def reset
+        down_all_services
+        @last_exit_code = nil
+        @last_command_logs = nil
+      end
+
+      # Kills all running services
+      def down_all_services
+        # This will fail to remove the network that maze is connected to
+        # as it is still in use, that is ok to ignore so we pass success codes!
+        # We set timeout to 0 so this kills the services rather than stopping them
+        # as its quicker and they are stateless anyway.
+        run_docker_compose_command('down -t 0', success_codes: [0, 256]) if compose_stack_exists? && @services_started
+        @services_started = false
+      end
+
+      def compose_project_name
+        @compose_project_name ||= nil
+      end
+
+      attr_writer :compose_project_name
+
+      private
+
+      def get_docker_compose_command(command)
+        project_name = compose_project_name.nil? ? '' : "-p #{compose_project_name}"
+
+        "docker compose #{project_name} -f #{COMPOSE_FILENAME} #{command}"
+      end
+
+      def run_docker_compose_command(command, success_codes: nil)
+        command = get_docker_compose_command(command)
+
+        @last_command_logs, @last_exit_code = Runner.run_command(command, success_codes: success_codes)
+      end
+
+      def compose_stack_exists?
+        File.exist? COMPOSE_FILENAME
+      end
+    end
+  end
+end

data/lib/maze/document_server.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'webrick'
+
+module Maze
+  # HTTP server for a given document root
+  class DocumentServer
+    class << self
+      # Start the document server.  This is intended to be called only once per test run.
+      # Use manual_start for finer grained control.
+      def start
+        @thread = Thread.new do
+          options = {
+            DocumentRoot: Maze.config.document_server_root,
+            Port: Maze.config.document_server_port,
+            Logger: $logger,
+            AccessLog: []
+          }
+          options[:BindAddress] = Maze.config.document_server_bind_address unless Maze.config.document_server_bind_address.nil?
+          server = WEBrick::HTTPServer.new(options)
+          server.mount '/reflect', Servlets::ReflectiveServlet
+
+          $logger.info "Starting document server for root: #{Maze.config.document_server_root}"
+          server.start
+        end
+      end
+
+      # Starts the document server "manually" (via a Cucumber step as opposed to command line option)
+      def manual_start
+        if !@thread.nil? && @thread.alive?
+          $logger.warn 'Document Server has already been started on the command line, ignoring manual start'
+          return
+        end
+        @manual_start = true
+        start
+      end
+
+      def manual_stop
+        return unless  @manual_start
+
+        @thread.kill
+        @manual_start = false
+      end
+    end
+  end
+end

data/lib/maze/driver/appium.rb

@@ -0,0 +1,198 @@
+require 'appium_lib'
+require 'json'
+require 'open3'
+require 'securerandom'
+require_relative '../logger'
+require_relative '../../maze'
+
+module Maze
+  module Driver
+    # Provide a thin layer of abstraction above @see Appium::Driver
+    class Appium < Appium::Driver
+
+      # @!attribute [rw] app_id
+      #   @return [String] The app_id derived from session_capabilities (appPackage on Android, bundleID on iOS)
+      attr_accessor :app_id
+
+      # @!attribute [r] device_type
+      #   @return [String] The device, from the list of device capabilities, used for this test
+      attr_reader :device_type
+
+      # @!attribute [r] capabilities
+      #   @return [Hash] The capabilities used to launch the BrowserStack instance
+      attr_reader :capabilities
+
+      # 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)
+        # Sets up identifiers for ease of connecting jobs
+        capabilities ||= {}
+
+        @element_locator = locator
+        @capabilities = capabilities
+
+        # Timers
+        @find_element_timer = Maze.timers.add 'Appium - find element'
+        @click_element_timer = Maze.timers.add 'Appium - click element'
+        @clear_element_timer = Maze.timers.add 'Appium - clear element'
+        @send_keys_timer = Maze.timers.add 'Appium - send keys to element'
+
+        super({
+          'caps' => @capabilities,
+          'appium_lib' => {
+            server_url: server_url
+          }
+        }, true)
+      end
+
+      # Starts the Appium driver
+      def start_driver
+        begin
+          $logger.info 'Starting Appium driver...'
+          time = Time.now
+          super
+          $logger.info "Appium driver started in #{(Time.now - time).to_i}s"
+        rescue => error
+          $logger.warn "Appium driver failed to start in #{(Time.now - time).to_i}s"
+          $logger.warn "#{error.class} occurred with message: #{error.message}"
+          raise error
+        end
+      end
+
+      # Checks for an element, waiting until it is present or the method times out
+      #
+      # @param element_id [String] the element to search for
+      # @param timeout [Integer] the maximum time to wait for an element to be present in seconds
+      # @param retry_if_stale [Boolean] enables the method to retry acquiring the element if a StaleObjectException occurs
+      def wait_for_element(element_id, timeout = 15, retry_if_stale = true)
+        wait = Selenium::WebDriver::Wait.new(timeout: timeout)
+        wait.until { find_element(@element_locator, element_id).displayed? }
+      rescue Selenium::WebDriver::Error::TimeoutError
+        false
+      rescue Selenium::WebDriver::Error::StaleElementReferenceError => e
+        if retry_if_stale
+          wait_for_element(element_id, timeout, false)
+        else
+          $logger.warn "StaleElementReferenceError occurred: #{e}"
+          false
+        end
+      else
+        true
+      end
+
+      # A wrapper around find_element adding timer functionality
+      def find_element_timed(element_id)
+        @find_element_timer.time do
+          find_element(@element_locator, element_id)
+        end
+      end
+
+      # Clicks a given element
+      #
+      # @param element_id [String] the element to click
+      def click_element(element_id)
+        element = find_element_timed(element_id)
+        @click_element_timer.time do
+          element.click
+        end
+      end
+
+      # Clicks a given element, ignoring any NoSuchElementError
+      #
+      # @param element_id [String] the element to click
+      # @return [Boolean] True is the element was clicked
+      def click_element_if_present(element_id)
+        element = find_element_timed(element_id)
+        @click_element_timer.time do
+          element.click
+        end
+        true
+      rescue Selenium::WebDriver::Error::NoSuchElementError
+        false
+      end
+
+      # Clears a given element
+      #
+      # @param element_id [String] the element to clear
+      def clear_element(element_id)
+        element = find_element_timed(element_id)
+        @clear_element_timer.time do
+          element.clear
+        end
+      end
+
+      # Gets the application hierarchy XML
+      def page_source
+        @driver.page_source
+      end
+
+      # Unlocks the device
+      def unlock
+        @driver.unlock
+      end
+
+      # Sends keys to a given element
+      #
+      # @param element_id [String] the element to send text to
+      # @param text [String] the text to send
+      def send_keys_to_element(element_id, text)
+        element = find_element_timed(element_id)
+        @send_keys_timer.time do
+          element.send_keys(text)
+        end
+      end
+
+      # Sets the rotation of the device
+      #
+      # @param orientation [Symbol] :portrait or :landscape
+      def set_rotation(orientation)
+        @driver.rotation = orientation
+      end
+
+      def window_size
+        @driver.window_size
+      end
+
+      # Send keys to the device without a specific element
+      #
+      # @param text [String] the text to send
+      def send_keys(text)
+        @driver.send_keys(text)
+      end
+
+      # Sends keys to a given element, clearing it first
+      #
+      # @param element_id [String] the element to clear and send text to
+      # @param text [String] the text to send
+      def clear_and_send_keys_to_element(element_id, text)
+        element = find_element_timed(element_id)
+        @clear_element_timer.time do
+          element.clear
+        end
+
+        @send_keys_timer.time do
+          element.send_keys(text)
+        end
+      end
+
+      # Reset the currently running application after a given timeout
+      #
+      # @param timeout [Number] the amount of time in seconds to wait before resetting
+      def reset_with_timeout(timeout = 0.1)
+        sleep(timeout)
+        reset
+      end
+
+      def device_info
+        driver.execute_script('mobile:deviceInfo')
+      end
+
+      def session_capabilities
+        driver.session_capabilities
+      end
+    end
+  end
+end

data/lib/maze/driver/browser.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+module Maze
+  module Driver
+    # Handles browser automation fundamentals
+    class Browser
+      # @!attribute [r] capabilities
+      #   @return [Hash] The capabilities used to launch the BrowserStack instance
+      attr_reader :capabilities
+
+      def initialize(driver_for, selenium_url=nil, capabilities=nil)
+        capabilities ||= {}
+        @capabilities = capabilities
+        @driver_for = driver_for
+        @selenium_url = selenium_url
+      end
+
+      def find_element(*args)
+        @driver.find_element(*args)
+      end
+
+      def navigate
+        @driver.navigate
+      end
+
+      # Refreshes the page
+      def refresh
+        @driver.refresh
+      end
+
+      # Quits the driver
+      def driver_quit
+        @driver.quit
+      end
+
+      # check if Selenium supports running javascript in the current browser
+      def javascript?
+        @driver.execute_script('return true')
+      rescue Selenium::WebDriver::Error::UnsupportedOperationError
+        false
+      end
+
+      # check if the browser supports local storage, e.g. safari 10 on browserstack
+      # does not have working local storage
+      def local_storage?
+        # Assume we can use local storage if we aren't able to verify by running JavaScript
+        return true unless javascript?
+
+        @driver.execute_script <<-JAVASCRIPT
+      try {
+        window.localStorage.setItem('__localstorage_test__', 1234)
+        window.localStorage.removeItem('__localstorage_test__')
+
+        return true
+      } catch (err) {
+        return false
+      }
+        JAVASCRIPT
+      end
+
+      # Restarts the underlying-driver in the case an unrecoverable error occurs
+      #
+      # @param attempts [Integer] The number of times we should retry a failed attempt (defaults to 6)
+      def restart_driver(attempts=6)
+        # Remove the old driver
+        @driver.quit
+        @driver = nil
+
+        start_driver(attempts)
+      end
+
+      # Attempts to create a new selenium driver a given number of times
+      #
+      # @param attempts [Integer] The number of times we should retry a failed attempt (defaults to 6)
+      def start_driver(attempts=6)
+        timeout = attempts * 10
+        wait = Maze::Wait.new(interval: 10, timeout: timeout)
+        success = wait.until do
+          begin
+            create_driver(@driver_for, @selenium_url)
+          rescue => error
+            $logger.warn "#{error.class} occurred with message: #{error.message}"
+          end
+          @driver
+        end
+
+        unless success
+          $logger.error "Selenium driver failed to start after #{attempts} attempts in #{timeout} seconds"
+          raise RuntimeError.new("Selenium driver failed to start in #{timeout} seconds")
+        end
+      end
+
+      private
+
+      # Creates and starts the selenium driver
+      def create_driver(driver_for, selenium_url=nil)
+        begin
+          $logger.info "Starting Selenium driver"
+          time = Time.now
+          if driver_for == :remote
+            if Maze.config.legacy_driver?
+              driver = ::Selenium::WebDriver.for :remote,
+                                                 url: selenium_url,
+                                                 desired_capabilities: @capabilities
+            else
+              driver = ::Selenium::WebDriver.for :remote,
+                                                 url: selenium_url,
+                                                 capabilities: @capabilities
+            end
+          else
+            driver = ::Selenium::WebDriver.for driver_for
+          end
+          $logger.info "Selenium driver started in #{(Time.now - time).to_i}s"
+          @driver = driver
+        rescue => error
+          $logger.warn "Selenium driver failed to start in #{(Time.now - time).to_i}s"
+          raise error
+        end
+      end
+    end
+  end
+end