LocalStack Testing Tools

Tools to simplify application testing

Covered Topics

• JVM Testing Utils

JVM Testing Utils

LocalStack provides Java Utils library that integrates with JUnit and provides LocalStack-targeted AWS Clients.

Installation

• Maven
• Gradle

<dependency>
    <groupId>cloud.localstack</groupId>
    <artifactId>localstack-utils</artifactId>
    <version>0.2.15</version>
    <scope>test</scope>
</dependency>

testImplementation group: 'cloud.localstack', name: 'localstack-utils', version: '0.2.15'

Usage

• Java
• Kotlin

...
import cloud.localstack.LocalstackTestRunner;
import cloud.localstack.ServiceName;
import cloud.localstack.TestUtils;
import cloud.localstack.docker.annotation.LocalstackDockerProperties;
@RunWith(LocalstackTestRunner.class)
@LocalstackDockerProperties(services = { ServiceName.S3, "sqs", "kinesis" })
public class MyCloudAppTest {
  @Test
  public void testLocalS3API() {
    AmazonS3 s3 = TestUtils.getClientS3()
    List<Bucket> buckets = s3.listBuckets();
    ...
  }
}

...
import cloud.localstack.LocalstackTestRunner
import cloud.localstack.ServiceName
import cloud.localstack.TestUtils
import cloud.localstack.docker.annotation.LocalstackDockerProperties
@RunWith(LocalstackTestRunner::class)
@LocalstackDockerProperties(services = [ServiceName.S3, "sqs", "kinesis"])
public class MyCloudAppTest {
  @Test
  fun testLocalS3API() {
    val s3 = TestUtils.getClientS3()
    val buckets = s3.listBuckets();
    ...
  }
}

Powermock

You can use the PowerMock Library to call the builders default method and still get LocalStack version of the AWS clients.

...
@RunWith(PowerMockRunner.class)
@PowerMockRunnerDelegate(LocalstackTestRunner.class)
@LocalstackDockerProperties(services = { "ses" })
@PrepareForTest({ AmazonSimpleEmailServiceClientBuilder.class, AmazonSimpleEmailServiceAsyncClientBuilder.class })
@PowerMockIgnore({"javax.crypto.*", "org.hamcrest.*", "javax.net.ssl.*", "com.sun.org.apache.xerces.*", "javax.xml.*", "org.xml.*", "javax.management.*", "javax.security.*", "org.w3c.*"})
public class SESMessagingTest {
....
    @Before
    public void mockSES() {
        AmazonSimpleEmailService mockSes = TestUtils.getClientSES();
        PowerMockito.mockStatic(AmazonSimpleEmailServiceClientBuilder.class);
        when(AmazonSimpleEmailServiceClientBuilder.defaultClient()).thenReturn(mockSes);
    }
    @Test
    public void testSendEmail() throws Exception {
        AmazonSimpleEmailService client = amazonSimpleEmailServiceClientBuilder.defaultClient();
    ....

PowerMockLocalStack Utility

This utility makes easier to use PowerMock with LocalStack.

...
public class PowerMockLocalStackExampleTest extends PowerMockLocalStack{
    private static final String TOPIC = "topic";
    @Before
    public void mock() {
        PowerMockLocalStack.mockSNS();
    }
    @Test
    public void testSendMessage() throws JMSException {
        final AmazonSNS clientSNS = AmazonSNSClientBuilder.defaultClient();
        ...
    }
}

Last modified May 17, 2022: fix capitalization of LocalStack in affected files (#157) (6206611c)