Java SDK - Local Web Services

Quick Start

Add the dependency, create a session in @BeforeAll, and write JUnit 5 tests. Local services start as a subprocess — your AWS SDK v2 clients are pre-configured to point at them.

1

Add dependency

              // build.gradle
repositories {
    mavenCentral()
    maven {
        name = 'GitHubPackages'
        url = uri('https://maven.pkg.github.com/local-web-services/local-web-services')
        credentials {
            username = System.getenv('GITHUB_ACTOR') ?: project.findProperty('gpr.user') ?: ''
            password = System.getenv('GITHUB_TOKEN') ?: project.findProperty('gpr.key') ?: ''
        }
    }
}

dependencies {
    testImplementation 'io.localwebservices:local-web-services-java-sdk:0.1.7'
}

// also requires local-web-services (Python) for ldk dev:
// pip install local-web-services
            

2

Write your test

              // OrderProcessorTest.java
import io.localwebservices.lws.LwsSession;
import org.junit.jupiter.api.*;
import software.amazon.awssdk.services.sfn.SfnClient;
import software.amazon.awssdk.services.sfn.model.*;

class OrderProcessorTest {

    static LwsSession session;
    static SfnClient sfnClient;
    static String stateMachineArn;

    @BeforeAll
    static void setUp() throws Exception {
        // Start ldk dev and discover resources from terraform/
        session = LwsSession.fromHcl("terraform");
        sfnClient = session.sfnClient();

        // Resolve the state machine ARN
        stateMachineArn = sfnClient
            .listStateMachines(ListStateMachinesRequest.builder().build())
            .stateMachines().get(0).stateMachineArn();
    }

    @AfterAll
    static void tearDown() {
        session.close();
    }

    @Test
    void processOrder_runsStateMachineAndReturnsResult() throws Exception {
        OrderProcessor processor = new OrderProcessor(sfnClient);

        Map result = processor.processOrder("order-001", stateMachineArn);

        assertEquals("order-001", result.get("orderId"));
    }
}
            

3

Run your tests

./gradlew test

The session starts ldk dev in @BeforeAll and waits for services to be ready. session.close() in @AfterAll stops the subprocess. LwsSession also implements AutoCloseable for try-with-resources use.

Resource Declaration

Use LwsSession.fromHcl to auto-discover resources from Terraform, or declare them explicitly with LwsSession.create.

Auto-discover from HCL

            // Reads .tf files in "terraform/", starts ldk dev,
// and pre-creates all declared resources
try (LwsSession session = LwsSession.fromHcl("terraform")) {
    SfnClient sfn = session.sfnClient();
    // state machine already exists — run your test
}
          

Explicit declaration

            SessionSpec spec = new SessionSpec()
    .withTable(new TableSpec("Orders", "id"))
    .withQueue("OrderQueue")
    .withStateMachine(
        new StateMachineSpec("OrderProcessor", definitionJson)
    );

try (LwsSession session = LwsSession.create(spec)) {
    DynamoDbClient dynamo = session.dynamoDbClient();
    SqsClient sqs = session.sqsClient();
    SfnClient sfn = session.sfnClient();
    // run your tests
}
          

LwsSession API

All factory methods block until ldk dev is ready and all resources have been created.

Factory methods

        import io.localwebservices.lws.LwsSession;
import io.localwebservices.lws.SessionSpec;
import io.localwebservices.lws.TableSpec;
import io.localwebservices.lws.StateMachineSpec;

// Auto-discover from HCL .tf files
LwsSession session = LwsSession.fromHcl("../my-terraform-project");

// Explicit resource declaration
SessionSpec spec = new SessionSpec()
    .withTable(new TableSpec("Orders", "id"))
    .withTable(new TableSpec("Products", "sku", "version"))
    .withQueue("OrderQueue")
    .withQueue("DeadLetterQueue")
    .withStateMachine(new StateMachineSpec("OrderProcessor", definitionJson));

LwsSession session = LwsSession.create(spec);

// Always close after your tests (or use try-with-resources)
session.close();
      

Client methods

        DynamoDbClient        dynamo  = session.dynamoDbClient();
SqsClient             sqs     = session.sqsClient();
S3Client              s3      = session.s3Client();
SnsClient             sns     = session.snsClient();
SfnClient             sfn     = session.sfnClient();
SsmClient             ssm     = session.ssmClient();
SecretsManagerClient  secrets = session.secretsManagerClient();

String queueUrl = session.queueUrl("OrderQueue");  // local SQS URL
int    port     = session.portFor("dynamodb");      // port number
      

Supported Services

Pre-configured clients for all major AWS services supported by Local Web Services.

DynamoDB

session.dynamoDbClient() — returns a pre-configured DynamoDbClient pointed at the local emulator. Supports all standard DynamoDB operations.

SQS

session.sqsClient() — returns a pre-configured SqsClient. Use session.queueUrl(name) to resolve local queue URLs.

S3

session.s3Client() — returns a S3Client configured for path-style access against the local S3 emulator.

Step Functions

session.sfnClient() — returns a pre-configured SfnClient. State machines declared in SessionSpec are created and ready before your test body runs.

SNS

session.snsClient() — returns a pre-configured SnsClient for publishing to topics and managing subscriptions locally.

SSM & Secrets Manager

session.ssmClient() and session.secretsManagerClient() for parameter store and secrets testing.