dynamodb-local-integration-tests

Posted on: 2019-10-08 2019-10-08
Tags: Persistence

Integration Testing with a Local DynamoDB Instance

Persistence

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.

getdocs

3043