Skip to content

Getting Started

This guide walks you through creating your first integration test with CloudStub.

1. Add dependencies

CloudStub is modular. Add cloudstub-testing (it brings in cloudstub-core and the JUnit extension), plus only the AWS service modules your project needs.

dependencies {
    testImplementation 'io.github.cloudstub:cloudstub-testing:0.1.0'

    // Add one or more service modules
    testImplementation 'io.github.cloudstub:cloudstub-sqs:0.1.0'
    testImplementation 'io.github.cloudstub:cloudstub-secretsmanager:0.1.0'

    // AWS SDK v2 clients for the services you use
    testImplementation 'software.amazon.awssdk:sqs:2.25.70'
    testImplementation 'software.amazon.awssdk:secretsmanager:2.25.70'
}

<dependencies>
    <dependency>
        <groupId>io.github.cloudstub</groupId>
        <artifactId>cloudstub-testing</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.github.cloudstub</groupId>
        <artifactId>cloudstub-sqs</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>sqs</artifactId>
        <version>2.25.70</version>
        <scope>test</scope>
    </dependency>
</dependencies>

2. Write your first test

Annotate the test class with @ExtendWith(CloudStubExtension.class). CloudStub starts before the first test, stops after the last, and sets aws.endpoint-url so the AWS SDK routes all traffic to the embedded server automatically.

import io.cloudstub.junit.CloudStubExtension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import software.amazon.awssdk.auth.credentials.AnonymousCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.sqs.SqsClient;

import java.net.URI;

import static org.junit.jupiter.api.Assertions.*;

@ExtendWith(CloudStubExtension.class) // (1)!
class OrderServiceTest {

    @Test
    void placingAnOrderPublishesIt() {
        SqsClient sqs = SqsClient.builder()
            .endpointOverride(URI.create(System.getProperty("aws.endpoint-url"))) // (2)!
            .credentialsProvider(AnonymousCredentialsProvider.create())
            .region(Region.US_EAST_1)
            .build();
        String queueUrl = sqs.createQueue(b -> b.queueName("orders")).queueUrl();

        new OrderService(sqs, queueUrl).placeOrder("sku-42");

        String body = sqs.receiveMessage(b -> b.queueUrl(queueUrl)).messages().get(0).body();
        assertTrue(body.contains("sku-42")); // (3)!
    }
}
  1. Starts CloudStub before the first test and stops it after the last. Service modules on the classpath are discovered automatically via ServiceLoader, with no registration required.
  2. CloudStub sets aws.endpoint-url to http://localhost:<port> before any test runs. The SDK reads it automatically.
  3. Send and receive are state-backed, so you assert on what your code actually did (the order reached the queue), not on the mock returning a value.

3. Run it

./gradlew test

CloudStub starts in under 200 ms. No containers, no credentials, no network.

Next steps