This project is no longer maintained. We recommend using Testcontainers instead: https://www.testcontainers.org/modules/elasticsearch/

embedded-elasticsearch

Small utility for creating integration tests that use Elasticsearch. Instead of using Node it downloads Elasticsearch in specified version and starts it in a separate process. It also allows you to install required plugins which is not possible when using NodeBuilder. Utility was tested with 1.x, 2.x, 5.x and 6.x versions of Elasticsearch.

Introduction

All you need to do to use this tool is create EmbeddedElastic instance. To do so, use provided builder:

final embeddedElastic = EmbeddedElastic.builder()
        .withElasticVersion("5.0.0")
        .withSetting(PopularProperties.TRANSPORT_TCP_PORT, 9350)
        .withSetting(PopularProperties.CLUSTER_NAME, "my_cluster")
        .withPlugin("analysis-stempel")
        .withIndex("cars", IndexSettings.builder()
            .withType("car", getSystemResourceAsStream("car-mapping.json"))
            .build())
        .withIndex("books", IndexSettings.builder()
            .withType(PAPER_BOOK_INDEX_TYPE, getSystemResourceAsStream("paper-book-mapping.json"))
            .withType("audio_book", getSystemResourceAsStream("audio-book-mapping.json"))
            .withSettings(getSystemResourceAsStream("elastic-settings.json"))
            .build())
        .build()
        .start()

When you are done with creating it, you can start it real simple:

embeddedElastic.start()

And that's all, you can connect to your embedded-elastic instance on specified port and use it in your tests.

Available builder options

Available IndexSettings.Builder options

Availabe JavaHomeOption options

Available operations

EmbeddedElastic provides following operations:

Example

If you want to see example, look at this spec: pl.allegro.tech.search.embeddedelasticsearch.EmbeddedElasticSpec

Dependency

To start using embedded-elasticsearch in your project add it as a test dependency:

Gradle:

testCompile 'pl.allegro.tech:embedded-elasticsearch:2.7.0'

Maven:

<dependency>
    <groupId>pl.allegro.tech</groupId>
    <artifactId>embedded-elasticsearch</artifactId>
    <version>2.7.0</version>
    <scope>test</scope>
</dependency>

SBT:

libraryDependencies ++= Seq("pl.allegro.tech" % "embedded-elasticsearch" % "2.7.0" % "test")

Known problems

If you build your project on Travis, you may have problems with OOM errors when using default settings. You can change Elasticsearch memory settings using withEsJavaOpts method. Example (from spec pl.allegro.tech.embeddedelasticsearch.EmbeddedElasticSpec):

    static EmbeddedElastic embeddedElastic = EmbeddedElastic.builder()
            .withElasticVersion(ELASTIC_VERSION)
            .withSetting(TRANSPORT_TCP_PORT, TRANSPORT_TCP_PORT_VALUE)
            .withSetting(CLUSTER_NAME, CLUSTER_NAME_VALUE)
            .withEsJavaOpts("-Xms128m -Xmx512m")
            .withIndex(CARS_INDEX_NAME, CARS_INDEX)
            .withIndex(BOOKS_INDEX_NAME, BOOKS_INDEX)
            .withStartTimeout(1, MINUTES)
            .build()
            .start()

Running more then one Elasticsearch instance

There are cases where you might want to run more than one Elasticsearch instance e.g.:

• running tests of one project in parallel (e.g. using gradle --parallel or mvn -T1C)
• running tests of different projects on the same physical mashine (e.g. Jenkins jobs running on the same server)
• running integration tests which require more than one Elasticsearch instance

In such situations you should use distinct values for following settings for each instance:

• withSetting(PopularProperties.TRANSPORT_TCP_PORT, ...)
• withSetting(PopularProperties.HTTP_PORT, ...)
• withInstallationDirectory(...)

With such configuration embedded-elasticsearch will redownload elasticsearch installation package for every distinct installation directory. To avoid this behavior and reuse downloaded installation package you should set common location of downloaded files with withDownloadDirectory(...) for every embedded-elasticsearch configuration.

License

embedded-elasticsearch is published under Apache License 2.0.