jay_api 27.1.0

data/lib/jay_api/mergeables/merge_selector.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'merge_selector/configuration'
+
+module JayAPI
+  # This class declaration serves as an extension of the already
+  # defined JayAPI::Configuration class.
+  class Configuration
+    # @return [JayAPI::Mergeables::MergeSelector::Configuration] A Configuration object
+    #   that contains the merging functionality.
+    def with_merge_selector
+      JayAPI::Mergeables::MergeSelector::Configuration.from_hash(deep_to_h)
+    end
+  end
+end

data/lib/jay_api/prior_version_fetcher_base.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'elasticsearch/index'
+require_relative 'elasticsearch/query_results'
+require_relative 'elasticsearch/query_builder'
+
+module JayAPI
+  # Fetches the previous software version depending on the given version.
+  class PriorVersionFetcherBase
+    attr_reader :client
+
+    # @param [JayAPI::Elasticsearch::Client] client The +Client+ object to use
+    #   when connecting to Elasticsearch to execute queries.
+    # @param [String] index_name The index of the build properties in Jay
+    def initialize(client:, index_name:)
+      @client = client
+      @index_name = index_name
+    end
+
+    # Calculates the prior software version given the current version if
+    # it exists.
+    # @param [String] current_version The version for which to find a prior
+    #   version.
+    # @return [String, nil] the previous software version or nil if none is
+    #   existent.
+    def prior_version(current_version:)
+      versions = []
+      results = index_obj.search(query)
+
+      results.all do |document|
+        # Since the version is inside an array we have to call first
+        versions << document['fields']['build_properties.version_code.keyword'].first
+      end
+
+      # This function must be injected by the project-specific fetcher
+      compute_last_version(current_version: current_version, existent_versions: versions)
+    end
+
+    private
+
+    attr_reader :cluster_url, :port, :index_name
+
+    # Computes the last version using a predefined logic.
+    # This function should be injected from the inheriting class, calling from
+    # the base class will raise an error.
+    # @param [String] current_version The current version for which the prior
+    #   version should be computed.
+    # @param [Array<Sting>] existent_versions An array containing versions which
+    #   exist on JAY.
+    # @raise [NotImplementedError] if called from the base class or the subclass
+    #   has not overridden this method.
+    def compute_last_version(current_version:, existent_versions:)
+      raise NotImplementedError, "Please implement the method #{__method__} in #{self.class}!"
+    end
+
+    # @return [JayAPI::Elasticsearch::Index]
+    def index_obj
+      @index_obj ||= JayAPI::Elasticsearch::Index.new(client: client, index_name: index_name)
+    end
+
+    # @return [Hash] returns the query hash
+    def query
+      @query ||= JayAPI::Elasticsearch::QueryBuilder.new.collapse('build_properties.version_code.keyword').to_query
+    end
+  end
+end

data/lib/jay_api/properties_fetcher.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'jay_api/errors/configuration_error'
+require 'jay_api/elasticsearch/query_builder'
+
+require_relative 'elasticsearch/time'
+
+module JayAPI
+  # Fetches build properties from the provided information. ATTENTION: There's
+  # a maximum number of data hashes that are returned (see MAX_SIZE).
+  class PropertiesFetcher
+    include JayAPI::Elasticsearch::Time
+
+    MAX_SIZE = 100
+
+    # Name of the field used when querying the index for data using the name of
+    # the build job.
+    BUILD_NAME_FIELD = 'build_properties.build_name.keyword'
+    BUILD_NUMBER_FIELD = 'build_properties.build_number'
+
+    # Name of the field used when querying the index for data using the version
+    # of the software.
+    VERSION_CODE_FIELD = 'build_properties.version_code.keyword'
+    BUILD_RELEASE_FIELD = 'build_properties.build_release'
+
+    # Name of the field used when querying the index for data using the SUT Revision.
+    SUT_REVISION_FIELD = 'sut_revision.keyword'
+    TIMESTAMP_FIELD = 'timestamp'
+
+    attr_reader :index
+
+    # Initializes a PropertiesFetcher object
+    # @param [JsyAPI::Elasticsearch::Index] index The Elasticsearch index to use
+    #   to fetch build properties data.
+    def initialize(index:)
+      @index = index
+    end
+
+    # Constraints the results to those properties belonging to the given
+    # SUT Revision.
+    # @param [String] sut_revision For example: '23-08-02/master'.
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    def by_sut_revision(sut_revision)
+      query_builder.query.bool.must.match_phrase(field: SUT_REVISION_FIELD, phrase: sut_revision)
+      self
+    end
+
+    # Constraints the results to those properties belonging to the given build
+    # job
+    # @param [String] build_job The name of the build job, for example:
+    #   'Release-XYZ01-Master'.
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    def by_build_job(build_job)
+      query_builder.query.bool.must.match_phrase(field: BUILD_NAME_FIELD, phrase: build_job)
+      self
+    end
+
+    # Constraints the results to those properties belonging to the given build
+    # number
+    # @param [String, Integer] build_number The build number, for example 432
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    def by_build_number(build_number)
+      query_builder.query.bool.must.query_string(fields: BUILD_NUMBER_FIELD, query: build_number)
+      self
+    end
+
+    # Constraints the results to those properties for which the software version
+    # matches the given one.
+    # @param [String] software_version The software version, for example 'D310'.
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    def by_software_version(software_version)
+      query_builder.query.bool.must.match_phrase(field: VERSION_CODE_FIELD, phrase: software_version)
+      self
+    end
+
+    # Constraint the results to properties that belong or don't belong to
+    # (depending on the +release_tag+ parameter) a release build.
+    # @param [Boolean] release_tag True If build properties should come from a
+    #   release, false if they SHOULD NOT.
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    def by_release_tag(release_tag)
+      query_builder.query.bool.must.query_string(fields: BUILD_RELEASE_FIELD, query: release_tag)
+      self
+    end
+
+    # Constraints the results to properties that were pushed after the given
+    # +timestamp+.
+    # @param [Time, String] timestamp A timestamp to filter the build properties
+    #   with. If a +String+ is given it is assumed to be in the right format for
+    #   Elasticsearch. No conversion / checking will be performed over it.
+    # @return [JayAPI::PropertiesFetcher] itself, so that other methods can be
+    #   chained.
+    def after(timestamp)
+      # noinspection RubyMismatchedParameterType (checked by the if modifier)
+      timestamp = format_time(timestamp) if timestamp.is_a?(Time)
+      query_builder.query.bool.must.query_string(fields: TIMESTAMP_FIELD, query: "> \"#{timestamp}\"")
+      self
+    end
+
+    # Constraints the results to properties that were pushed before the given
+    # +timestamp+.
+    # @param [Time, String] timestamp A timestamp to filter the build properties
+    #   with. If a +String+ is given it is assumed to be in the right format for
+    #   Elasticsearch. No conversion / checking will be performed over it.
+    # @return [JayAPI::PropertiesFetcher] itself, so that other methods can be
+    #   chained.
+    def before(timestamp)
+      # noinspection RubyMismatchedParameterType (checked by the if modifier)
+      timestamp = format_time(timestamp) if timestamp.is_a?(Time)
+      query_builder.query.bool.must.query_string(fields: TIMESTAMP_FIELD, query: "< \"#{timestamp}\"")
+      self
+    end
+
+    # This method is here only for readability. It is meant to act as a
+    # conjunction between two method calls.
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    # @example
+    #   properties_fetcher.by_build_job('Release-XYZ01-Master').and.by_build_number(106)
+    def and
+      self
+    end
+
+    # @return [Hash, nil] The last set of properties (ordered chronologically)
+    #   or +nil+ if no properties are found.
+    def last
+      sort_records('desc').size(1)
+      fetch_properties.last
+    end
+
+    # @return [Hash, nil] The first set of properties (ordered chronologically)
+    #   or +nil+ if no properties are found
+    def first
+      sort_records('asc').size(1)
+      fetch_properties.first
+    end
+
+    # Limits the amount of records returned to the given number.
+    # @param [Integer] size The number of records to return. If this number is
+    #   greater than +MAX_SIZE+ then +MAX_SIZE+ will be used instead.
+    # @return [JayAPI::PropertiesFetcher] Itself, so that other methods can be
+    #   chained.
+    def limit(size)
+      size = [size, MAX_SIZE].min
+      # noinspection RubyMismatchedParameterType (The array will never be empty)
+      query_builder.size(size)
+      self
+    end
+
+    alias size limit
+
+    # Allows the caller to retrieve or iterate over the set of Build Properties
+    # entries. The method can be called with or without a block. If a block is
+    # given then each of the Build Properties entries will be yielded to the
+    # block, if no block is given then an +Enumerator+ is returned.
+    #
+    # @yield [Hash] One of the Build Properties entries.
+    # @return [Enumerator] If no block is given an +Enumerator+ object for all
+    #   the property sets that were found is returned (might be empty). With a
+    #   block the return value is undefined.
+    def all(&block)
+      fetch_properties.all(&block)
+    end
+
+    private
+
+    # Fetches the properties given the provided query hash.
+    # @return [QueryResults] The fetched data as a QueryResults object.
+    def fetch_properties
+      properties = index.search(query_builder.to_query)
+      @query_builder = nil
+      properties
+    end
+
+    # @return [JayAPI::Elasticsearch::QueryBuilder] The current QueryBuilder
+    #   object. The QueryBuilder is only reset when records are fetched so that
+    #   multiple conditions can be put together into it before the query is
+    #   actually carried out.
+    def query_builder
+      @query_builder ||= JayAPI::Elasticsearch::QueryBuilder.new
+    end
+
+    # Adds a sort clause to the +QueryComposer+ object to sort the records
+    # chronologically.
+    # @param [String] direction The direction of the sorting, either +'asc'+ or
+    #   +'desc'+
+    def sort_records(direction)
+      query_builder.sort('timestamp' => direction)
+    end
+  end
+end

data/lib/jay_api/rspec/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative '../configuration'
+require_relative '../errors/configuration_error'
+
+module JayAPI
+  # A module that contains the classes and method needed to interact with RSpec
+  # data (test cases, test results, etc).
+  module RSpec
+    # @return [JayAPI::Configuration] The current configuration for JayAPI::RSpec
+    # @raise [JayAPI::Errors::ConfigurationError] If the module hasn't been
+    #   configured yet.
+    def self.configuration
+      unless @configuration
+        raise JayAPI::Errors::ConfigurationError,
+              'No configuration has been set for the JayAPI::RSpec module. ' \
+              'Please call JayAPI::RSpec.configure to load/create configuration.'
+      end
+
+      @configuration
+    end
+
+    # Called to configure the JayAPI::RSpec module.
+    # @yield [Class] Yields +JayAPI::Configuration+ (the class itself), on it
+    #   the yielded block can call either, +new+, +from_string+ or +from_file+
+    #   to create the configuration.
+    # @yieldreturn [JayAPI::Configuration] The block should return an instance
+    #   of the +JayAPI::Configuration+ class with the configuration for the
+    #   module.
+    # @raise [JayAPI::Errors::ConfigurationError] If the block returns anything
+    #   but an instance of +JayAPI::Configuration+ or one of its subclasses.
+    def self.configure
+      configuration = yield JayAPI::Configuration
+
+      return unless configuration
+
+      unless configuration.is_a?(JayAPI::Configuration)
+        raise JayAPI::Errors::ConfigurationError,
+              'Expected a JayAPI::Configuration or a subclass. ' \
+              "Got a #{configuration.class} instead."
+      end
+
+      @configuration = configuration
+    end
+  end
+end

data/lib/jay_api/rspec/git.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../git/repository'
+
+module JayAPI
+  module RSpec
+    # Git-related methods for the +TestDataCollector+
+    module Git
+      private
+
+      # @return [JayAPI::Git::Repository] An instance of the +Repository+ class
+      #   set to target the Git repository in the current working directory.
+      def git_repository
+        @git_repository ||= JayAPI::Git::Repository.new(url: nil, clone_path: Dir.pwd)
+      end
+
+      # @return [String] The SHA1 of the current revision for the repository
+      #   from which RSpec is running. If JayAPI's Git library cannot obtain it
+      #   then an attempt is made to get it directly from Git's CLI.
+      def fetch_git_revision
+        git_repository.log(count: 1).first.sha
+      rescue ::Git::GitExecuteError
+        # It wasn't possible to obtain the SHA1 of the repository via the Git
+        # Library. it may still be possible to get it via Git's CLI.
+        `git rev-parse HEAD`.chomp
+      end
+
+      # @return [String] The SHA1 of current repository's revision.
+      # @see #fetch_git_revision
+      def git_revision
+        @git_revision ||= fetch_git_revision
+      end
+
+      # Attempts to get the URL of the first remote associated with the Git
+      # repository in the current working directory.
+      # @return [String] The URL of the remote, or an empty string if the
+      #   attempt fails.
+      def remote_from_command
+        `git remote get-url $(git remote show | head -n 1)`.chomp
+      end
+
+      # @return [String] The URL of the first remote associated with the
+      #   repository from which
+      def fetch_git_remote
+        git_repository.remote_url || remote_from_command
+      rescue ::Git::GitExecuteError
+        # It wasn't possible to obtain the repository's remote URL via the Git
+        # Library. it may still be possible to get it via Git's CLI.
+        remote_from_command
+      end
+
+      # @return [String] The URL of the first remote associated with the current
+      #   repository.
+      # @see #fetch_git_remote
+      def git_remote
+        @git_remote ||= fetch_git_remote
+      end
+    end
+  end
+end

data/lib/jay_api/rspec/test_data_collector.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'rspec'
+require 'rspec/core/formatters'
+require 'rspec/core/configuration'
+
+require_relative '../elasticsearch/client_factory'
+require_relative '../elasticsearch/index'
+require_relative '../elasticsearch/time'
+require_relative '../id_builder'
+require_relative 'configuration'
+require_relative 'git'
+
+module JayAPI
+  module RSpec
+    # Collects RSpec Test Data and pushes it to Jay's Elasticsearch backend.
+    class TestDataCollector
+      include JayAPI::Elasticsearch::Time
+      include JayAPI::RSpec::Git
+
+      DEFAULT_BATCH_SIZE = 100
+
+      # Meta-dara keys that can be used to annotate requirements in tests.
+      REQUIREMENTS_KEYS = %i[requirements refs].freeze
+
+      ::RSpec::Core::Formatters.register self, :start, :close, :example_finished
+
+      # Executed by RSpec during initialization.
+      # Sets the +@push_enabled+ instance variable according to configuration.
+      def initialize(_output)
+        @push_enabled = configuration.push_enabled # When the push is disabled the class behaviour is inhibited.
+      end
+
+      # Called by RSpec at the beginning of the test run. If the push is enabled
+      # the method initializes the Elasticsearch::Index instance. This is done
+      # so that, if it cannot be initialized the tests will fail right away and
+      # not after execution.
+      def start(_notification)
+        return unless push_enabled
+
+        elasticsearch_index
+      end
+
+      # Called by RSpec when an example is finished. The method extracts all the
+      # information from the given notification and creates a data +Hash+ to
+      # push to Elasticsearch.
+      # @param [RSpec::Core::Notifications::ExampleNotification] notification
+      #   The +Notification+ object passed by RSpec.
+      def example_finished(notification)
+        return unless push_enabled
+
+        example = notification.example
+        identifier = example.full_description
+        ex_result = example.execution_result
+        metadata = example.metadata
+
+        data = {
+          test_env: {
+            build_number: ENV['BUILD_NUMBER'],
+            build_job_name: ENV['JOB_NAME'],
+            repository: git_remote.presence,
+            revision: git_revision.presence,
+            hostname: hostname
+          },
+          test_case: {
+            name: identifier,
+            started_at: format_time(ex_result.started_at),
+            finished_at: format_time(ex_result.finished_at),
+            runtime: ex_result.run_time,
+            id_long: identifier,
+            id: build_short_id(identifier),
+            location: metadata[:location],
+            requirements: requirements_from(metadata),
+            expectation: example.description,
+            result: translate_result(ex_result.status),
+            exception: ex_result.exception&.message&.strip
+          }
+        }
+
+        elasticsearch_index.push(data)
+      end
+
+      # Executed by RSpec at the end of the test run. If the push is enabled,
+      # any test cases still being held in the Elasticsearch buffer are flushed.
+      def close(_notification)
+        return unless push_enabled
+
+        elasticsearch_index.flush
+      end
+
+      private
+
+      attr_reader :push_enabled
+
+      # @return [Hash] The configuration set for Elasticsearch as a hash. If no
+      #   value has been set for the batch size a reasonable default is set.
+      # @raise [JayAPI::Errors::ConfigurationError] If no configuration for
+      #   Elasticsearch has been provided.
+      def elasticsearch_config
+        @elasticsearch_config ||= configuration.elasticsearch.tap do |config|
+          unless config
+            raise JayAPI::Errors::ConfigurationError,
+                  'No Elasticsearch configuration provided for the JayAPI::RSpec module.'
+          end
+        end.to_h
+      end
+
+      # @return [JayAPI::Elasticsearch::Client] The +Elasticsearch::Client+
+      #   object that the importer uses to initialize the +Elasticsearch::Index+
+      #   class.
+      def client
+        @client ||= JayAPI::Elasticsearch::ClientFactory.new(**elasticsearch_config).create
+      end
+
+      # @return [Hash] A Hash with the required parameters for the
+      #   +Elasticsearch::Index+ class
+      def index_params
+        @index_params ||= {
+          index_name: elasticsearch_config.delete(:index_name),
+          batch_size: elasticsearch_config.delete(:batch_size) || DEFAULT_BATCH_SIZE,
+          client: client
+        }
+      end
+
+      # @return [JayAPI::Elasticsearch::Index] An +Elasticsearch::Index+
+      #   instance that can be used to push data or search for it.
+      # @raise [ArgumentError] If any of the needed parameters to initialize the
+      #   Elasticsearch Index is missing.
+      def elasticsearch_index
+        @elasticsearch_index ||= JayAPI::Elasticsearch::Index.new(**index_params)
+      end
+
+      # @return [JayAPI::Configuration] The configuration for the JayAPI::RSpec
+      #   module
+      # @raise [JayAPI::Errors::ConfigurationError] If the module hasn't been
+      #   configured yet.
+      def configuration
+        @configuration ||= JayAPI::RSpec.configuration
+      end
+
+      # Builds a short identifier for the Test Case from its long identifier.
+      # @param [String] long_id The Long Identifier of the Test Case
+      # @return [String] The short identifier for the Test Case.
+      def build_short_id(long_id)
+        JayAPI::IDBuilder.new(test_case_id: long_id, project: project).short_id
+      end
+
+      # @return [String] The name of the configured project.
+      def project
+        @project ||= configuration.project
+      end
+
+      # Translates the given test result
+      # @param [Symbol] result The test result (provided by RSpec)
+      # @return [String] The translated result
+      def translate_result(result)
+        case result
+        when :passed then 'pass'
+        when :failed then 'fail'
+        when :pending then 'skip'
+        else 'error'
+        end
+      end
+
+      # @return [String] The name of the computer running the tests
+      def hostname
+        @hostname ||= `hostname`.chomp
+      end
+
+      # Extracts the requirements from the given meta-data. The methods checks
+      # the given meta-data hash and creates an array with all the requirements
+      # found in either of the keys which can contain them.
+      #
+      # If more than one key contains requirements they are put together into a
+      # single array. If none of the keys have requirements +nil+ is returned.
+      #
+      # @param [Hash] metadata The meta-data Hash (normally comes from RSpec).
+      # @return [Array<Object>, nil] An array with all the requirements found
+      #   in the given meta-data Hash or +nil+ if none was found.
+      def requirements_from(metadata)
+        REQUIREMENTS_KEYS.each_with_object([]) do |key, array|
+          array.concat(Array(metadata[key]))
+        end.presence
+      end
+    end
+  end
+end

data/lib/jay_api/rspec.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/git'
+require_relative 'rspec/test_data_collector'
+
+module JayAPI
+  # Namespace for RSpec related classes and modules.
+  module RSpec; end
+end

data/lib/jay_api/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JayAPI
+  # JayAPI gem's semantic version
+  VERSION = '27.1.0'
+end

data/lib/jay_api.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'jay_api/version'
+
+require_relative 'jay_api/rspec'
+
+# Top-level namespace for the Gem
+module JayAPI
+end