dragnet 5.2.1

data/lib/dragnet/validators/fields/repos_validator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../../repo'
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates that the +repos+ attribute in an MTR is valid. This means:
+      # * It is either a +Hash+ or an +Array+ of +Hash+es.
+      # * The attributes inside each of the +Hash+es are also valid.
+      class ReposValidator < Dragnet::Validators::Fields::FieldValidator
+        # Validates the MTR's +repos+ field.
+        # @param [String] key The name of the key (usually +'repos'+)
+        # @param [Object] value The value associated to the attribute.
+        # @return [Array<Dragnet::Repo>, nil] If +value+ is a valid +Hash+ or a
+        #   valid +Array+ of +Hash+es an +Array+ of +Dragnet::Repo+ objects is
+        #   returned. If +value+ is +nil+, +nil+ is returned.
+        # @raise [Dragnet::Errors::ValidationError] If +value+ is not a +Hash+
+        #   or an +Array+ of +Hash+es or the attributes inside the +Hash+es are
+        #   invalid.
+        # @see Dragnet::Repo#validate
+        def validate(key, value)
+          return unless value
+
+          validate_type(key, value, Hash, Array)
+
+          if value.is_a?(Array)
+            return if value.empty?
+
+            validate_array_types(key, value, Hash)
+          else
+            # This is needed because trying to apply the splat operator over a
+            # Hash will result in an Array of Arrays (one for each of the Hash's
+            # key pairs).
+            value = [value]
+          end
+
+          create_repos(value)
+        end
+
+        private
+
+        # @param [Array<Hash>] hashes The array of +Hash+es from which the Repo
+        #   objects shall be created.
+        # @return [Array<Dragnet::Repo>] The array of +Dragnet::Repo+ objects
+        #   that result from using each of the given +Hash+es as parameters for
+        #   the constructor.
+        # @raise [Dragnet::Errors::ValidationError] If the attributes inside the
+        #   +Hash+es are invalid.
+        # @see Dragnet::Repo#validate
+        def create_repos(hashes)
+          hashes.map do |hash|
+            repo = Dragnet::Repo.new(**hash)
+            repo.validate
+            repo
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/result_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates the result field of an MTR Record
+      class ResultValidator < Dragnet::Validators::Fields::FieldValidator
+        VALID_RESULTS = %w[passed failed].freeze
+
+        # Validates the MTR's result
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @return [String] The downcase version of the result field.
+        # @raise [Dragnet::Errors::ValidationError] If the result is missing, if
+        #   it isn't a String or is not one of the allowed values for the field.
+        def validate(key, value)
+          validate_presence(key, value)
+          validate_type(key, value, String)
+
+          value = value.downcase
+          return value if VALID_RESULTS.include?(value)
+
+          validation_error(
+            "Invalid value for key result: '#{value}'. "\
+            "Valid values are #{VALID_RESULTS.join(', ')}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/sha1_validator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates the SHA1 field of a Manual Test Record
+      class SHA1Validator < Dragnet::Validators::Fields::FieldValidator
+        SHA1_MIN_LENGTH = 7
+        SHA1_MAX_LENGTH = 40
+        SHA1_REGEX = /\A[0-9a-f]+\Z/.freeze
+
+        # Validates the SHA1 of the MTR
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @raise [Dragnet::Errors::ValidationError] If the SHA1 is missing, is not
+        #   and string, is too short or too long or is not a valid hexadecimal
+        #   string.
+        def validate(key, value)
+          validate_presence(key, value)
+          validate_type(key, value, String)
+
+          length = value.length
+          unless length >= SHA1_MIN_LENGTH && length <= SHA1_MAX_LENGTH
+            validation_error(
+              "Invalid value for key #{key}: '#{value}'. Expected a string between "\
+              "#{SHA1_MIN_LENGTH} and #{SHA1_MAX_LENGTH} characters"
+            )
+          end
+
+          return if value.match(SHA1_REGEX)
+
+          validation_error(
+            "Invalid value for key #{key}: '#{value}'. "\
+            "Doesn't seem to be a valid hexadecimal string"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'fields/description_validator'
+require_relative 'fields/files_validator'
+require_relative 'fields/id_validator'
+require_relative 'fields/meta_data_field_validator'
+require_relative 'fields/path_validator'
+require_relative 'fields/repos_validator'
+require_relative 'fields/result_validator'
+require_relative 'fields/sha1_validator'
+
+module Dragnet
+  module Validators
+    # Namespace module for entity fields validators.
+    module Fields; end
+  end
+end

data/lib/dragnet/validators/files_validator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative '../errors/file_not_found_error'
+require_relative 'validator'
+
+module Dragnet
+  module Validators
+    # Validates the +files+ key in the given Manual Test Record object.
+    # Validates:
+    #   - That the listed file(s) glob pattern(s) match at least one file in the
+    #     repository.
+    class FilesValidator < Dragnet::Validators::Validator
+      attr_reader :test_record, :path
+
+      # Creates a new instance of the class.
+      # @param [Dragnet::TestRecord] test_record The +TestRecord+ object whose
+      #   files should be validated.
+      # @param [Pathname] path The path to the repository where the files are
+      #   supposed to be located.
+      def initialize(test_record, path)
+        @test_record = test_record
+        @files = test_record.files
+        @path = path
+      end
+
+      # Validates the +files+ key in the given data.
+      # Updates the +file+ key in the given +data+ to the actual files found in
+      # the repository.
+      # @raise [Dragnet::Errors::FileNotFoundError] If any of the listed files
+      #   cannot be found in the given repository path or if a glob pattern
+      #   doesn't match any files there.
+      def validate
+        return unless files
+
+        test_record.files = translate_paths && force_relative_paths && resolve_files
+      end
+
+      private
+
+      attr_reader :files
+
+      # Forces all the file paths to be relative by removing the +/+ at the
+      # start (if they have one). This is done to ensure that files are always
+      # considered relative to the path being checked.
+      def force_relative_paths
+        @files = files.map do |file|
+          file.sub(%r{^/}, '')
+        end
+      end
+
+      # Translate the file paths from windows style paths (with \ as path
+      # separator) to Unix style paths (with / as path separator).
+      # This is done so that the git commands work in all systems.
+      def translate_paths
+        @files = files.map do |file|
+          file.tr('\\', '/')
+        end
+      end
+
+      # Resolve the given files by checking for matches in the given repository.
+      # Glob patterns are resolved an translated into individual files.
+      # @return [Array<Pathname>] The resolved file paths.
+      # @raise [Dragnet::Errors::FileNotFoundError] If any of the listed files
+      #   cannot be found in the given repository path or if a glob pattern
+      #   doesn't match any files there.
+      def resolve_files
+        resolved_files = []
+
+        files.each do |file|
+          # Files can be defined as glob patterns
+          matched_files = path.glob(file)
+
+          if matched_files.empty?
+            raise Dragnet::Errors::FileNotFoundError,
+                  "Could not find any files matching #{file} in #{path}"
+          end
+
+          resolved_files += matched_files
+        end
+
+        resolved_files
+      end
+    end
+  end
+end

data/lib/dragnet/validators/repos_validator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../errors/repo_path_not_found_error'
+require_relative 'files_validator'
+
+module Dragnet
+  module Validators
+    # Validates the +Repo+ objects attached to the given +TestRecord+
+    class ReposValidator < Dragnet::Validators::Validator
+      attr_reader :test_record, :repos, :path
+
+      # @param [Dragnet::TestRecord] test_record The Test Record to validate.
+      # @param [Pathname] path The path where the repositories are supposed to
+      #   be located.
+      def initialize(test_record, path)
+        @test_record = test_record
+        @path = path
+        @repos = test_record.repos
+      end
+
+      # Validates the +Repo+ objects inside the given +TestCase+
+      def validate
+        return unless repos
+
+        validate_paths
+      end
+
+      private
+
+      # Validates the +paths+ of the +Repo+ objects (makes sure the paths
+      # exist). Knowing that these paths exist, the +files+ attribute of the
+      # +Repo+ object can be validated as well.
+      # @raise [Dragnet::Errors::RepoPathNotFoundError] If one or more of the
+      #   paths cannot be found.
+      # @raise [Dragnet::Errors::FileNotFoundError] If any of the files listed
+      #   in the +files+ attribute do not exist inside the given +path+.
+      def validate_paths
+        repos.each do |repo|
+          repo_path = repo.path = repo.path.gsub('\\', '/')
+          repo_path = Pathname.new(repo_path)
+
+          complete_path = repo_path.absolute? ? repo_path : path / repo_path
+
+          if complete_path.exist?
+            validate_files(repo, complete_path)
+            next
+          end
+
+          repo_path_not_found(repo_path)
+        end
+      end
+
+      # Validates the existence of the files listed in the +files+ attributes
+      # inside the +Repo+ object inside the +Repo+'s +path+.
+      # @param [Dragnet::Repo] repo The +Repo+ whose files should be validated.
+      # @param [Pathname] complete_path The path to the repository.
+      def validate_files(repo, complete_path)
+        return unless repo.files
+
+        Dragnet::Validators::FilesValidator.new(repo, complete_path).validate
+      end
+
+      # Raises a Dragnet::Errors::RepoPathNotFoundError with the appropriate
+      # message (which depends on whether the path is absolute or relative).
+      # @param [Pathname] repo_path The path that couldn't be found.
+      # @raise [Dragnet::Errors::RepoPathNotFoundError] is always raised.
+      def repo_path_not_found(repo_path)
+        message = "Cannot find the repository path #{repo_path}"
+        message += " inside #{path}" if repo_path.relative?
+        raise Dragnet::Errors::RepoPathNotFoundError, message
+      end
+    end
+  end
+end

data/lib/dragnet/validators/validator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../errors/yaml_format_error'
+
+module Dragnet
+  module Validators
+    # Base class for all validators.
+    class Validator
+      private
+
+      # Raises a +Dragnet::Errors::YAMLFormatError+ with the given message.
+      # @param [String] message The message for the exception.
+      # @raise [Dragnet::Errors::YAMLFormatError] Is always raised with the
+      #   given message.
+      def yaml_format_error(message)
+        raise Dragnet::Errors::YAMLFormatError, message
+      end
+    end
+  end
+end

data/lib/dragnet/validators.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'validators/data_validator'
+require_relative 'validators/entities'
+require_relative 'validators/fields'
+require_relative 'validators/files_validator'
+require_relative 'validators/validator'
+
+module Dragnet
+  # Namespace for Validator classes.
+  module Validators; end
+end

data/lib/dragnet/verification_result.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'colorize'
+
+require_relative 'errors/missing_timestamp_attribute_error'
+
+module Dragnet
+  # Holds the verification result of a Manual Test Record
+  class VerificationResult
+    VALID_STATUSES = %i[passed skipped failed].freeze
+
+    attr_reader :status, :reason, :started_at, :finished_at
+
+    # Creates a new instance of the class.
+    # @param [Symbol] status The status
+    # @param [String] reason
+    def initialize(status:, reason: nil)
+      self.status = status
+      @reason = reason
+    end
+
+    def passed?
+      status == :passed
+    end
+
+    def skipped?
+      status == :skipped
+    end
+
+    def failed?
+      status == :failed
+    end
+
+    # Assigns the given status
+    # @param [Symbol] status The status
+    # @raise [ArgumentError] If the given status is not one of the accepted
+    #   valid statuses.
+    def status=(status)
+      unless VALID_STATUSES.include?(status)
+        raise ArgumentError, "Invalid status #{status}."\
+              " Valid statuses are: #{VALID_STATUSES.join(', ')}"
+      end
+
+      @status = status
+    end
+
+    # Sets the verification's start time.
+    # @param [Time] time The verification's start time.
+    # @raise [ArgumentError] If the given +time+ is not an instance of +Time+.
+    # @raise [ArgumentError] If +finished_at+ is set and the given +time+ is
+    #   bigger than or equal to it.
+    def started_at=(time)
+      validate_time(time)
+      raise ArgumentError, 'started_at must be smaller than finished_at' if finished_at && time >= finished_at
+
+      @runtime = nil
+      @started_at = time
+    end
+
+    # Sets the verification's finish time
+    # @param [Time] time The verification's finish time.
+    # @raise [TypeError] Is an attempt is made to set +finished_at+ before
+    #   setting +started_at+.
+    # @raise [ArgumentError] If the given +time+ is not an instance of +Time+.
+    # @raise [ArgumentError] If +started_at+ is set and the given +time+ is
+    #   smaller than or equal to it.
+    def finished_at=(time)
+      validate_time(time)
+      raise ArgumentError, 'finished_at must be greater than started_at' if started_at && time <= started_at
+
+      @runtime = nil
+      @finished_at = time
+    end
+
+    # @return [Float, nil] The runtime calculated from the started_at and
+    #   finished_at attributes, if any of them is missing +nil+ is returned
+    #   instead.
+    def runtime
+      runtime!
+    rescue Dragnet::Errors::MissingTimestampAttributeError
+      nil
+    end
+
+    # @return [Float] The runtime calculated from the started_at and finished_at
+    #   timestamp attributes.
+    # @raise [TypeError] If either of these attributes is +nil+
+    def runtime!
+      @runtime ||= calculate_runtime
+    end
+
+    # @return [String] A string representation of the receiver that can be used
+    #   to log the result of a verification.
+    def log_message
+      if passed?
+        '✔ PASSED '.colorize(:light_green)
+      elsif skipped?
+        "#{'⚠ SKIPPED'.colorize(:light_yellow)} #{reason}"
+      else
+        "#{'✘ FAILED '.colorize(:light_red)} #{reason || 'Unknown reason'}"
+      end
+    end
+
+    private
+
+    # Checks if the given object is a +Time+ and raises an +ArgumentError+ if it
+    # isn't.
+    # @param [Object] time The object to check.
+    # @raise [ArgumentError] If the given object is not a +Time+ object.
+    def validate_time(time)
+      raise ArgumentError, "Expected a Time object, got #{time.class}" unless time.is_a?(Time)
+    end
+
+    # @return [Float] The runtime calculated from the started_at and finished_at
+    #   timestamp attributes.
+    # @raise [TypeError] If either of these attributes is +nil+
+    def calculate_runtime
+      if started_at.nil? || finished_at.nil?
+        raise Dragnet::Errors::MissingTimestampAttributeError,
+              'Both started_at and finished_at must be set in order to calculate the runtime'
+      end
+
+      finished_at - started_at
+    end
+  end
+end

data/lib/dragnet/verifier.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'git'
+
+require_relative 'verifiers/test_record_verifier'
+
+module Dragnet
+  # Executes the verification process on the given Test Records
+  class Verifier
+    attr_reader :test_records, :path, :logger
+
+    # Creates a new instance of the class.
+    # @param [Array<Hash>] test_records An array with the test records.
+    # @param [Dragnet::Repository] repository The repository where the MTR and
+    #   the source files are stored.
+    # @param [#info] logger The logger object to use for output.
+    def initialize(test_records:, repository:, logger:)
+      @test_records = test_records
+      @repository = repository
+      @logger = logger
+    end
+
+    # Runs the verify process
+    # After the execution of this method each Test Record will get a +:result+
+    # key with the result of the verification process. This key contains a hash
+    # like the following:
+    #
+    #  result: {
+    #    status: :passed,     # Either :passed, :failed or :skipped
+    #    reason: 'String'     # The reason for the failure (for :failed and :skipped)
+    #  }
+    def verify
+      logger.info 'Verifying MTR files...'
+      test_records.each do |test_record|
+        logger.info "Verifying #{test_record.source_file}"
+        verify_mtr(test_record)
+      end
+    end
+
+    private
+
+    attr_reader :repository
+
+    # Verifies the given Manual Test Record
+    # Runs the given test record through all the verifiers. If no verifier adds
+    # a +result+ key to the Test Record then the method adds one with passed
+    # status.
+    # @param [Dragnet::TestRecord] test_record The Test Record to verify.
+    def verify_mtr(test_record)
+      started_at = Time.now.utc
+
+      verification_result = Dragnet::Verifiers::TestRecordVerifier.new(
+        test_record: test_record, repository: repository, test_records: test_records
+      ).verify
+
+      finished_at = Time.now.utc
+      verification_result.started_at = started_at
+      verification_result.finished_at = finished_at
+      test_record.verification_result = verification_result
+
+      logger.info(verification_result.log_message)
+    end
+  end
+end

data/lib/dragnet/verifiers/changes_verifier.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../verification_result'
+require_relative 'repository_verifier'
+
+module Dragnet
+  module Verifiers
+    # Checks for changes in the repository since the creation of the MTR Record
+    class ChangesVerifier < Dragnet::Verifiers::RepositoryVerifier
+      attr_reader :test_records
+
+      # @param [Dragnet::TestRecord] test_record The +TestRecord+ object to
+      #   verify.
+      # @param [Dragnet::Repository] repository A +Dragnet::Repository+ object
+      #   linked to the repository where the verification should be executed.
+      # @param [Array<Hash>] test_records The hash of all the test records. This
+      #   is used to determine if the changes in the repository are only in the
+      #   Test Record Files, in which case the Test Records will still be
+      #   considered valid.
+      def initialize(test_record:, repository:, test_records:)
+        super(test_record: test_record, repository: repository)
+        @test_records = test_records
+      end
+
+      # Runs the verification process. Checks the changes on the repository
+      # between the Commit with the SHA1 registered in the MTR and the current
+      # HEAD.
+      # @return [Dragnet::VerificationResult, nil] A +VerificationResult+ with
+      #   the details of the changes found in the repository or +nil+ if no
+      #   changes were found.
+      def verify
+        diff = repository.diff(sha1, 'HEAD')
+        return unless diff.size.positive?
+
+        find_changes(diff)
+      end
+
+      private
+
+      # Scans the given diff for changes. If changes are detected then a
+      # +:result+ key will be added to the +test_record+. Changes to the MTR
+      # files themselves are ignored.
+      # @return [Dragnet::VerificationResult, nil] A +VerificationResult+ with
+      #   the details of the changes found in the repository, or +nil+ if no
+      #   changes were found.
+      def find_changes(diff)
+        diff.stats[:files].each do |file, _changes|
+          next if mtr_files.include?(file) # Changes to MTR files are ignored.
+
+          return Dragnet::VerificationResult.new(
+            status: :skipped,
+            reason: "Changes detected in the repository: #{shorten_sha1(sha1)}..#{shorten_sha1(repository.head.sha)}"\
+                    " # -- #{file}"
+          )
+        end
+
+        nil
+      end
+
+      # @return [Array<Strings>] An array of strings with the paths to all the
+      #   known MTR files. These will be excluded when checking from changes in
+      #   the repository.
+      def mtr_files
+        @mtr_files ||= test_records.map do |test_record|
+          test_record.source_file.relative_path_from(path).to_s
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/verifiers/files_verifier.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative '../verification_result'
+require_relative 'repository_verifier'
+
+module Dragnet
+  module Verifiers
+    # Checks if any of the files listed in the MTR have changed since the MTR
+    # was created.
+    class FilesVerifier < Dragnet::Verifiers::RepositoryVerifier
+      # Executes the verification process.
+      # Checks the changes in the repository. If a change in one of the files
+      # is detected a +:result+ key is added to the MTR, including the detected
+      # change.
+      # @return [Dragnet::VerificationResult, nil] A +VerificationResult+ object
+      #   with the detected changes to the listed files or +nil+ if no changes
+      #   are found.
+      def verify
+        changes = []
+
+        files.each do |file|
+          diff = repository.diff(sha1, 'HEAD').path(file.to_s)
+          next unless diff.size.positive?
+
+          changes << file
+        end
+
+        result_from(changes) if changes.any?
+      end
+
+      private
+
+      # @return [Array<String>] The paths to the files listed in the MTR file.
+      def files
+        @files ||= test_record.files.map do |file|
+          file.relative_path_from(path)
+        end
+      end
+
+      # Stores the detected changes on the Test Record
+      # @param [Array<String>] changes The array of changed files.
+      def result_from(changes)
+        Dragnet::VerificationResult.new(
+          status: :skipped,
+          reason: "Changes detected in listed file(s): #{shorten_sha1(sha1)}..#{shorten_sha1(repository.head.sha)}"\
+                  " -- #{changes.join(' ')}"
+        )
+      end
+    end
+  end
+end