Neo4j Module

This module helps to run Neo4j using Testcontainers.

Note that it's based on the official Docker image provided by Neo4j, Inc.

Even though the latest LTS version of Neo4j 4.4 is used in the examples of this documentation, the Testcontainers integration supports also newer 5.x images of Neo4j.

Usage example

You can start a Neo4j container instance from any Java application by using:

Neo4j container inside_block:container

Additional features

Custom password

A custom password can be provided:

Custom password inside_block:withAdminPassword

Disable authentication

Authentication can be disabled:

Disable authentication inside_block:withoutAuthentication

Random password

A random (UUID-random based) password can be set:

Random password inside_block:withRandomPassword

Neo4j-Configuration

Neo4j's Docker image needs Neo4j configuration options in a dedicated format. The container takes care of that, and you can configure the database with standard options like the following:

Neo4j configuration inside_block:neo4jConfiguration

Add custom plugins

Custom plugins, like APOC, can be copied over to the container from any classpath or host resource like this:

Plugin jar inside_block:registerPluginsJar

Whole directories work as well:

Plugin folder inside_block:registerPluginsPath

Add Neo4j Docker Labs plugins

Add any Neo4j Labs plugin from the Neo4j 4.4 Docker Labs plugin list or Neo4j 5 plugin list.

!!! note The methods withLabsPlugins(Neo4jLabsPlugin...) and withLabsPlugins(String... plugins) are deprecated. Please the method withPlugins(String... plugins).

Configure Neo4j Labs Plugins inside_block:configureLabsPlugins

Start the container with a predefined database

If you have an existing database (graph.db) you want to work with, copy it over to the container like this:

Copy database inside_block:copyDatabase

!!! note The withDatabase method will only work with Neo4j 3.5 and throw an exception if used in combination with a newer version.

Choose your Neo4j license

If you need the Neo4j enterprise license, you can declare your Neo4j container like this:

Enterprise edition inside_block:enterpriseEdition

This creates a Testcontainers based on the Docker image build with the Enterprise version of Neo4j 4.4. The call to withEnterpriseEdition adds the required environment variable that you accepted the terms and condition of the enterprise version. You accept those by adding a file named container-license-acceptance.txt to the root of your classpath containing the text neo4j:4.4-enterprise in one line.

If you are planning to run a newer Neo4j 5.x enterprise edition image, you have to manually define the proper enterprise image (e.g. neo4j:5-enterprise) and set the environment variable NEO4J_ACCEPT_LICENSE_AGREEMENT by adding .withEnv("NEO4J_ACCEPT_LICENSE_AGREEMENT", "yes") to your container definition.

You'll find more information about licensing Neo4j here: About Neo4j Licenses.

Adding this module to your project dependencies

Add the following dependency to your pom.xml/build.gradle file:

=== "Gradle" groovy testImplementation "org.testcontainers:testcontainers-neo4j:{{latest_version}}" === "Maven" xml <dependency> <groupId>org.testcontainers</groupId> <artifactId>testcontainers-neo4j</artifactId> <version>{{latest_version}}</version> <scope>test</scope> </dependency>

!!! hint Add the Neo4j Java driver if you plan to access the Testcontainers via Bolt:

=== "Gradle"
    ```groovy
    compile "org.neo4j.driver:neo4j-java-driver:4.4.13"
    ```

=== "Maven"
    ```xml
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
        <version>4.4.13</version>
    </dependency>
    ```