{"id":18636695,"url":"https://github.com/localstack/localstack-java-utils","last_synced_at":"2025-04-11T09:31:04.008Z","repository":{"id":41170673,"uuid":"242806355","full_name":"localstack/localstack-java-utils","owner":"localstack","description":"☕ Java utilities and JUnit integration for LocalStack","archived":false,"fork":false,"pushed_at":"2023-12-05T22:07:17.000Z","size":319,"stargazers_count":75,"open_issues_count":16,"forks_count":43,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-03-25T11:52:29.198Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-02-24T18:05:06.000Z","updated_at":"2024-09-05T17:07:19.000Z","dependencies_parsed_at":"2024-01-29T18:38:40.377Z","dependency_job_id":null,"html_url":"https://github.com/localstack/localstack-java-utils","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-java-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-java-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-java-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Flocalstack-java-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/localstack-java-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248368207,"owners_count":21092317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T05:31:17.292Z","updated_at":"2025-04-11T09:31:03.718Z","avatar_url":"https://github.com/localstack.png","language":"Java","readme":"[![CI](https://github.com/localstack/localstack-java-utils/actions/workflows/build.yml/badge.svg)](https://github.com/localstack/localstack-java-utils/actions/workflows/build.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/cloud.localstack/localstack-utils)](https://mvnrepository.com/artifact/cloud.localstack/localstack-utils)\n\n⚠️ Note: This repo is not currently very actively maintained. Please consider using the [Testcontainers LocalStack Java module](https://java.testcontainers.org/modules/localstack/) as a potential alternative.\n\n# LocalStack Java Utils\n\nJava utilities and JUnit integration for [LocalStack](https://github.com/localstack/localstack).\n\n## Prerequisites\n\n* Java\n* Maven\n* Docker\n* LocalStack\n\n## Usage\n\nIn order to use LocalStack with Java, this project provides a simple JUnit runner and a JUnit 5\nextension. Take a look at the example JUnit tests in `src/test/java`.\n\nBy default, the JUnit Test Runner starts LocalStack in a Docker container, for the duration of the test.\nThe container can be configured by using the `@LocalstackDockerProperties` annotation.\n\n```java\n...\nimport cloud.localstack.LocalstackTestRunner;\nimport cloud.localstack.ServiceName;\nimport cloud.localstack.TestUtils;\nimport cloud.localstack.docker.annotation.LocalstackDockerProperties;\n\n@RunWith(LocalstackTestRunner.class)\n@LocalstackDockerProperties(services = { ServiceName.S3, \"sqs\", \"kinesis\" })\npublic class MyCloudAppTest {\n\n  @Test\n  public void testLocalS3API() {\n    AmazonS3 s3 = TestUtils.getClientS3()\n    List\u003cBucket\u003e buckets = s3.listBuckets();\n    ...\n  }\n\n}\n```\n\nOr with JUnit 5:\n\n```java\n@ExtendWith(LocalstackDockerExtension.class)\n@LocalstackDockerProperties(...)\npublic class MyCloudAppTest {\n   ...\n}\n```\n\n## Installation\n\nThe LocalStack JUnit test runner is published as an artifact in Maven Central.\nSimply add the following dependency to your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecloud.localstack\u003c/groupId\u003e\n    \u003cartifactId\u003elocalstack-utils\u003c/artifactId\u003e\n    \u003cversion\u003e0.2.23\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Configuration\n\nYou can configure the Docker behaviour using the `@LocalstackDockerProperties` annotation with the following parameters:\n\n| property                    | usage                                                                                                                        | type                         | default value |\n|-----------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------|---------------|\n| `pullNewImage`              | Determines if a new image is pulled from the docker repo before the tests are run.                                           | boolean                      | `false`         |\n| `services`                  | Determines which services should be run when the localstack starts.                                                          | String[]                     | All           |\n| `imageName`                 | Use a specific image name (organisation/repo) for docker container                                                           | String                       | `localstack/localstack`  |\n| `imageTag`                  | Use a specific image tag for docker container                                                                                | String                       | `latest`        |\n| `portEdge`                  | Port number for the edge service, the main entry point for all API invocations                                               | String                       | `4566`        |\n| `portElasticSearch`         | Port number for the elasticsearch service                                                                                    | String                       | `4571`        |\n| `hostNameResolver`          | Used for determining the host name of the machine running the docker containers so that the containers can be addressed.     | IHostNameResolver            | `localhost`     |\n| `environmentVariableProvider` | Used for injecting environment variables into the container.                                                               | IEnvironmentVariableProvider | Empty Map     |\n| `bindMountProvider`         | Used bind mounting files and directories into the container, useful to run init scripts before using the container.          | IBindMountProvider           | Empty Map     |\n|  `initializationToken`      | Give a regex that will be searched in the logstream of the container, start is complete only when the token is found. Use with bindMountProvider to execute init scripts. | String | Empty String |\n| `useSingleDockerContainer`  | Whether a singleton container should be used by all test classes.                                                            | boolean | `false`     |\n\nFor more details, please refer to the README of the main LocalStack repo: https://github.com/localstack/localstack\n\n\u003e **_NOTE:_** These utilities assume docker is installed in one of the default locations (`C:\\program files\\docker\\docker\\resources\\bin\\docker.exe`,\n`C:\\program files\\docker\\docker\\resources\\docker.exe`, `usr/local/bin/docker` or `usr/bin/docker`). If your docker executable is in a\ndifferent location, then use the `DOCKER_LOCATION` environment variable to specify it.\n\n### Deprecated Configurations\n\nDue to recent changes in LocalStack (exposing all services via a single edge port, `4566`), the following configuration parameters are now deprecated in the latest version:\n\n| property                    | usage                                                                                                                        | type                         | default value |\n|-----------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------|---------------|\n| `randomizePorts`            | Determines if the container should expose the default local stack ports (4567-4583) or if it should expose randomized ports. | boolean                      | `false`         |\n\n_Note: When specifying the port in the `services` property, you cannot use `randomizePorts = true`_\n\n## Building\n\nTo build the latest version of the code via Maven:\n\n```sh\nmake build\n```\n\n### Releasing\n\nTo publish a release of the library, the \"Maven Release\" Github Action can be manually triggered in the repository, which will take the latest code on `master` branch and publish it to Maven Central.\n\n## Change Log\n\n* v0.2.23: Fix S3 endpoints to be compatible with LocalStack v2\n* v0.2.22: Fix sqs event mapping for new event format, some test fixes\n* v0.2.21: Bump version of AWS SDK v1; add AWS SDK v2 sync clients to TestUtils; add docker executable path under homebrew\n* v0.2.20: Fix extracting container logs for LocalStack startup check\n* v0.2.19: Bump version of log4j to 2.17.0 to fix further vulnerabilities related to recent CVE\n* v0.2.18: Fix for isRunning method after stopping the container; filter synthetic bridge methods during method detection for java Lambda full handler syntax; pass ADDITIONAL_MVN_ARGS to mvn javadoc command; bump version of log4j to 2.15.0 to fix CVE-2021-44228\n* v0.2.17: Fix issue with using :: to specify lambda handler which implements the RequestHandler interface, revert removal of EC2HostNameResolver annotation\n* v0.2.16: Add support for :: notation for Java Lambda handler specification, fix failing QLDB tests, fix failing tests with Jexter rules/extensions\n* v0.2.15: Fix Kinesis CBOR tests; fix project setup and classpath for SDK v1/v2 utils; fix awaiting results in tests using async clients; refactor classpath setup for v1/v2 SDKs; fall back to using edge port if port mapping cannot be determined from container\n* v0.2.14: Add ability to get handler class name through `_HANDLER` environment variable like on real AWS and Lambci environment\n* v0.2.11: Enable specification of \"platform\" when configuring container\n* v0.2.10: Add Lambda async utils for AWS SDK v2; add support for specifying bind mounts and init scripts via `@LocalstackDockerProperties`; add PowerMock integration for easy patching of AWS SDK to use local endpoints; add support for configuring the Docker image name via `@LocalstackDockerProperties`; add tests for templated emails\n* v0.2.8: Allow overwriting the port binding via environment variables\n* v0.2.7: Extend `@LocalstackDockerProperties` to include port binding\n* v0.2.6: Add new path to possible docker exe locations in Windows; add various additional tests for v1 and v2 SDKs (Kinesis, SQS, SSM \u0026 SecretsManager, ...)\n* v0.2.5: Refactor code to accommodate edge port config for all services; add CloudWatch Logs endpoint configuration\n* v0.2.2: Addition of CloudWatch Logs endpoint configuration; adjust tests to use central edge service endpoint\n* v0.2.1: Move Java sources into separate project; mark non-Docker Java `LocalstackExtension` as deprecated; update paths for Python code lookup in Docker container\n* v0.2.0: Last version still maintained in LocalStack main repo\n\n## PowerMock\n\nYou can use the PowerMock Library to call the builders default method and still get LocalStack version of the AWS clients.\n\n```java\n...\n@RunWith(PowerMockRunner.class)\n@PowerMockRunnerDelegate(LocalstackTestRunner.class)\n@LocalstackDockerProperties(services = { \"ses\" })\n@PrepareForTest({ AmazonSimpleEmailServiceClientBuilder.class, AmazonSimpleEmailServiceAsyncClientBuilder.class })\n@PowerMockIgnore({\"javax.crypto.*\", \"org.hamcrest.*\", \"javax.net.ssl.*\", \"com.sun.org.apache.xerces.*\", \"javax.xml.*\", \"org.xml.*\", \"javax.management.*\", \"javax.security.*\", \"org.w3c.*\"})\npublic class SESMessagingTest {\n....\n    @Before\n    public void mockSES() {\n        AmazonSimpleEmailService mockSes = TestUtils.getClientSES();\n        PowerMockito.mockStatic(AmazonSimpleEmailServiceClientBuilder.class);\n        when(AmazonSimpleEmailServiceClientBuilder.defaultClient()).thenReturn(mockSes);\n    }\n    @Test\n    public void testSendEmail() throws Exception {\n        AmazonSimpleEmailService client = amazonSimpleEmailServiceClientBuilder.defaultClient();\n    ....\n```\n\n## PowerMockLocalStack Utility\n\nThis utility makes easier to use PowerMock with Localstack.\n\n```java\n...\npublic class PowerMockLocalStackExampleTest extends PowerMockLocalStack{\n    private static final String TOPIC = \"topic\";\n    @Before\n    public void mock() {\n        PowerMockLocalStack.mockSNS();\n    }\n\n    @Test\n    public void testSendMessage() throws JMSException {\n        final AmazonSNS clientSNS = AmazonSNSClientBuilder.defaultClient();\n        ...\n    }\n}\n```\n\n## Acknowledgements\nI thank you [Keith Humphreys](https://gitlab.com/keithh), for showing us how to empower LocalStack with PowerMock to write tests even easier.\n\n## License\n\nThis code is released under the Apache License, Version 2.0 (see LICENSE.txt).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocalstack-java-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Flocalstack-java-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Flocalstack-java-utils/lists"}