Integration Testing with a Local DynamoDB Instance

1. Overview

If we develop an application which uses Amazon’s DynamoDB, it can be tricky to develop integration tests without having a local instance.

In this tutorial, we’ll explore multiple ways of configuring, starting and stopping a local DynamoDB for our integration tests.

This tutorial also complements our existing DynamoDB article.

2. Configuration

2.1. Maven Setup

DynamoDB Local is a tool developed by Amazon which supports all the DynamoDB APIs. It doesn’t directly manipulate the actual DynamoDB tables in production but performs it locally instead.

First, we add the DynamoDB Local dependency to the list of dependencies in our Maven configuration:

<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>DynamoDBLocal</artifactId>
    <version>1.11.86</version>
    <scope>test</scope>
</dependency>

Next, we also need to add the Amazon DynamoDB repository, since the dependency doesn’t exist in the Maven Central repository.

We can select the closest Amazon server to our current IP address geolocation:

<repository>
    <id>dynamodb-local</id>
    <name>DynamoDB Local Release Repository</name>
    <url>https://s3-us-west-2.amazonaws.com/dynamodb-local/release</url>
</repository>

2.2. Add SQLite4Java Dependency

The DynamoDB Local uses the SQLite4Java library internally; thus, we also need to include the library files when we run the test. The SQLite4Java library files depend on the environment where the test is running, but Maven can pull them transitively once we declare the DynamoDBLocal dependency.

Next, we need to add a new build step to copy native libraries into a specific folder that we’ll define in the JVM system property later on.

Let’s copy the transitively-pulled SQLite4Java library files to a folder named native-libs:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>2.10</version>
    <executions>
        <execution>
            <id>copy</id>
            <phase>test-compile</phase>
            <goals>
                <goal>copy-dependencies</goal>
            </goals>
            <configuration>
                <includeScope>test</includeScope>
                <includeTypes>so,dll,dylib</includeTypes>
                <outputDirectory>${project.basedir}/native-libs</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

2.3. Set the SQLite4Java System Property

Now, we’ll reference the previously created folder (where the SQLite4Java libraries are located), using a JVM system property named sqlite4java.library.path:

System.setProperty("sqlite4java.library.path", "native-libs");

In order to successfully run the test later, it’s mandatory to have all the SQLite4Java libraries in the folder defined by the sqlite4java.library.path system property. We must run Maven test-compile (mvn test-compile) at least once to fulfill the prerequisite.

3. Setting up the Test Database’s Lifecycle

We can define the code to create and start the local DynamoDB server in a setup method annotated with @BeforeClass; and, symmetrically, stop the server in a teardown method annotated with @AfterClass.

In the following example, we’ll start up the local DynamoDB server on port 8000 and make sure it’s stopped again after running our tests:

public class ProductInfoDAOIntegrationTest {
    private static DynamoDBProxyServer server;

    @BeforeClass
    public static void setupClass() throws Exception {
        System.setProperty("sqlite4java.library.path", "native-libs");
        String port = "8000";
        server = ServerRunner.createServerFromCommandLineArgs(
          new String[]{"-inMemory", "-port", port});
        server.start();
        //...
    }

    @AfterClass
    public static void teardownClass() throws Exception {
        server.stop();
    }

    //...
}

We can also run the local DynamoDB server on any available port instead of a fixed port using java.net.ServerSocket. In this case, we must also configure the test to set the endpoint to the correct DynamoDB port:

public String getAvailablePort() throws IOException {
    ServerSocket serverSocket = new ServerSocket(0);
    return String.valueOf(serverSocket.getLocalPort());
}

4. Alternative Approach: Using @ClassRule

We can wrap the previous logic in a JUnit rule which performs the same action:

public class LocalDbCreationRule extends ExternalResource {
    private DynamoDBProxyServer server;

    public LocalDbCreationRule() {
        System.setProperty("sqlite4java.library.path", "native-libs");
    }

    @Override
    protected void before() throws Exception {
        String port = "8000";
        server = ServerRunner.createServerFromCommandLineArgs(
          new String[]{"-inMemory", "-port", port});
        server.start();
    }

    @Override
    protected void after() {
        this.stopUnchecked(server);
    }

    protected void stopUnchecked(DynamoDBProxyServer dynamoDbServer) {
        try {
            dynamoDbServer.stop();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }    
    }
}

To use our custom rule, we’ll have to create and annotate an instance with @ClassRule as shown below. Again, the test will create and start the local DynamoDB server prior to the test class initialization.

Note that the access modifier of the test rule must be public in order to run the test:

public class ProductInfoRepositoryIntegrationTest {
    @ClassRule
    public static LocalDbCreationRule dynamoDB = new LocalDbCreationRule();

    //...
}

Before wrapping up, a very quick note – since DynamoDB Local uses the SQLite database internally, its performance doesn’t reflect the real performance in production.

5. Conclusion

In this article, we’ve seen how to setup and configure DynamoDB Local to run integration tests.

As always, the source code and the configuration example can be found over on Github.