elasticsearch-api 7.17.1 → 8.0.1

data/api-spec-testing/test_file/test.rb

@@ -0,0 +1,295 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Elasticsearch
+  module RestAPIYAMLTests
+    class TestFile
+      # Represents a single test in a test file. A single test can have many operations and validations.
+      #
+      # @since 6.2.0
+      class Test
+        class << self
+          # Given a list of keys, find the value in a recursively nested document.
+          #
+          # @param [ Array<String> ] chain The list of nested document keys.
+          # @param [ Hash ] document The document to find the value in.
+          #
+          # @return [ Object ] The value at the nested key.
+          #
+          # @since 6.2.0
+          def find_value_in_document(chain, document)
+            return document[chain] unless chain.is_a?(Array)
+            return document[chain[0]] unless chain.size > 1
+
+            # a number can be a string key in a Hash or indicate an element in a list
+            if document.is_a?(Hash)
+              find_value_in_document(chain[1..-1], document[chain[0].to_s]) if document[chain[0].to_s]
+            elsif document[chain[0]]
+              find_value_in_document(chain[1..-1], document[chain[0]]) if document[chain[0]]
+            end
+          end
+
+          # Given a string representing a nested document key using dot notation,
+          #   split it, keeping escaped dots as part of a key name and replacing
+          #   numerics with a Ruby Integer.
+          #
+          # For example:
+          #   "joe.metadata.2.key2" => ['joe', 'metadata', 2, 'key2']
+          #   "jobs.0.node.attributes.ml\\.enabled" => ["jobs", 0, "node", "attributes", "ml\\.enabled"]
+          #
+          # @param [ String ] chain The list of nested document keys.
+          # @param [ Hash ] document The document to find the value in.
+          #
+          # @return [ Array<Object> ] A list of the nested keys.
+          #
+          # @since 6.2.0
+          def split_and_parse_key(key)
+            key.split(/(?<!\\)\./).reject { |k| k.empty? }.map do |key_part|
+              case key_part
+               when /^\.\$/ # For keys in the form of .$key
+                 key_part.gsub(/^\./, '')
+              when /\A[-+]?[0-9]+\z/
+                key_part.to_i
+              else
+                key_part.gsub('\\', '')
+              end
+            end.reject { |k| k == '$body' }
+          end
+        end
+
+        attr_reader :description, :test_file, :cached_values, :file_basename
+
+        # Actions that if followed by a 'do' action, indicate that they complete their task group.
+        # For example, consider this sequence of actions:
+        #   do, do, match, match, do, match
+        # The second match indicates that the task group is complete and can be run as a unit.
+        # That sequence becomes two task groups:
+        #   do, do, match, match
+        #   do, match
+        #
+        # @since 6.2.0
+        GROUP_TERMINATORS = [
+          'length',
+          'gt',
+          'gte',
+          'lt',
+          'lte',
+          'set',
+          'transform_and_set',
+          'match',
+          'is_false',
+          'is_true'
+        ].freeze
+
+        # The maximum Elasticsearch version this client version can successfully run tests against.
+        #
+        # @since 6.2.0
+        MAX_REQUIRED_VERSION = nil
+
+        # The minimum Elasticsearch version this client version can successfully run tests against.
+        #
+        # @since 6.2.0
+        MIN_REQUIRED_VERSION = nil
+
+        # Initialize the Test object.
+        #
+        # @example Create a test object
+        #   Test.new(file, definition)
+        #
+        # @param [ String ] test_file The name of the test file.
+        # @param [ Hash ] test_definition A hash corresponding to the parsed YAML containing the test definition.
+        #
+        # @since 6.2.0
+        def initialize(test_file, test_definition)
+          @test_file = test_file
+          @file_basename = test_file.name.gsub("#{YAML_FILES_DIRECTORY}/", '')
+          @description = test_definition.keys.first
+          @definition = test_definition[description].select { |doc| !doc.key?('skip') }
+          @definition.delete_if { |doc| doc['skip'] }
+          @cached_values = {}
+          skip_definitions = test_definition[description].select { |doc| doc['skip'] }.compact
+          @skip = skip_definitions unless skip_definitions.empty?
+        end
+
+        # Get the list of task groups in this test.
+        #
+        # @example
+        #   test.task_groups
+        #
+        # @return [ Array<TaskGroup> ] The list of task groups.
+        #
+        # @since 6.2.0
+        def task_groups
+          @task_groups ||= begin
+            @definition.each_with_index.inject([]) do |task_groups, (action, i)|
+              # the action has a catch, it's a singular task group
+              if action['do'] && action['do']['catch']
+                task_groups << TaskGroup.new(self)
+              elsif action['do'] && i > 0 && is_a_validation?(@definition[i-1])
+                task_groups << TaskGroup.new(self)
+              elsif i == 0
+                task_groups << TaskGroup.new(self)
+              end
+
+              task_groups[-1].add_action(action) && task_groups
+            end
+          end
+        end
+
+        # Cache a value on this test object.
+        #
+        # @example
+        #   test.cache_value(cache_key, value)
+        #
+        # @param [ String ] cache_key The cache key for the value.
+        # @param [ Object ] value The value to cache.
+        #
+        # @return [ Hash ] The cached values.
+        #
+        # @since 6.2.0
+        def cache_value(cache_key, value)
+          @cached_values[cache_key] = value
+          @cached_values
+        end
+
+        # Get a cached value.
+        #
+        # @example
+        #   test.get_cached_value('$watch_count_active')
+        #
+        # @param [ String ] key The key of the cached value.
+        #
+        # @return [ Hash ] The cached value at the key or the key if it's not found.
+        #
+        # @since 6.2.0
+        def get_cached_value(key)
+          case key
+          when String
+            key =~ /^\$/ ? @cached_values.fetch(key.gsub(/[\$\{\}]/, ''), key) : key
+          when Hash
+            key.inject({}) do |hash, (k, v)|
+              if v.is_a?(String)
+                hash.merge(@cached_values.fetch(k.gsub(/[\$\{\}]/, ''), k) => @cached_values.fetch(v.gsub(/[\$\{\}]/, ''), v))
+              else
+                hash.merge(@cached_values.fetch(k.gsub(/[\$\{\}]/, ''), k) => v)
+              end
+            end
+          when Array
+            key.collect do |k|
+              k.is_a?(String) ? @cached_values.fetch(k.gsub(/[\$\{\}]/, ''), k) : k
+            end
+          else
+            key
+          end
+        end
+
+        # Run all the tasks in this test.
+        #
+        # @example
+        #   test.run(client)
+        #
+        # @param [ Elasticsearch::Client ] client The client to use when executing operations.
+        #
+        # @return [ self ]
+        #
+        # @since 6.2.0
+        def run(client)
+          task_groups.each { |task_group| task_group.run(client) }
+          self
+        end
+
+        # Determine whether this test should be skipped, given a list of unsupported features.
+        #
+        # @example
+        #   test.skip_test?(['warnings'])
+        #
+        # @param [ Array<String> ] features_to_skip A list of the features to skip.
+        #
+        # @return [ true, false ] Whether this test should be skipped, given a list of unsupported features.
+        #
+        # @since 6.2.0
+        def skip_test?(client, features_to_skip = test_file.features_to_skip)
+          return true if pre_defined_skip?
+
+          if @skip
+            @skip.collect { |s| s['skip'] }.any? do |skip_definition|
+              contains_features_to_skip?(features_to_skip, skip_definition) || test_file.skip_version?(client, skip_definition)
+            end
+          end
+        end
+
+        # Replace the `$master` substring in a key with the cached master node's id.
+        #
+        # @param [ String ] expected_key The expected key, containing the substring `$master` that needs to be replaced.
+        #
+        # See test xpack/10_basic.yml
+
+        # @return [ String ] The altered key.
+        #
+        # @since 7.2.0
+        def inject_master_node_id(expected_key)
+          if cached_values['master']
+            expected_key.gsub(/\$master/, cached_values['master'])
+          else
+            expected_key
+          end
+        end
+
+        private
+
+        def contains_features_to_skip?(features_to_skip, skip_definition)
+          !(features_to_skip &  ([skip_definition['features']].flatten || [])).empty?
+        end
+
+        def pre_defined_skip?
+          SKIPPED_TESTS.find do |t|
+            file_basename == t[:file] && (description == t[:description] || t[:description] == '*')
+          end
+        end
+
+        # Given the server version and the skip definition version, returns if a
+        # test should be skipped. It will return true if the server version is
+        # contained in the range of the test's skip definition version.
+        #
+        def skip_version?(client, skip_definition)
+          return true if skip_definition['version'] == 'all'
+
+          range_partition = /\s*-\s*/
+          if versions = skip_definition['version'] &&
+                        skip_definition['version'].partition(range_partition)
+            low, high = __parse_versions(versions)
+            range = low..high
+            begin
+              server_version = client.info['version']['number']
+            rescue
+              warn('Could not determine Elasticsearch version when checking if test should be skipped.')
+            end
+            range.cover?(server_version)
+          end
+        end
+
+        def is_a_validation?(action)
+          GROUP_TERMINATORS.any? { |validation| action[validation] } || expects_exception?(action)
+        end
+
+        def expects_exception?(action)
+          action['do'] && action['do']['catch']
+        end
+      end
+    end
+  end
+end

data/api-spec-testing/test_file.rb

@@ -0,0 +1,173 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+require_relative 'test_file/action'
+require_relative 'test_file/test'
+require_relative 'test_file/task_group'
+require_relative 'logging'
+
+module Elasticsearch
+  module RestAPIYAMLTests
+    # Custom exception to raise when a test file needs to be skipped. This is
+    # captured as soon as possible so the test runners can move on to the next test.
+    class SkipTestsException < StandardError
+    end
+
+    # Class representing a single test file, containing a setup, teardown, and multiple tests.
+    #
+    # @since 6.2.0
+    class TestFile
+      include Elasticsearch::RestAPIYAMLTests::Logging
+      attr_reader :features_to_skip, :name, :client
+
+      # Initialize a single test file.
+      #
+      # @example Create a test file object.
+      #   TestFile.new(file_name)
+      #
+      # @param [ String ] file_name The name of the test file.
+      # @param [ Client] An instance of the client
+      # @param [ Array<Symbol> ] skip_features The names of features to skip.
+      #
+      # @since 6.1.0
+      def initialize(file_name, client, features_to_skip = [])
+        @name = file_name
+        @client = client
+        begin
+          documents = YAML.load_stream(File.new(file_name))
+        rescue StandardError => e
+          logger.error e
+          logger.error "Filename : #{@name}"
+        end
+        @test_definitions = documents.reject { |doc| doc['setup'] || doc['teardown'] }
+        @setup = documents.find { |doc| doc['setup'] }
+        skip_entire_test_file? if @setup
+        @teardown = documents.find { |doc| doc['teardown'] }
+        @features_to_skip = REST_API_YAML_SKIP_FEATURES + features_to_skip
+      end
+
+      def skip_entire_test_file?
+        @skip = @setup['setup']&.select { |a| a['skip'] }
+        return false if @skip.empty?
+
+        raise SkipTestsException if skip_version?(@client, @skip.first['skip'])
+      end
+
+      def skip_version?(client, skip_definition)
+        return true if skip_definition['version'] == 'all'
+
+        range_partition = /\s*-\s*/
+        return unless (versions = skip_definition['version'])
+
+        low, high = __parse_versions(versions.partition(range_partition))
+        range = low..high
+        begin
+          server_version = client.info['version']['number']
+        rescue
+          warn('Could not determine Elasticsearch version when checking if test should be skipped.')
+        end
+        range.cover?(Gem::Version.new(server_version))
+      end
+
+      def __parse_versions(versions)
+        versions = versions.split('-') if versions.is_a? String
+
+        low = (['', nil].include? versions[0]) ? '0' : versions[0]
+        high = (['', nil].include? versions[2]) ? '9999' : versions[2]
+        [Gem::Version.new(low), Gem::Version.new(high)]
+      end
+
+      # Get a list of tests in the test file.
+      #
+      # @example Get the list of tests
+      #   test_file.tests
+      #
+      # @return [ Array<Test> ] A list of Test objects.
+      #
+      # @since 6.2.0
+      def tests
+        @test_definitions.collect do |test_definition|
+          Test.new(self, test_definition)
+        end
+      end
+
+      # Run the setup tasks defined for a single test file.
+      #
+      # @example Run the setup tasks.
+      #   test_file.setup
+      #
+      # @param [ Elasticsearch::Client ] client The client to use to perform the setup tasks.
+      #
+      # @return [ self ]
+      #
+      # @since 6.2.0
+      def setup
+        return unless @setup
+
+        actions = @setup['setup'].select { |action| action['do'] }.map { |action| Action.new(action['do']) }
+        run_actions_and_retry(actions)
+        self
+      end
+
+      # Run the teardown tasks defined for a single test file.
+      #
+      # @example Run the teardown tasks.
+      #   test_file.teardown
+      #
+      # @param [ Elasticsearch::Client ] client The client to use to perform the teardown tasks.
+      #
+      # @return [ self ]
+      #
+      # @since 6.2.0
+      def teardown
+        return unless @teardown
+
+        actions = @teardown['teardown'].select { |action| action['do'] }.map { |action| Action.new(action['do']) }
+        run_actions_and_retry(actions)
+        self
+      end
+
+      # Helper function to run actions. If the server returns an error, give it some time and retry
+      # for a few times.
+      def run_actions_and_retry(actions)
+        count = 0
+        loop do
+          actions.delete_if do |action|
+            begin
+              action.execute(client)
+              true
+            rescue Elastic::Transport::Transport::Errors::RequestTimeout,
+                   Elastic::Transport::Transport::Errors::ServiceUnavailable => e
+              # The action sometimes gets the cluster in a recovering state, so we
+              # retry a few times and then raise an exception if it's still
+              # happening
+              count += 1
+              sleep 10
+              logger.debug(
+                "The server responded with an #{e.class} error. Retrying action - (#{count})"
+              )
+              raise e if count > 11
+
+              false
+            end
+          end
+          break if actions.empty?
+        end
+      end
+    end
+  end
+end