elasticsearch-test, a framework that makes elasticsearch unit testing a breeze.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
src Fix unit test Mar 26, 2014
.gitignore Add gitignore file Nov 6, 2012
README.textile Update to 1.2.1 Jun 12, 2014
pom.xml nudged ElasticSearch version to 1.2.2 Jul 23, 2014


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


elasticsearch-test ElasticSearch
master (1.2.2-SNAPSHOT) 1.2.2
1.2.1 1.2.1
1.1.0 1.1.0
0.90.6 0.90.6
0.90.5 0.90.5
0.0.10 0.90.3
0.0.9 0.90.1
0.0.8 0.90.0.Beta1
0.0.7 0.20.1
0.0.6 0.20.0
0.0.5 0.19.11
0.0.4 0.19.8
0.0.3 0.19.7
0.0.2 0.19.4
0.0.1 0.19.4

Maven dependency

Add a new dependency in your Maven POM file:


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
.withMapping(“type1”, fromClassPath(“path/to/mapping/of/type1.json”))
@Test public void testMethod() {
// check if the index exists
// 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
@After public void tearDown() throws Exception {
// This will stop and clean the local node

More usages can be found in BasicTest.java

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;

public class VersionTest {


The library provides the following annotations:

@ElasticsearchNode Instantiate an elasticsearch Node
@ElasticsearchClient Instantiate an elasticsearch Client
@ElasticsearchAdminClient Instantiate an elasticsearch AdminClient
@ElasticsearchTransportClient Instantiate an elasticsearch TransportClient
@ElasticsearchIndexes Used to create multiple index
@ElasticsearchIndex Creates an index
@ElasticsearchMapping Defines a mapping for an index and a document type
@ElasticsearchMappingField Defines field properties in a mapping
@ElasticsearchSetting Defines settings (at node or index level)
@ElasticsearchBulkRequest Used to import data
@ElasticsearchAnalysis Used to define analysis settings of an ElasticsearchIndex
@ElasticsearchAnalyzer Used to define an analyzer
@ElasticsearchFilter Used to define an analysis filter


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;

public class VersionTest {

	Node node;
	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;


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:

Client client;

Example with a predefined node:

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

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


Same as ElasticsearchClient but instantiates an AdminClient.

AdminClient adminClient0;

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

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


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:

AdminClient adminClient;

public void test(){...}

This example will create an index “people”:

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

This example will create 2 indexs with settings:

@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:

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

Load data from JSON file with @ElasticsearchBulkRequest

@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”:

Node node;

@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