tlrx/elasticsearch-test

elasticsearch-test, a framework that makes ElasticSearch unit testing a breeze.

Warning: Since 0.90.7, the Elasticsearch team provides a JAR file containing all the test classes. This JAR can be included in third party projects. See the pull request for more information.

Here you will find:

• a simple Java API that can be used to easily set up ElasticSearch in your unit tests
• some Java annotations that simplifies JUnit testing with ElasticSearch

Versions

Maven dependency

Add a new dependency in your Maven POM file:

<dependency>
  <groupId>com.github.tlrx</groupId>
  <artifactId>elasticsearch-test</artifactId>
  <version>1.2.1</version>
</dependency>

Using the Java API

The EsSetup class helps to start and stop a local ElasticSearch node. Then, the EsSetup.execute() method
can be used to create indices (with mappings, settings and templates support) and import test data.

The usage of EsSetup is pretty self explanatory:

import static com.github.tlrx.elasticsearch.test.EsSetup.*;

public class MyTest {

        EsSetup esSetup;

	@Before public void setUp() throws Exception {

                // Instantiates a local node & client

                esSetup = new EsSetup();

                // Clean all, and creates some indices

                esSetup.execute(

                        deleteAll(),

                        createIndex(“my_index_1”),

                        createIndex(“my_index_2”)

                                .withSettings(fromClassPath(“path/to/settings.json”))

                                .withMapping(“type1”, fromClassPath(“path/to/mapping/of/type1.json”))

                                .withData(fromClassPath(“path/to/bulk.json”)),

                        createTemplate(“template-1”)

                                .withSource(fromClassPath(“path/to/template1.json”)),

                );

        }

        @Test public void testMethod() {

                // check if the index exists

                assertTrue(esSetup.exists(“my_index_2”));

		// Index a new document

		esSetup.execute(index(“my_index_2”, “type1”, “1”).withSource(“{ \”field1\" : \“value1\” }"));

                // Count the number of documents

                Long nb = esSetup.countAll();

		// Delete a document

		esSetup.execute(delete(“my_index_2”, “type1”, “1”));

                // Clean all indices

                esSetup.execute(deleteAll());

        }

        @After public void tearDown() throws Exception {

                // This will stop and clean the local node

                esSetup.terminate();

        }	

}

Using with JUnit

Define the JUnit Runner to use in your test classes with the annotation @RunWith(ElasticsearchRunner.class) :

package com.github.tlrx.elasticsearch.samples.core;

@RunWith(ElasticsearchRunner.class)
public class VersionTest {
	...
}

Annotations

The library provides the following annotations:

@ElasticsearchNode

Used to instantiate an elasticsearch Node in a unit test class.

Simple node has default name “elasticsearch-test-node” and is part of default cluster name “elasticsearch-test-cluster”. Node is local and can hold data.

package com.github.tlrx.elasticsearch.samples.core;

@RunWith(ElasticsearchRunner.class)
public class VersionTest {

        @ElasticsearchNode
	Node node;
	
        @Test
	public void test(){
                // Use of node
	}
}

Example with custom cluster and node names, and local set to true and data set to false:

@ElasticsearchNode(name = "node3", clusterName = "fourth-cluster-name", local = true, data = false)
Node node3;

Example with custom settings:

@ElasticsearchNode(name = "node0", settings = {
	@ElasticsearchSetting(name = "http.enabled", value = "false"),
	@ElasticsearchSetting(name = "node.zone", value = "zone_one") })
Node node;

@ElasticsearchClient

Used to instantiate an elasticsearch Client from a Node. The nodeName parameter of the annotation is used to retrieve the node from which the client will be instantiated. If no nodeName is defined, a default node will be instantiated.

Example with default node:

@ElasticsearchClient
Client client;

Example with a predefined node:

@ElasticsearchNode(name = "node1")
Node node1;

@ElasticsearchClient(nodeName = "node1")
Client client1;

@ElasticsearchAdminClient

Same as ElasticsearchClient but instantiates an AdminClient.

@ElasticsearchAdminClient
AdminClient adminClient0;

@ElasticsearchNode(name = "node1")
Node node1;

@ElasticsearchAdminClient(nodeName = "node1")
AdminClient adminClient1;

@ElasticsearchTransportClient

Used to instantiate an elasticsearch TransportClient. By default the TransportClient will try to join localhost:9200.

Connect to a remote node with a TransportClient:

@ElasticsearchTransportClient(local = false, clusterName = "external",
					hostnames = {"host1", "host2"},
					ports= {9300, 9300})
	Client client;

@ElasticsearchIndex, @ElasticsearchIndexes

Used to creates one or many index before a test method. A node must be instantiated before using this annotation.

This example will create an index with default name test:

@ElasticsearchAdminClient
AdminClient adminClient;

@Test
@ElasticsearchIndex
public void test(){...}

This example will create an index “people”:

@Test
@ElasticsearchIndex(indexName = "people")
public void test(){
        ...
}

This example will create 2 indexs with settings:

@Test
@ElasticsearchIndexes(indexes = {
			@ElasticsearchIndex(indexName = "library", 
					forceCreate = true,
					settings = {
						@ElasticsearchSetting(name = "number_of_shards", value = "2"),
						@ElasticsearchSetting(name = "number_of_replicas", value = "1") }),
				@ElasticsearchIndex(indexName = "people") })
public void test(){
        ...
}

This example will create an index with settings:

@Test
@Test
@ElasticsearchIndex(indexName = "documents", settingsFile = "path/to/settings.json")
public void test() {
        ...
}

Load data from JSON file with @ElasticsearchBulkRequest

@Test
@ElasticsearchIndex(indexName = "documents", forceCreate = true)
@ElasticsearchBulkRequest(dataFile = "com/tlrx/elasticsearch/test/annotations/documents/bulk1.json")
public void test() {
   // Data from JSON file are indexed
}

@ElasticsearchMapping, @ElasticsearchMappingField and @ElasticsearchSetting

Used to define the mappings and settings of an index

This example will create 2 indexs, “people” and “library”, with a mapping for document type “book”:

@ElasticsearchNode

Node node;

@Test

@ElasticsearchIndexes(indexes = {

	@ElasticsearchIndex(indexName = “people”, settings = {

		@ElasticsearchSetting(name = “number_of_shards”, value = “2”),

		@ElasticsearchSetting(name = “number_of_replicas”, value = “1”)

	}),

	@ElasticsearchIndex(indexName = “library”,

		mappings = {

			@ElasticsearchMapping(typeName = “book”,

				properties = {

					@ElasticsearchMappingField(name = “title”, store = Store.Yes, type = Types.String),

					@ElasticsearchMappingField(name = “author”, store = Store.Yes, type = Types.String)

			})

		})

})

public void test(){

	…

}

You can also look at the unit tests for some inspiration