-
-
Notifications
You must be signed in to change notification settings - Fork 487
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* chore: add localstack basic example Run "go run . --name localstack --image "localstack/localstack:0.11.2" --title LocalStack" * chore: add wait for log * chore: add Docker socket binding * chore: support defining legacy mode * chore: support passing services and configuring them * chore: simplify the creation of a localstack container request It will allow users not to pass the legacy mode everywhere. Instead, it's defined in the initial request, and consumed downstream * chore: support configuring the AWS region * chore: expose localstack container * chore: support for retrieving the endpoint of a given service * chore: store enabled services in the localstack container * chore: store the region in the localstack container * chore: apply default region when needed * chore: support passing version and legacyMode as functional options * chore: support for overriding the container request with a functional option * chore: remove useless method for retrieving the internal endpoint of a service * chore: simplify unit tests * chore: create aws session using v1 * chore: add S3 tests * chore: rename start localstack function * chore: define default functions as vars * chore: add tests for legacy mode * chore: move the Session code to the tests We want to et the user define how to get the Session * docs: use S3 in the docs * fix: read the expected daemon host from the provider * chore: move v1 tests to its own test package * feat: add example test for S3 using v2 * chore: store localstack credentials in a struct * feat: create a functional opt for passing the AWS credentials * chore: define defaults for the AWS credentials * chore: include a test for overriding the image * chore: remove withCredentials Set them up using the override, as it's as simple as adding the right env vars * chore: remove withRegion Set it up using the override, as it's as simple as adding the right env var * chore: remove withVersion Set them up using the override, as it's as simple as setting the req.Image * chore: rename configure method * chore: reorder container configuration 1. merge the override request 2. set up the functional opts 3. configure Docker host * chore: move to types * chor: export structs * docs: document exported functions * docs: document how to create localstack container * docs: reorder * docs: document containerRequest override * docs: document the container functional opts * chore: be more explicit in comment Co-authored-by: Eddú Meléndez Gonzales <eddu.melendez@gmail.com> * chore: convert into real module * chore: remove support for legacy mode * chore: move tests * fix: update module paths * fix: update tests after moving an example to modules * chore: bump default version to 1.3.1 * chore: remove Port from the Service struct If the user wants to use the legacy mode, then they should build the environment accordingly (e.g. SERVICES env var) * fix: wrong relative path to the docs * chore: remove any code to Services We'll delegate it to the user, using the localstack env vars * chore: adjust unit tests * docs: include tests * chore: use waitFor HTTP health * chore: bump to latest version * chore: go mod examples * chore: rename GH action workflow file --------- Co-authored-by: Eddú Meléndez Gonzales <eddu.melendez@gmail.com>
- Loading branch information
1 parent
8b88363
commit 0779549
Showing
45 changed files
with
1,408 additions
and
108 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| name: LocalStack module pipeline | ||
|
|
||
| on: [push, pull_request] | ||
|
|
||
| concurrency: | ||
| group: ${{ github.workflow }}-${{ github.head_ref || github.sha }} | ||
| cancel-in-progress: true | ||
|
|
||
| jobs: | ||
| test-localstack: | ||
| strategy: | ||
| matrix: | ||
| go-version: [1.18.x, 1.x] | ||
| runs-on: "ubuntu-latest" | ||
| steps: | ||
|
|
||
| - name: Set up Go | ||
| uses: actions/setup-go@v3 | ||
| with: | ||
| go-version: ${{ matrix.go-version }} | ||
| id: go | ||
|
|
||
| - name: Check out code into the Go module directory | ||
| uses: actions/checkout@v3 | ||
|
|
||
| - name: modVerify | ||
| working-directory: ./modules/localstack | ||
| run: go mod verify | ||
|
|
||
| - name: modTidy | ||
| working-directory: ./modules/localstack | ||
| run: make tools-tidy | ||
|
|
||
| - name: gotestsum | ||
| working-directory: ./modules/localstack | ||
| run: make test-unit | ||
|
|
||
| - name: Run checker | ||
| run: | | ||
| ./scripts/check_environment.sh | ||
| - name: Test Summary | ||
| uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7 | ||
| with: | ||
| paths: "**/TEST-localstack*.xml" | ||
| if: always() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,107 @@ | ||
| # LocalStack | ||
|
|
||
| The Testcontainers module for [LocalStack](http://localstack.cloud/) is _"a fully functional local AWS cloud stack"_, to develop and test your cloud and serverless apps without actually using the cloud. | ||
|
|
||
| ## Adding this module to your project dependencies | ||
|
|
||
| Please run the following command to add the LocalStack module to your Go dependencies: | ||
|
|
||
| ``` | ||
| go get github.com/testcontainers/testcontainers-go/modules/localstack | ||
| ``` | ||
|
|
||
| ## Usage example | ||
|
|
||
| Running LocalStack as a stand-in for multiple AWS services during a test: | ||
|
|
||
| <!--codeinclude--> | ||
| [Creating a LocalStack container](../../modules/localstack/v1/s3_test.go) inside_block:localStackCreateContainer | ||
| <!--/codeinclude--> | ||
|
|
||
| Environment variables listed in [Localstack's README](https://github.com/localstack/localstack#configurations) may be used to customize Localstack's configuration. | ||
| Use the `OverrideContainerRequest` option when creating the `LocalStackContainer` to apply configuration settings. | ||
|
|
||
| ## Creating a client using the AWS SDK for Go | ||
|
|
||
| ### Version 1 | ||
|
|
||
| <!--codeinclude--> | ||
| [Test for a LocalStack container, usinv AWS SDK v1](../../modules/localstack/v1/s3_test.go) inside_block:awsSDKClientV1 | ||
| <!--/codeinclude--> | ||
|
|
||
| For further reference on the SDK v1, please check out the AWS docs [here](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html). | ||
|
|
||
| ### Version 2 | ||
|
|
||
| <!--codeinclude--> | ||
| [Test for a LocalStack container, usinv AWS SDK v2](../../modules/localstack/v2/s3_test.go) inside_block:awsSDKClientV2 | ||
| <!--/codeinclude--> | ||
|
|
||
| For further reference on the SDK v2, please check out the AWS docs [here](https://aws.github.io/aws-sdk-go-v2/docs/getting-started) | ||
|
|
||
| ## `HOSTNAME_EXTERNAL` and hostname-sensitive services | ||
|
|
||
| Some Localstack APIs, such as SQS, require the container to be aware of the hostname that it is accessible on - for example, for construction of queue URLs in responses. | ||
|
|
||
| Testcontainers will inform Localstack of the best hostname automatically, using the `HOSTNAME_EXTERNAL` environment variable: | ||
|
|
||
| * when running the Localstack container directly without a custom network defined, it is expected that all calls to the container will be from the test host. As such, the container address will be used (typically localhost or the address where the Docker daemon is running). | ||
|
|
||
| <!--codeinclude--> | ||
| [Localstack container running without a custom network](../../modules/localstack/localstack_test.go) inside_block:withoutNetwork | ||
| <!--/codeinclude--> | ||
|
|
||
| * when running the Localstack container [with a custom network defined](/features/networking/#advanced-networking), it is expected that all calls to the container will be **from other containers on that network**. `HOSTNAME_EXTERNAL` will be set to the *last* network alias that has been configured for the Localstack container. | ||
|
|
||
| <!--codeinclude--> | ||
| [Localstack container running with a custom network](../../modules/localstack/localstack_test.go) inside_block:withNetwork | ||
| <!--/codeinclude--> | ||
|
|
||
| * Other usage scenarios, such as where the Localstack container is used from both the test host and containers on a custom network are not automatically supported. If you have this use case, you should set `HOSTNAME_EXTERNAL` manually. | ||
|
|
||
| ## Module reference | ||
|
|
||
| The LocalStack module exposes one single function to create the LocalStack container, and this function receives two parameters: | ||
|
|
||
| ```golang | ||
| func StartContainer(ctx context.Context, overrideReq OverrideContainerRequestOption) (*LocalStackContainer, error) | ||
| ``` | ||
|
|
||
| - `context.Context` | ||
| - `OverrideContainerRequestOption` | ||
|
|
||
| ### OverrideContainerRequestOption | ||
|
|
||
| The `OverrideContainerRequestOption` functional option represents a way to override the default LocalStack container request: | ||
|
|
||
| <!--codeinclude--> | ||
| [Default container request](../../modules/localstack/localstack.go) inside_block:defaultContainerRequest | ||
| <!--/codeinclude--> | ||
|
|
||
| With simply passing your own instance of an `OverrideContainerRequestOption` type to the `StartContainer` function, you'll be able to configure the LocalStack container with your own needs, as this new container request will be merged with the original one. | ||
|
|
||
| In the following example you check how it's possible to set certain environment variables that are needed by the tests, the most important of them the AWS services you want to use. Besides, the container runs in a separate Docker network with an alias: | ||
|
|
||
| <!--codeinclude--> | ||
| [Overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:withNetwork | ||
| <!--/codeinclude--> | ||
|
|
||
| If you do not need to override the container request, you can pass `nil` or the `NoopOverrideContainerRequest` instance, which is exposed as a helper for this reason. | ||
|
|
||
| <!--codeinclude--> | ||
| [Skip overriding the default container request](../../modules/localstack/localstack_test.go) inside_block:noopOverrideContainerRequest | ||
| <!--/codeinclude--> | ||
|
|
||
| ## Testing the module | ||
|
|
||
| The module includes unit and integration tests that can be run from its source code. To run the tests please execute the following command: | ||
|
|
||
| ``` | ||
| cd modules/localstack | ||
| make test | ||
| ``` | ||
|
|
||
| !!!info | ||
|
|
||
| At this moment, the tests for the module include tests for the S3 service, only. They live in two different Go packages of the LocalStack module, | ||
| `v1` and `v2`, where it'll be easier to add more examples for the rest of services. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.