elasticsearch-test
elasticsearch-test copied to clipboard
tlrx
elasticsearch-test, a framework that makes elasticsearch unit testing a breeze.
elasticsearch-test, a framework that makes "ElasticSearch":http://www.elasticsearch.org/ 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":https://github.com/elasticsearch/elasticsearch/pull/4126 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
h3. Versions
|. 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 |
h3. Maven dependency
Add a new dependency in your Maven POM file:
bc.
h2. 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();
}
}More usages can be found in "BasicTest.java":https://github.com/tlrx/elasticsearch-test/blob/master/src/test/java/com/github/tlrx/elasticsearch/test/BasicTest.java
h2. 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 {
...
}
h3. Annotations
The library provides the following annotations:
|. Annotation |. | | @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 |
h3. @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:
bc. @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;
h3. @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:
bc. @ElasticsearchClient Client client;
Example with a predefined node:
@ElasticsearchNode(name = "node1") Node node1; @ElasticsearchClient(nodeName = "node1") Client client1;
h3. @ElasticsearchAdminClient
Same as @ElasticsearchClient@ but instantiates an @AdminClient@.
@ElasticsearchAdminClient AdminClient adminClient0; @ElasticsearchNode(name = "node1") Node node1; @ElasticsearchAdminClient(nodeName = "node1") AdminClient adminClient1;
h3. @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;
h3. @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() {
...
}
h3. 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
}
h3. @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":https://github.com/tlrx/elasticsearch-test/tree/master/src/test/java/com/github/tlrx/elasticsearch
tlrx