Skip to content

Neo4j Module

This module helps running Neo4j using Testcontainers.

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

Usage example

Declare your Testcontainers as a @ClassRule or @Rule in a JUnit 4 test or as static or member attribute of a JUnit 5 test annotated with @Container as you would with other Testcontainers. You can either use call getBoltUrl() or getHttpUrl() on the Neo4j container. getBoltUrl() is meant to be used with one of the official Bolt drivers while getHttpUrl() gives you the HTTP-address of the transactional HTTP endpoint. On the JVM you would most likely use the Java driver.

The following example uses the JUnit 5 extension @Testcontainers and demonstrates both the usage of the Java Driver and the REST endpoint:

class Neo4jExampleTest {

    private static Neo4jContainer<?> neo4jContainer =
        new Neo4jContainer<>(DockerImageName.parse("neo4j:4.4"))
        .withAdminPassword(null); // Disable password

    void testSomethingUsingBolt() {

        // Retrieve the Bolt URL from the container
        String boltUrl = neo4jContainer.getBoltUrl();
        try (
            Driver driver = GraphDatabase.driver(boltUrl, AuthTokens.none());
            Session session = driver.session()
        ) {
            long one ="RETURN 1", Collections.emptyMap()).next().get(0).asLong();
        } catch (Exception e) {

    void testSomethingUsingHttp() throws IOException {

        // Retrieve the HTTP URL from the container
        String httpUrl = neo4jContainer.getHttpUrl();

        URL url = new URL(httpUrl + "/db/data/transaction/commit");
        HttpURLConnection con = (HttpURLConnection) url.openConnection();

        con.setRequestProperty("Content-Type", "application/json");

        try (Writer out = new OutputStreamWriter(con.getOutputStream())) {
            out.write("{\"statements\":[{\"statement\":\"RETURN 1\"}]}");

        try (BufferedReader buffer = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
            String expectedResponse =
            String response = buffer.lines().collect(Collectors.joining("\n"));

You are not limited to Unit tests and can of course use an instance of the Neo4j Testcontainers in vanilla Java code as well.

Additional features

Disable authentication

Authentication can be disabled:

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:4.4")


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:

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:4.4")
    .withNeo4jConfig("", "apoc.*,algo.*")
    .withNeo4jConfig("dbms.tx_log.rotation.size", "42M");

Add custom plugins

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

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:4.4")

Whole directories work as well:

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:4.4")

Add Neo4j Docker Labs plugins

Add any Neo4j Labs plugin from the Neo4j Docker Labs plugin list.


At the moment only the plugins available from the list Neo4j Docker 4.4 are supported by type. If you want to register another supported Neo4j Labs plugin, you have to add it manually by using the method withLabsPlugins(String... neo4jLabsPlugins). Please refer to the list of supported Docker image plugins.

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:4.4")
    .withLabsPlugins(Neo4jLabsPlugin.APOC, Neo4jLabsPlugin.BLOOM);

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:

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:3.5.30")


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:

Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:4.4")

This creates a Testcontainers based on the Docker image build with the Enterprise version of Neo4j. 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:3.5.0-enterprise in one line. 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:

testImplementation "org.testcontainers:neo4j:1.17.4"


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

compile "org.neo4j.driver:neo4j-java-driver:4.4.3"