dragnet 5.2.1

data/lib/dragnet/exporter.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'errors/unable_to_write_report_error'
+require_relative 'errors/unknown_export_format_error'
+require_relative 'exporters/html_exporter'
+require_relative 'exporters/json_exporter'
+
+module Dragnet
+  # The base exporter class, receives an array of test records, an array of
+  # errors and an array of file names and exports the results to the given
+  # files. (For each file the format is deduced from its file name).
+  class Exporter
+    KNOWN_FORMATS = {
+      'HTML' => { extensions: %w[.html .htm], exporter: Dragnet::Exporters::HTMLExporter },
+      'JSON' => { extensions: %w[.json], exporter: Dragnet::Exporters::JSONExporter }
+    }.freeze
+
+    attr_reader :test_records, :errors, :repository, :targets, :logger
+
+    # Creates a new instance of the class.
+    # @param [Array<Dragnet::TestRecord>] test_records The array of MTRs that
+    #   should be included in the reports.
+    # @param [Array<Hash>] errors An array of Hashes with the data of the MTR
+    #   files that did not pass the validation process.
+    # @param [Dragnet::Repository, Dragnet::MultiRepository] repository The
+    #   repository where the MTR files and the source code are stored.
+    # @param [Array<String>] targets The array of target files. For each of them
+    #   the format of the export will be deduced from the file's extension.
+    # @param [#info, #debug] logger A logger object to use for output.
+    def initialize(test_records:, errors:, repository:, targets:, logger:)
+      @test_records = test_records
+      @errors = errors
+      @repository = repository
+      @targets = targets
+      @logger = logger
+    end
+
+    # Starts the export process.
+    # @raise [Dragnet::Errors::UnableToWriteReportError] If one of the target
+    #   files cannot be created, opened, or if the output cannot be written to
+    #   it.
+    def export
+      logger.info 'Starting export process...'
+      log_target_files
+
+      formats.each do |format, targets|
+        exporter = KNOWN_FORMATS.dig(format, :exporter).new(
+          test_records: test_records, errors: errors, repository: repository, logger: logger
+        )
+
+        text = exporter.export
+        write_output(text, format, targets)
+      end
+    end
+
+    private
+
+    # Writes the given text output with the given format to the given targets.
+    # @param [String] text The text output to write.
+    # @param [String] format The format of the target file.
+    # @param [Array<String>] targets The paths of the target files the output
+    #   should be written to.
+    # @raise [Dragnet::Errors::UnableToWriteReportError] If one of the target
+    #   files cannot be created, opened, or if the output cannot be written to
+    #   it.
+    def write_output(text, format, targets)
+      targets.each do |target|
+        logger.info "Writing #{format} output to #{target}..."
+
+        begin
+          start = Time.now
+          bytes = File.write(target, text)
+          elapsed = Time.now - start
+
+          logger.debug("Ok (#{bytes} bytes written in #{elapsed} seconds)")
+        rescue SystemCallError => e
+          raise Dragnet::Errors::UnableToWriteReportError,
+                "Unable to write report output to #{target}: #{e.message}"
+        end
+      end
+    end
+
+    # Writes a log entry with the files that will be written as a result of the
+    # export process (each with its corresponding format).
+    def log_target_files
+      files_with_formats = formats.flat_map do |format, targets|
+        targets.map { |target| "\t * #{target} as #{format}" }
+      end
+
+      logger.debug "Target files are:\n#{files_with_formats.join("\n")}"
+    end
+
+    # @return [Hash] A hash whose keys are known formats and whose values are
+    #   arrays of target files.
+    def formats
+      @formats ||= deduce_formats
+    end
+
+    # Deduces the format of each target file (given its extension) and relates
+    # them to their corresponding formats.
+    # @return [Hash] A hash whose keys are known formats and whose values are
+    #   arrays of target files.
+    def deduce_formats
+      formats = {}
+
+      targets.each do |target|
+        extension = File.extname(target).downcase
+        format, = KNOWN_FORMATS.find { |_name, config| config[:extensions].include?(extension) }
+        unknown_format_error(extension) unless format
+
+        formats[format] ||= []
+        formats[format] << target
+      end
+
+      formats
+    end
+
+    # Raises a +Dragnet::Errors::UnknownExportFormatError+ with the proper error
+    # message.
+    # @param [String] extension The extension of the given target file.
+    # @raise [Dragnet::Errors::UnknownExportFormatError] is always raised.
+    def unknown_format_error(extension)
+      allowed_extensions = KNOWN_FORMATS.flat_map { |_format, config| config[:extensions] }
+
+      raise Dragnet::Errors::UnknownExportFormatError,
+            "Unknown export format: '#{extension}'. Valid export formats are: "\
+            "#{allowed_extensions.join(', ')}"
+    end
+  end
+end

data/lib/dragnet/exporters/exporter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Dragnet
+  module Exporters
+    # Base class for all exporter classes.
+    class Exporter
+      attr_reader :test_records, :errors, :repository, :logger
+
+      # @param [Array<Hash>] test_records The array of test records.
+      # @param [Array<Hash>] errors The array of errors.
+      # @param [Dragnet::Repository, Dragnet::MultiRepository] repository The
+      #   repository where the MTR files and the source code are stored.
+      # @param [#info] logger A logger object to use for output.
+      def initialize(test_records:, errors:, repository:, logger:)
+        @test_records = test_records
+        @errors = errors
+        @repository = repository
+        @logger = logger
+      end
+
+      # @raise [NotImplementedError] Is always raised. Subclasses are expected
+      #   to override this method.
+      def export
+        raise NotImplementedError,
+              "'export' method not implemented for class #{self.class}"
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/html_exporter.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+require_relative '../helpers/repository_helper'
+require_relative 'exporter'
+
+module Dragnet
+  module Exporters
+    # Creates an HTML report from the given Test Records and Errors data.
+    class HTMLExporter < Dragnet::Exporters::Exporter
+      include Dragnet::Helpers::RepositoryHelper
+
+      TEMPLATE = File.join(__dir__, 'templates', 'template.html.erb').freeze
+
+      # Generates the report and returns it as a string.
+      # @return [String] The generated HTML report.
+      def export
+        logger.info "Generating HTML report from template: #{TEMPLATE}..."
+        ERB.new(File.read(TEMPLATE)).result(binding)
+      end
+
+      private
+
+      # Returns the percentage that +num1+ represents with respect to +num2+
+      # @param [Integer, Float] num1 A number.
+      # @param [Integer, Float] num2 A number.
+      # @return [Integer, Float] The percentage that +num1+ represents with
+      #   respect to +num2+ rounded to two decimal places.
+      def percentage(num1, num2)
+        return 0.0 if num1.zero? || num2.zero?
+
+        ((num1.to_f / num2) * 100).round(2)
+      end
+
+      # @param [Dragnet::Repository] repository The repository whose branches
+      #   should be retrieved.
+      # @return [Array<String>] An array with the names of the branches that
+      #   "contain" the current head of the repository (may be empty).
+      def software_branches(repository)
+        # (uniq needed because of remote/local branches)
+        repository.branches_with_head.map(&:name).uniq
+      rescue Git::GitExecuteError => e
+        logger.warn "Failed to read branches information from the repository at #{repository.path}"
+        logger.warn e.message
+        []
+      end
+
+      # Method used to memoize the output of the +group_by_requirement+ method.
+      # @see #group_by_requirement
+      # @return [Hash] A hash whose keys are the requirement IDs and whose
+      #   values are arrays of MTRs
+      def test_records_by_requirement
+        @test_records_by_requirement ||= group_by_requirement
+      end
+
+      # Groups the MTRs by the requirement(s) they are covering, if a MTR covers
+      # more than one requirement it will be added to all of them, if a
+      # requirement is covered by more than one MTR the requirement will end up
+      # with more than one MTR, example:
+      #
+      # {
+      #   'ESR_REQ_9675' => [MTR1],
+      #   'ESR_REQ_1879' => [MTR2, MTR3]
+      #   'ESR_REQ_4714' => [MTR3]
+      # }
+      #
+      # @return [Hash] A hash whose keys are the requirement IDs and whose
+      #   values are arrays of MTRs
+      def group_by_requirement
+        tests_by_requirement = {}
+
+        test_records.each do |test_record|
+          ids = *test_record.id
+          ids.each do |id|
+            tests_by_requirement[id] ||= []
+            tests_by_requirement[id] << test_record
+          end
+        end
+
+        tests_by_requirement
+      end
+
+      # Returns the HTML code needed to render the Review Status of a MTR as a
+      # badge.
+      # @param [Dragnet::TestRecord] test_record The Test Record.
+      # @return [String] The HTML code to display the Test Record's review
+      #   status as a badge.
+      def review_status_badge(test_record)
+        if test_record.review_status
+          color = test_record.reviewed? ? 'green' : 'red'
+          review_status = test_record.review_status.capitalize
+        else
+          color = 'gray'
+          review_status = '(unknown)'
+        end
+
+        badge_html(color, review_status)
+      end
+
+      # Returns the HTML code needed to display the verification result of a MTR
+      # (the color and the text inside the badge are picked in accordance to the
+      # given result).
+      # @param [Dragnet::VerificationResult] verification_result The result of
+      #   the verification for a given +TestRecord+
+      # @return [String] The HTML code needed to display the result as a badge.
+      def verification_result_badge(verification_result)
+        badge_html(
+          verification_result_color(verification_result),
+          verification_result.status.capitalize
+        )
+      end
+
+      # Returns a color that depends on the verification result for a Test
+      # Record. To be used on HTML elements.
+      # @param [Dragnet::VerificationResult] verification_result The
+      #   +VerificationResult+ object.
+      # @return [String] The corresponding color (depends on the +status+ field
+      #   of the +VerificationResult+ object).
+      def verification_result_color(verification_result)
+        case verification_result.status
+        when :passed
+          'green'
+        when :skipped
+          'yellow'
+        else
+          'red'
+        end
+      end
+
+      # Returns the color that should be used for the highlight line on the left
+      # of the card given the result of the MTR's verification.
+      # @param [Dragnet::VerificationResult] verification_result The
+      #   +VerificationResult+ object associated with the +TestRecord+ being
+      #   rendered on the card.
+      def card_color(verification_result)
+        verification_result_color(verification_result)
+      end
+
+      # Returns the HTML string to produce a Badge
+      # @param [String] color The color of the badge.
+      # @param [String] text The text that goes inside the badge.
+      # @return [String] The HTML code to produce a badge with the given color
+      #   and text.
+      def badge_html(color, text)
+        "<span class=\"badge bg-#{color}\">#{text}</span>"
+      end
+
+      # Converts the ID (+String+) or IDs (+Array<String>+) of a +TestRecord+
+      # object into a string that can be safely rendered in the HTML report.
+      # @param [Dragnet::TestRecord] test_record The +TestRecord+ object.
+      # @return [String] A string with the ID or IDs of the +TestRecord+ object.
+      def test_record_id_to_string(test_record)
+        Array(test_record.id).join(', ')
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/id_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+require_relative '../helpers/repository_helper'
+
+module Dragnet
+  module Exporters
+    # Generates unique IDs for the Manual Test Records by hashing some of their
+    # properties into a hexadecimal SHA1.
+    class IDGenerator
+      include Dragnet::Helpers::RepositoryHelper
+
+      attr_reader :repository
+
+      # @param [Dragnet::Repository] repository The repository where the MTR
+      #   files are located. This allows the SHA1 to be calculated with relative
+      #   paths to the MTRs' files.
+      def initialize(repository)
+        @repository = repository
+      end
+
+      # Calculates the ID of the given MTR
+      # @param [Dragnet::TestRecord] test_record The record for which the ID
+      #   should be calculated.
+      # @return [String] The ID for the given +TestRecord+.
+      # :reek:FeatureEnvy (Cannot be done in the TestRecord itself because it needs the Repository)
+      def id_for(test_record)
+        string = "#{relative_to_repo(test_record.source_file)}#{test_record.id}"
+        # noinspection RubyMismatchedReturnType (This is never nil)
+        Digest::SHA1.hexdigest(string)[0...16]
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/json_exporter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'exporter'
+require_relative 'id_generator'
+require_relative 'serializers/test_record_serializer'
+
+module Dragnet
+  module Exporters
+    # Exports the results for the Manual Test Record verification to a JSON
+    # string.
+    class JSONExporter < ::Dragnet::Exporters::Exporter
+      # @return [String] A JSON string containing an array of objects, one for
+      #   each Test Record.
+      def export
+        logger.info 'Exporting data to JSON'
+        test_records.map do |test_record|
+          ::Dragnet::Exporters::Serializers::TestRecordSerializer
+            .new(test_record, repository).serialize
+            .merge(id: id_generator.id_for(test_record))
+        end.to_json
+      end
+
+      private
+
+      # @return [Dragnet::Exporters::IDGenerator] An instance of the IDGenerator
+      #   class that can be used to calculate the ID for the exported MTRs.
+      def id_generator
+        @id_generator ||= ::Dragnet::Exporters::IDGenerator.new(repository)
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/serializers/repo_serializer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+
+module Dragnet
+  module Exporters
+    module Serializers
+      # Serializes a +Repo+ object into a +Hash+
+      class RepoSerializer
+        attr_reader :repo
+
+        # @param [Dragnet::Repo] repo The +Repo+ object to serialize.
+        def initialize(repo)
+          @repo = repo
+        end
+
+        # Serializes the given +Repo+ object.
+        # @return [Hash] A +Hash+ representing the given +Repo+ object.
+        def serialize
+          {
+            path: repo.path,
+            sha1: repo.sha1
+          }.tap do |hash|
+            hash[:files] = serialize_files if repo.files.present?
+          end
+        end
+
+        private
+
+        # Serializes the array of files attached to the +Repo+
+        # @return [Array<String>] The array of file names (without the path to
+        #   the repository).
+        def serialize_files
+          repo.files.map { |file| file.to_s.gsub("#{repo.path}/", '') }
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/serializers/test_record_serializer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+
+require_relative '../../helpers/repository_helper'
+require_relative 'repo_serializer'
+require_relative 'verification_result_serializer'
+
+module Dragnet
+  module Exporters
+    module Serializers
+      # Serializes a +TestRecord+ object into a +Hash+.
+      class TestRecordSerializer
+        include ::Dragnet::Helpers::RepositoryHelper
+
+        attr_reader :test_record, :repository
+
+        # @param [Dragnet::TestRecord] test_record The +TestRecord+ object to
+        #   serialize.
+        # @param [Dragnet::RepositoryBase] repository The +Repository+ object
+        #   associated with the +TestRecord+. Used to render file paths relative
+        #   to the repository instead of as absolute paths.
+        def initialize(test_record, repository)
+          @test_record = test_record
+          @repository = repository
+        end
+
+        # rubocop:disable Metrics/AbcSize (because of the Hash)
+        # rubocop:disable Metrics/CyclomaticComplexity (because of the conditionals)
+        # rubocop:disable Metrics/PerceivedComplexity (because of the conditionals)
+        # rubocop:disable Metrics/MethodLength (because of he Hash)
+
+        # @return [Hash] A +Hash+ representing the given +TestRecord+ object.
+        def serialize
+          {
+            refs: Array(test_record.id),
+            result: test_record.result,
+            review_status: render_review_status,
+            verification_result: serialized_verification_result,
+
+            # TODO: Remove the started_at and finished_at attributes after solving
+            #   https://esrlabs.atlassian.net/browse/JAY-493
+            started_at: serialized_verification_result[:started_at],
+            finished_at: serialized_verification_result[:finished_at]
+          }.tap do |hash|
+            hash[:sha1] = test_record.sha1 if test_record.sha1.present?
+            hash[:owner] = Array(test_record.name).join(', ') if test_record.name.present?
+            hash[:description] = test_record.description if test_record.description.present?
+            hash[:test_method] = Array(test_record.test_method) if test_record.test_method.present?
+
+            if test_record.tc_derivation_method.present?
+              hash[:tc_derivation_method] = Array(test_record.tc_derivation_method)
+            end
+
+            hash[:review_comments] = test_record.review_comments if test_record.review_comments.present?
+            hash[:findings] = test_record.findings if test_record.findings?
+            hash[:files] = serialize_files if test_record.files.present?
+            hash[:repos] = serialize_repos if test_record.repos.present?
+          end
+        end
+
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
+        # rubocop:enable Metrics/MethodLength
+
+        private
+
+        # Renders the +TestRecord+'s review status
+        # @return [String] The review status, either +'not_reviewed'+ or +'reviewed'+
+        def render_review_status
+          "#{test_record.reviewed? ? nil : 'not_'}reviewed"
+        end
+
+        # Serializes the files listed in the given +TestRecord+
+        # @return [Array<String>] An array of strings, one for each listed file.
+        def serialize_files
+          test_record.files.map { |file| relative_to_repo(file).to_s }
+        end
+
+        # Serializes the +Repo+ objects attached to the +TestRecord+
+        # @return [Array<Hash>] An array of +Hash+es representing each of the
+        #   +Repo+ objects associated with the +TestRecord+
+        def serialize_repos
+          test_record.repos.map { |repo| ::Dragnet::Exporters::Serializers::RepoSerializer.new(repo).serialize }
+        end
+
+        # Serializes the +VerificationResult+ object attached to the given
+        # +TestRecord+
+        # @return [Hash] A +Hash+ representation of the +VerificationResult+
+        #   object.
+        def serialized_verification_result
+          @serialized_verification_result ||= ::Dragnet::Exporters::Serializers::VerificationResultSerializer.new(
+            test_record.verification_result
+          ).serialize
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/serializers/verification_result_serializer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Dragnet
+  module Exporters
+    module Serializers
+      # Serializes a +VerificationResult+ object into a +Hash+.
+      class VerificationResultSerializer
+        attr_reader :verification_result
+
+        # Format used to serialize the +VerificationResult+'s date/time attributes.
+        DATE_FORMAT = '%F %T %z'
+
+        # @param [Dragnet::VerificationResult] verification_result The
+        #   +VerificationResult+ object to serialize.
+        def initialize(verification_result)
+          @verification_result = verification_result
+        end
+
+        # @return [Hash] The +Hash+ representation of the given
+        #   +VerificationResult+ object.
+        def serialize
+          {
+            status: verification_result.status,
+            started_at: verification_result.started_at.strftime(DATE_FORMAT),
+            finished_at: verification_result.finished_at.strftime(DATE_FORMAT),
+            runtime: verification_result.runtime
+          }.tap do |hash|
+            hash[:reason] = verification_result.reason if verification_result.reason
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/exporters/serializers.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'serializers/repo_serializer'
+require_relative 'serializers/test_record_serializer'
+require_relative 'serializers/verification_result_serializer'
+
+module Dragnet
+  module Exporters
+    # Namespace for the serializer classes used by the exporters.
+    module Serializers; end
+  end
+end