MENU +44 (0) 333 44 GRAPH

GraphAware Blog

Integration Testing Against Remote Neo4j

20 Aug 2015 by Adam George

Writing integration tests for your code that runs against Neo4j is simple enough when using the native API, but there’s not a great deal of help out there if you’re working in client-server mode. Making assertions about the shape of the graph can also be difficult, particularly if use cases involve more than a few nodes and relationships.

In all but the most simple of scenarios, it can be hard to see why the graph in the test database isn’t as expected, as the feedback is often as black-and-white as pass/fail so you can be looking for a proverbial needle in a haystack when trying to pinpoint the problem.


Fortunately, GraphAware have developed a neat little utility called GraphUnit that does all the hard work for you. To take advantage of it, you’ll need to make sure that the following Java dependencies are on your classpath. If you’re unlucky enough to be using Maven, you can just copy the following XML block into your POM file.


Server Mode

You can learn all about how to use GraphUnit in embedded mode by reading this blog post but what about client-server mode? If you’ve got a use case where you’re testing against the transactional Cypher endpoint or one of the REST APIs then you’ll need to consider this. If you have unmanaged extensions then it can also be useful for verifying that these work correctly in their natural environment.

JUnit Rules

Since JUnit 4.9, Rules have been available for instrumenting your test cases. These offer a much more flexible approach than custom runners and abstract base classes and bootstrapping Neo4j is a great use for them.

	public class Neo4jIntegrationTestRule implements TestRule {

		private final WrappingNeoServerBootstrapper bootstrapper;
		private final GraphDatabaseService database;

		public Neo4jIntegrationTestRule() {
			this.database = new TestGraphDatabaseFactory().newImpermanentDatabase();

			ServerConfigurator configurator = new ServerConfigurator((GraphDatabaseAPI) this.database);
			configurator.configuration().addProperty(Configurator.WEBSERVER_PORT_PROPERTY_KEY, 7890); // pick any port you like
			this.bootstrapper = new WrappingNeoServerBootstrapper((GraphDatabaseAPI) this.database, configurator);

		public Statement apply(final Statement baseStatement, Description description) {

			return new Statement() {
				public void evaluate() throws Throwable {
					try {
						if (database.isAvailable(1000)) {
						} else {"Database was shut down or didn't become available within 1s");
					} finally {

		public GraphDatabaseService getGraphDatabaseService() {
			return this.database;


The Statement passed to the apply method represents the JUnit test to be run. Calling baseStatement.evaluate() actually runs the test, hence all the code around it is used to provide the infrastructure needed for test execution. The code above starts a Neo4j database running on local TCP port 7890, checks that the database is available and then runs the test, making sure to stop the bootstrapper again at the end of the test to shut the database down.

You can include it in your test case thus:

	public class ArbitraryIntegrationTest {

		public final Neo4jIntegrationTestRule neo4jRule = new Neo4jIntegrationTestRule();

		public void arbitraryTestMethod() {

			// some code that's supposed to create a person node in the database running on http://localhost:7890

			GraphUnit.assertSameGraph("CREATE (:Person {name:'Sheila'})", neo4jRule.getGraphDatabaseService());


The @Rule annotation needs to be applied to the field for JUnit to use it. Note that the field must be public because of the way in which JUnit reads it when setting up your test harness. The rule’s apply(...) method gets called for each test method when used in this way.

There’s no need for duplicating set-up or tear-down methods in all of your test cases if you use this approach. Just including the rule as shown above will handle everything and expose the underlying graph database service for use with the GraphUnit framework as well.

You can also annotate the rule field with @ClassRule and declare it public static if you want its apply(...) method to be called just once for the whole test class. This is often a good idea because it starts and stops the database once for the entire test run and can save a lot of time if you have more than a few test methods. Of course, by not recreating the database each time for every test you run the risk of having data lying around from previous test methods, so it’s often a good idea to declare an @Before method in your test case to delete the contents of your database.

Share this blog post:

+1 LinkedIn
comments powered by Disqus



Posts by tag

Neo4j Conference NoSQL Czech Beginner Analytics Advanced Modelling Meetup GraphAware Intermediate GraphUnit Testing Transactions Cypher Events Spring SDN OGM Recommendations Search Elasticsearch Security Enterprise NLP HCM PeopleAnalytics HR HRTech Framework Internationalization Localization

Search this blog