Package org.elasticsearch.test

Class ESIntegTestCase

  • Direct Known Subclasses:
    AbstractNumericTestCase, AbstractTermsTestCase, ESBlobStoreRepositoryIntegTestCase
    @SuppressFileSystems("ExtrasFS")
public abstract class ESIntegTestCase
extends ESTestCase
    ESIntegTestCase is an abstract base class to run integration tests against a JVM private Elasticsearch Cluster. The test class supports 2 different cluster scopes.

    The most common test scope is ESIntegTestCase.Scope.SUITE which shares a cluster per test suite.

    If the test methods need specific node settings or change persistent and/or transient cluster settings ESIntegTestCase.Scope.TEST should be used. To configure a scope for the test cluster the ESIntegTestCase.ClusterScope annotation should be used, here is an example: 

    
 @NodeScope(scope=Scope.TEST) public class SomeIT extends ESIntegTestCase {
 public void testMethod() {}
 }

    If no ESIntegTestCase.ClusterScope annotation is present on an integration test the default scope is ESIntegTestCase.Scope.SUITE

    A test cluster creates a set of nodes in the background before the test starts. The number of nodes in the cluster is determined at random and can change across tests. The ESIntegTestCase.ClusterScope allows configuring the initial number of nodes that are created before the tests start. 

     @NodeScope(scope=Scope.SUITE, numDataNodes=3)
 public class SomeIT extends ESIntegTestCase {
 public void testMethod() {}
 }

    Note, the ESIntegTestCase uses randomized settings on a cluster and index level. For instance each test might use different directory implementation for each test or will return a random client to one of the nodes in the cluster for each call to client(). Test failures might only be reproducible if the correct system properties are passed to the test execution environment.

    This class supports the following system properties (passed with -Dkey=value to the application)

    • -D"tests.client.ratio" - a double value in the interval [0..1] which defines the ration between node and transport clients used
    • -D"tests.enable_mock_modules" - a boolean value to enable or disable mock modules. This is useful to test the system without asserting modules that to make sure they don't hide any bugs in production.
    • - a random seed used to initialize the index random context.

    • Field Detail

      • SYSPROP_THIRDPARTY

        public static final java.lang.String SYSPROP_THIRDPARTY
        Property that controls whether ThirdParty Integration tests are run (not the default).
        See Also:
        Constant Field Values

      • SUITE_CLUSTER_NODE_PREFIX

        public static final java.lang.String SUITE_CLUSTER_NODE_PREFIX
        node names of the corresponding clusters will start with these prefixes
        See Also:
        Constant Field Values

      • TEST_CLUSTER_NODE_PREFIX

        public static final java.lang.String TEST_CLUSTER_NODE_PREFIX
        See Also:
        Constant Field Values

      • TESTS_CLIENT_RATIO

        public static final java.lang.String TESTS_CLIENT_RATIO
        Key used to set the transport client ratio via the commandline -D"tests.client.ratio"
        See Also:
        Constant Field Values

      • TESTS_CLUSTER

        public static final java.lang.String TESTS_CLUSTER
        Key used to eventually switch to using an external cluster and provide its transport addresses
        See Also:
        Constant Field Values

      • INDEX_TEST_SEED_SETTING

        public static final Setting<java.lang.Long> INDEX_TEST_SEED_SETTING
        Key used to retrieve the index random seed from the index settings on a running node. The value of this seed can be used to initialize a random context for a specific index. It's set once per test via a generic index template.

      • TESTS_ENABLE_MOCK_MODULES

        public static final java.lang.String TESTS_ENABLE_MOCK_MODULES
        A boolean value to enable or disable mock modules. This is useful to test the system without asserting modules that to make sure they don't hide any bugs in production.
        See Also:
        ESIntegTestCase, Constant Field Values

      • DEFAULT_MIN_NUM_SHARDS

        protected static final int DEFAULT_MIN_NUM_SHARDS
        Default minimum number of shards for an index
        See Also:
        Constant Field Values

      • DEFAULT_MAX_NUM_SHARDS

        protected static final int DEFAULT_MAX_NUM_SHARDS
        Default maximum number of shards for an index
        See Also:
        Constant Field Values

    • Constructor Detail

      • ESIntegTestCase

        public ESIntegTestCase()

    • Method Detail

      • beforeClass

        public static void beforeClass()
                        throws java.lang.Exception
        Throws:
        java.lang.Exception

      • enableWarningsCheck

        protected final boolean enableWarningsCheck()
        Description copied from class: ESTestCase
        Whether or not we check after each test whether it has left warnings behind. That happens if any deprecated feature or syntax was used by the test and the test didn't assert on it using ESTestCase.assertWarnings(String...).
        Overrides:
        enableWarningsCheck in class ESTestCase

      • beforeInternal

        protected final void beforeInternal()
                             throws java.lang.Exception
        Throws:
        java.lang.Exception

      • randomIndexTemplate

        public void randomIndexTemplate()
                         throws java.io.IOException
        Creates a randomized index template. This template is used to pass in randomized settings on a per index basis. Allows to enable/disable the randomization for number of shards and replicas
        Throws:
        java.io.IOException

      • afterInternal

        protected final void afterInternal​(boolean afterClass)
                            throws java.lang.Exception
        Throws:
        java.lang.Exception

      • excludeTemplates

        protected java.util.Set<java.lang.String> excludeTemplates()
        Returns:
        An exclude set of index templates that will not be removed in between tests.

      • beforeIndexDeletion

        protected void beforeIndexDeletion()
                            throws java.lang.Exception
        Throws:
        java.lang.Exception

      • isInternalCluster

        public static boolean isInternalCluster()

      • client

        public static Client client()

      • client

        public static Client client​(@Nullable
                            java.lang.String node)

      • dataNodeClient

        public static Client dataNodeClient()

      • clients

        public static java.lang.Iterable<Client> clients()

      • minimumNumberOfShards

        protected int minimumNumberOfShards()

      • maximumNumberOfShards

        protected int maximumNumberOfShards()

      • numberOfShards

        protected int numberOfShards()

      • minimumNumberOfReplicas

        protected int minimumNumberOfReplicas()

      • maximumNumberOfReplicas

        protected int maximumNumberOfReplicas()

      • numberOfReplicas

        protected int numberOfReplicas()

      • clearDisruptionScheme

        public void clearDisruptionScheme()

      • indexSettings

        public Settings indexSettings()
        Returns a settings object used in createIndex(String...) and prepareCreate(String) and friends. This method can be overwritten by subclasses to set defaults for the indices that are created by the test. By default it returns a settings object that sets a random number of shards. Number of shards and replicas can be controlled through specific methods.

      • createIndex

        public final void createIndex​(java.lang.String... names)
        Creates one or more indices and asserts that the indices are acknowledged. If one of the indices already exists this method will fail and wipe all the indices created so far.

      • createIndex

        public final void createIndex​(java.lang.String name,
                              Settings indexSettings)
        creates an index with the given setting

      • prepareCreate

        public final CreateIndexRequestBuilder prepareCreate​(java.lang.String index,
                                                     int numNodes)
        Creates a new CreateIndexRequestBuilder with the settings obtained from indexSettings(). The index that is created with this builder will only be allowed to allocate on the number of nodes passed to this method.

        This method uses allocation deciders to filter out certain nodes to allocate the created index on. It defines allocation rules based on index.routing.allocation.exclude._name.

      • prepareCreate

        public CreateIndexRequestBuilder prepareCreate​(java.lang.String index,
                                               int numNodes,
                                               Settings.Builder settingsBuilder)
        Creates a new CreateIndexRequestBuilder with the settings obtained from indexSettings(). The index that is created with this builder will only be allowed to allocate on the number of nodes passed to this method.

        This method uses allocation deciders to filter out certain nodes to allocate the created index on. It defines allocation rules based on index.routing.allocation.exclude._name.

      • waitNoPendingTasksOnAll

        public void waitNoPendingTasksOnAll()
                             throws java.lang.Exception
        Waits until all nodes have no pending tasks.
        Throws:
        java.lang.Exception

      • assertConcreteMappingsOnAll

        public void assertConcreteMappingsOnAll​(java.lang.String index,
                                        java.lang.String type,
                                        java.lang.String... fieldNames)
                                 throws java.lang.Exception
        Waits until mappings for the provided fields exist on all nodes. Note, this waits for the current started shards and checks for concrete mappings.
        Throws:
        java.lang.Exception

      • assertMappingOnMaster

        public void assertMappingOnMaster​(java.lang.String index,
                                  java.lang.String type,
                                  java.lang.String... fieldNames)
                           throws java.lang.Exception
        Waits for the given mapping type to exists on the master node.
        Throws:
        java.lang.Exception

      • assertResultsAndLogOnFailure

        public void assertResultsAndLogOnFailure​(long expectedResults,
                                         SearchResponse searchResponse)
        Ensures the result counts are as expected, and logs the results if different

      • allowNodes

        public void allowNodes​(java.lang.String index,
                       int n)
        Restricts the given index to be allocated on n nodes using the allocation deciders. Yet if the shards can't be allocated on any other node shards for this index will remain allocated on more than n nodes.

      • ensureGreen

        public ClusterHealthStatus ensureGreen​(java.lang.String... indices)
        Ensures the cluster has a green state via the cluster health API. This method will also wait for relocations. It is useful to ensure that all action on the cluster have finished and all shards that were currently relocating are now allocated and started.

      • ensureGreen

        public ClusterHealthStatus ensureGreen​(TimeValue timeout,
                                       java.lang.String... indices)
        Ensures the cluster has a green state via the cluster health API. This method will also wait for relocations. It is useful to ensure that all action on the cluster have finished and all shards that were currently relocating are now allocated and started.
        Parameters:
        timeout - time out value to set on ClusterHealthRequest

      • ensureYellow

        public ClusterHealthStatus ensureYellow​(java.lang.String... indices)
        Ensures the cluster has a yellow state via the cluster health API.

      • ensureYellowAndNoInitializingShards

        public ClusterHealthStatus ensureYellowAndNoInitializingShards​(java.lang.String... indices)
        Ensures the cluster has a yellow state via the cluster health API and ensures the that cluster has no initializing shards for the given indices

      • waitForRelocation

        public ClusterHealthStatus waitForRelocation()
        Waits for all relocating shards to become active using the cluster health API.

      • waitForRelocation

        public ClusterHealthStatus waitForRelocation​(ClusterHealthStatus status)
        Waits for all relocating shards to become active and the cluster has reached the given health status using the cluster health API.

      • waitForDocs

        public long waitForDocs​(long numDocs)
                 throws java.lang.InterruptedException
        Waits until at least a give number of document is visible for searchers
        Parameters:
        numDocs - number of documents to wait for.
        Returns:
        the actual number of docs seen.
        Throws:
        java.lang.InterruptedException

      • waitForDocs

        public long waitForDocs​(long numDocs,
                        @Nullable
                        BackgroundIndexer indexer)
                 throws java.lang.InterruptedException
        Waits until at least a give number of document is visible for searchers
        Parameters:
        numDocs - number of documents to wait for
        indexer - a BackgroundIndexer. If supplied it will be first checked for documents indexed. This saves on unneeded searches.
        Returns:
        the actual number of docs seen.
        Throws:
        java.lang.InterruptedException

      • waitForDocs

        public long waitForDocs​(long numDocs,
                        int maxWaitTime,
                        java.util.concurrent.TimeUnit maxWaitTimeUnit,
                        @Nullable
                        BackgroundIndexer indexer)
                 throws java.lang.InterruptedException
        Waits until at least a give number of document is visible for searchers
        Parameters:
        numDocs - number of documents to wait for
        maxWaitTime - if not progress have been made during this time, fail the test
        maxWaitTimeUnit - the unit in which maxWaitTime is specified
        indexer - If supplied it will be first checked for documents indexed. This saves on unneeded searches.
        Returns:
        the actual number of docs seen.
        Throws:
        java.lang.InterruptedException

      • setMinimumMasterNodes

        public void setMinimumMasterNodes​(int n)
        Sets the cluster's minimum master node and make sure the response is acknowledge. Note: this doesn't guarantee that the new setting has taken effect, just that it has been received by all nodes.

      • logClusterState

        public void logClusterState()
        Prints the current cluster state as debug logging.

      • logSegmentsState

        public void logSegmentsState​(java.lang.String... indices)
                      throws java.lang.Exception
        Prints the segments info for the given indices as debug logging.
        Throws:
        java.lang.Exception

      • logMemoryStats

        public void logMemoryStats()
        Prints current memory stats as info logging.

      • ensureClusterSizeConsistency

        protected void ensureClusterSizeConsistency()

      • ensureClusterStateConsistency

        protected void ensureClusterStateConsistency()
                                      throws java.io.IOException
        Verifies that all nodes that have the same version of the cluster state as master have same cluster state
        Throws:
        java.io.IOException

      • ensureSearchable

        protected ClusterHealthStatus ensureSearchable​(java.lang.String... indices)
        Ensures the cluster is in a searchable state for the given indices. This means a searchable copy of each shard is available on the cluster.

      • ensureStableCluster

        protected void ensureStableCluster​(int nodeCount)

      • ensureStableCluster

        protected void ensureStableCluster​(int nodeCount,
                                   TimeValue timeValue)

      • ensureStableCluster

        protected void ensureStableCluster​(int nodeCount,
                                   @Nullable
                                   java.lang.String viaNode)

      • ensureStableCluster

        protected void ensureStableCluster​(int nodeCount,
                                   TimeValue timeValue,
                                   boolean local,
                                   @Nullable
                                   java.lang.String viaNode)

      • ensureFullyConnectedCluster

        protected void ensureFullyConnectedCluster()
        Ensures that all nodes in the cluster are connected to each other. Some network disruptions may leave nodes that are not the master disconnected from each other. NodeConnectionsService will eventually reconnect but it's handy to be able to ensure this happens faster

      • index

        protected final IndexResponse index​(java.lang.String index,
                                    java.lang.String type,
                                    XContentBuilder source)
        Syntactic sugar for: 
           client().prepareIndex(index, type).setSource(source).execute().actionGet();

      • index

        protected final IndexResponse index​(java.lang.String index,
                                    java.lang.String type,
                                    java.lang.String id,
                                    java.util.Map<java.lang.String,​java.lang.Object> source)
        Syntactic sugar for: 
           client().prepareIndex(index, type).setSource(source).execute().actionGet();

      • get

        protected final GetResponse get​(java.lang.String index,
                                java.lang.String type,
                                java.lang.String id)
        Syntactic sugar for: 
           client().prepareGet(index, type, id).execute().actionGet();

      • index

        protected final IndexResponse index​(java.lang.String index,
                                    java.lang.String type,
                                    java.lang.String id,
                                    XContentBuilder source)
        Syntactic sugar for: 
           return client().prepareIndex(index, type, id).setSource(source).execute().actionGet();

      • index

        protected final IndexResponse index​(java.lang.String index,
                                    java.lang.String type,
                                    java.lang.String id,
                                    java.lang.Object... source)
        Syntactic sugar for: 
           return client().prepareIndex(index, type, id).setSource(source).execute().actionGet();

      • index

        protected final IndexResponse index​(java.lang.String index,
                                    java.lang.String type,
                                    java.lang.String id,
                                    java.lang.String source)
        Syntactic sugar for: 
           return client().prepareIndex(index, type, id).setSource(source).execute().actionGet();

        where source is a JSON String.

      • refresh

        protected final RefreshResponse refresh​(java.lang.String... indices)
        Waits for relocations and refreshes all indices in the cluster.
        See Also:
        waitForRelocation()

      • flushAndRefresh

        protected final void flushAndRefresh​(java.lang.String... indices)
        Flushes and refreshes all indices in the cluster

      • flush

        protected final FlushResponse flush​(java.lang.String... indices)
        Flush some or all indices in the cluster.

      • forceMerge

        protected ForceMergeResponse forceMerge()
        Waits for all relocations and force merge all indices in the cluster to 1 segment.

      • indexExists

        protected boolean indexExists​(java.lang.String index)
        Returns true iff the given index exists otherwise false

      • enableAllocation

        protected final void enableAllocation​(java.lang.String... indices)
        Syntactic sugar for enabling allocation for indices

      • disableAllocation

        protected final void disableAllocation​(java.lang.String... indices)
        Syntactic sugar for disabling allocation for indices

      • admin

        protected AdminClient admin()
        Returns a random admin client. This client can either be a node or a transport client pointing to any of the nodes in the cluster.

      • indexRandom

        public void indexRandom​(boolean forceRefresh,
                        IndexRequestBuilder... builders)
                 throws java.lang.InterruptedException,
                        java.util.concurrent.ExecutionException
        Convenience method that forwards to indexRandom(boolean, List).
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException

      • indexRandom

        public void indexRandom​(boolean forceRefresh,
                        boolean dummyDocuments,
                        IndexRequestBuilder... builders)
                 throws java.lang.InterruptedException,
                        java.util.concurrent.ExecutionException
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException

      • indexRandom

        public void indexRandom​(boolean forceRefresh,
                        java.util.List<IndexRequestBuilder> builders)
                 throws java.lang.InterruptedException,
                        java.util.concurrent.ExecutionException
        Indexes the given IndexRequestBuilder instances randomly. It shuffles the given builders and either indexes them in a blocking or async fashion. This is very useful to catch problems that relate to internal document ids or index segment creations. Some features might have bug when a given document is the first or the last in a segment or if only one document is in a segment etc. This method prevents issues like this by randomizing the index layout.
        Parameters:
        forceRefresh - if true all involved indices are refreshed once the documents are indexed. Additionally if true some empty dummy documents are may be randomly inserted into the document list and deleted once all documents are indexed. This is useful to produce deleted documents on the server side.
        builders - the documents to index.
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException
        See Also:
        indexRandom(boolean, boolean, java.util.List)

      • indexRandom

        public void indexRandom​(boolean forceRefresh,
                        boolean dummyDocuments,
                        java.util.List<IndexRequestBuilder> builders)
                 throws java.lang.InterruptedException,
                        java.util.concurrent.ExecutionException
        Indexes the given IndexRequestBuilder instances randomly. It shuffles the given builders and either indexes them in a blocking or async fashion. This is very useful to catch problems that relate to internal document ids or index segment creations. Some features might have bug when a given document is the first or the last in a segment or if only one document is in a segment etc. This method prevents issues like this by randomizing the index layout.
        Parameters:
        forceRefresh - if true all involved indices are refreshed once the documents are indexed.
        dummyDocuments - if true some empty dummy documents may be randomly inserted into the document list and deleted once all documents are indexed. This is useful to produce deleted documents on the server side.
        builders - the documents to index.
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException

      • indexRandom

        public void indexRandom​(boolean forceRefresh,
                        boolean dummyDocuments,
                        boolean maybeFlush,
                        java.util.List<IndexRequestBuilder> builders)
                 throws java.lang.InterruptedException,
                        java.util.concurrent.ExecutionException
        Indexes the given IndexRequestBuilder instances randomly. It shuffles the given builders and either indexes them in a blocking or async fashion. This is very useful to catch problems that relate to internal document ids or index segment creations. Some features might have bug when a given document is the first or the last in a segment or if only one document is in a segment etc. This method prevents issues like this by randomizing the index layout.
        Parameters:
        forceRefresh - if true all involved indices are refreshed once the documents are indexed.
        dummyDocuments - if true some empty dummy documents may be randomly inserted into the document list and deleted once all documents are indexed. This is useful to produce deleted documents on the server side.
        maybeFlush - if true this method may randomly execute full flushes after index operations.
        builders - the documents to index.
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException

      • disableIndexBlock

        public static void disableIndexBlock​(java.lang.String index,
                                     java.lang.String block)
        Disables an index block for the specified index

      • enableIndexBlock

        public static void enableIndexBlock​(java.lang.String index,
                                    java.lang.String block)
        Enables an index block for the specified index

      • setClusterReadOnly

        public static void setClusterReadOnly​(boolean value)
        Sets or unsets the cluster read_only mode

      • clearScroll

        public void clearScroll​(java.lang.String... scrollIds)
        Clears the given scroll Ids

      • nodeSettings

        protected Settings nodeSettings​(int nodeOrdinal)
        This method is used to obtain settings for the Nth node in the cluster. Nodes in this cluster are associated with an ordinal number such that nodes can be started with specific configurations. This method might be called multiple times with the same ordinal and is expected to return the same value for each invocation. In other words subclasses must ensure this method is idempotent.

      • nodeConfigPath

        protected java.nio.file.Path nodeConfigPath​(int nodeOrdinal)

      • nodePlugins

        protected java.util.Collection<java.lang.Class<? extends Plugin>> nodePlugins()
        Returns a collection of plugins that should be loaded on each node.

      • transportClientPlugins

        protected java.util.Collection<java.lang.Class<? extends Plugin>> transportClientPlugins()
        Returns a collection of plugins that should be loaded when creating a transport client.

      • transportClientSettings

        protected Settings transportClientSettings()
        This method is used to obtain additional settings for clients created by the internal cluster. These settings will be applied on the client in addition to some randomized settings defined in the cluster. These settings will also override any other settings the internal cluster might add by default.

      • externalClusterClientSettings

        protected Settings externalClusterClientSettings()

      • ignoreExternalCluster

        protected boolean ignoreExternalCluster()

      • addMockTransportService

        protected boolean addMockTransportService()
        Iff this returns true mock transport implementations are used for the test runs. Otherwise not mock transport impls are used. The default is true.

      • addTestZenDiscovery

        protected boolean addTestZenDiscovery()
        Iff this returns true test zen discovery implementations is used for the test runs. The default is true.

      • getClientWrapper

        protected java.util.function.Function<Client,​Client> getClientWrapper()
        Returns a function that allows to wrap / filter all clients that are exposed by the test cluster. This is useful for debugging or request / response pre and post processing. It also allows to intercept all calls done by the test framework. By default this method returns an identity function Function.identity().

      • getMockPlugins

        protected java.util.Collection<java.lang.Class<? extends Plugin>> getMockPlugins()
        Return the mock plugins the cluster should use

      • getPerTestTransportClientRatio

        protected double getPerTestTransportClientRatio()
        Returns the transport client ratio from the class level annotation or via System.getProperty(String) if available. If both are not available this will return a random ratio in the interval [0..1].

      • randomRepoPath

        public java.nio.file.Path randomRepoPath()
        Returns path to a random directory that can be used to create a temporary file system repo

      • randomRepoPath

        public static java.nio.file.Path randomRepoPath​(Settings settings)
        Returns path to a random directory that can be used to create a temporary file system repo

      • assertAllShardsOnNodes

        public java.util.Set<java.lang.String> assertAllShardsOnNodes​(java.lang.String index,
                                                              java.lang.String... pattern)
        Asserts that all shards are allocated on nodes matching the given node pattern.

      • assertSortedSegments

        public void assertSortedSegments​(java.lang.String indexName,
                                 Sort expectedIndexSort)
        Asserts that all segments are sorted with the provided Sort.

      • setupTestCluster

        public final void setupTestCluster()
                            throws java.lang.Exception
        Throws:
        java.lang.Exception

      • cleanUpCluster

        public final void cleanUpCluster()
                          throws java.lang.Exception
        Throws:
        java.lang.Exception

      • afterClass

        public static void afterClass()
                       throws java.lang.Exception
        Throws:
        java.lang.Exception

      • routingKeyForShard

        protected java.lang.String routingKeyForShard​(java.lang.String index,
                                              int shard)
        Compute a routing key that will route documents to the shard-th shard of the provided index.

      • forbidPrivateIndexSettings

        protected boolean forbidPrivateIndexSettings()

      • getRestClient

        protected static RestClient getRestClient()
        Returns an instance of RestClient pointing to the current test cluster. Creates a new client if the method is invoked for the first time in the context of the current test scope. The returned client gets automatically closed when needed, it shouldn't be closed as part of tests otherwise it cannot be reused by other tests anymore.

      • resolveIndex

        public static Index resolveIndex​(java.lang.String index)

      • inFipsJvm

        public static boolean inFipsJvm()