JUnit Jupiter Causal Cluster Testcontainer extension

This is a JUnit Jupiter extension that provides a Neo4j Causal Cluster for JUnit based integration tests.

Warning

This software requires the use of the Neo4j Enterprise Edition via the official enterprise Docker Image. You need to have a valid commercial license in order to use the Enterprise Edition. Using an enterprise Docker image will require you to accept the official Enterprise license agreement.

Usage

Declare the extension as Maven dependency:

<dependency>
    <groupId>eu.michael-simons.neo4j</groupId>
    <artifactId>junit-jupiter-causal-cluster-testcontainer-extension</artifactId>
    <version>2022.1.8</version>
    <scope>test</scope>
</dependency>

You also need the Neo4j Java Driver, but I guess you already have that in your application:

<dependency>
    <groupId>org.neo4j.driver</groupId>
    <artifactId>neo4j-java-driver</artifactId>
    <version>${neo4j-java-driver.version}</version>
</dependency>

A test against a causal cluster now looks like this:

import java.net.URI;

import org.junit.jupiter.api.Test;
import org.neo4j.driver.AuthToken;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.Session;
import org.neo4j.junit.jupiter.causal_cluster.CausalCluster;import org.neo4j.junit.jupiter.causal_cluster.NeedsCausalCluster;
import org.neo4j.junit.jupiter.causal_cluster.Neo4jUri;

@NeedsCausalCluster(password = PASSWORD) // (1)
public class SimpleTest {

    static final String USERNAME = "neo4j";
    static final String PASSWORD = "cc";

    @CausalCluster // (2)
    private static URI neo4jUri;

    @Test
    void aTest() {

        AuthToken authToken = AuthTokens.basic(USERNAME, PASSWORD);
        try (
            Driver driver = GraphDatabase.driver(neo4jUri, authToken);
            Session session = driver.session();
        ) {
            session.run("MATCH (n) RETURN n").list();
        }
    }
}

1. Register the extension and set a password (Default is password)

2. Mark a field as @CausalCluster. The field can be of type URI or String and will contain a neo4j:// uri into the cluster

For more advanced test, you can also annotate a field of type List<URI> or List<String> with @CausalCluster to get all external entry points into the cluster. To retrieve the whole cluster, annotate exactly one field of type Neo4jCluster with @CausalCluster.

Custom versions

A custom version can be used by setting the appropriate attribute:

@NeedsCausalCluster(neo4jVersion = "3.5.16")
public class SimpleTest {
}

Custom images

You can also use completely custom images. Those have precedence over the version number. Make sure those are enterprise images:

@NeedsCausalCluster(customImageName = "MY_NEO4j:4711")
public class SimpleTest {
}