Repository: localstack/localstack
Pull request: Improve documentation around @LocalstackDockerProperties
Fixes #1324.


Problem statement:
Docker example with junit5 throws java.lang.IllegalStateException
looks like this snippet for Junit5 (have not tested it with Junit4) is not working with `lambda` and `stepfunctions`

```
@ExtendWith(LocalstackDockerExtension.class)
@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
public class MyDockerCloudAppTest {
   ...
}
```

I get the error
```
java.lang.IllegalStateException: Service to port mapping has not been determined yet.

	at cloud.localstack.docker.LocalstackDocker.endpointForService(LocalstackDocker.java:183)
	at cloud.localstack.docker.LocalstackDocker.getEndpointLambda(LocalstackDocker.java:116)
	at cloud.localstack.DockerTestUtils.createEndpointConfiguration(DockerTestUtils.java:114)
	at cloud.localstack.DockerTestUtils.getClientLambda(DockerTestUtils.java:53)
```

Which seems misleading because even if I specifically set the port mapping localstack seems to ignore it. I also noticed that stepfunctions client is only available in the `DockerTestUtils` class and not in the `TestUtils` class so I cannot even try to do this without Docker.

Hints from issue discussion:
Hello,
I think that specifying the `randomizePorts` + a default port for Kinesis is causing the error.
When you specify `RandomizePorts` it means this: 
```java
    public RunCommand withExposedPorts(String portsToExpose, boolean randomize) {
        String portsOption = String.format("%s:%s", randomize ? "" : portsToExpose, portsToExpose );
        addOptions("-p", portsOption);
        return this;
    }
```
So there is a high chance that the port 77077 is not on the exposed port list.
Can you try with random or fixed port ?
If it is working, the documentation should be updated to reflect this.
I've run some tests locally and I can confirm that mixing randomize ports and fixing one for a service cause the issue.
I'll create a PR to explain this.

Commit message: Improve documentation around @LocalstackDockerProperties

Patch to review:
diff --git a/README.md b/README.md
index 100b81b7b2dfc..ccb7d70d1c7e8 100644
--- a/README.md
+++ b/README.md
@@ -371,7 +371,7 @@ duration of the test.  The container can be configured by using the @LocalstackD
 
 ```
 @RunWith(LocalstackDockerTestRunner.class)
-@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
+@LocalstackDockerProperties(services = { "sqs", "kinesis:77077" })
 public class MyDockerCloudAppTest {
 
   @Test
@@ -386,12 +386,25 @@ Or with JUnit 5 :
 
 ```
 @ExtendWith(LocalstackDockerExtension.class)
-@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
+@LocalstackDockerProperties(services = { "sqs", "kinesis:77077" })
 public class MyDockerCloudAppTest {
    ...
 }
 ```
 
+You can configure the Docker behaviour using the `@LocalstackDockerProperties` annotation with the following parameters:
+
+| property                    | usage                                                                                                                        | type                         | default value |   |
+|-----------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------|---------------|---|
+| pullNewImage                | Determines if a new image is pulled from the docker repo before the tests are run.                                           | boolean                      | false         |   |
+| randomizePorts              | Determines if the container should expose the default local stack ports (4567-4583) or if it should expose randomized ports. | boolean                      | false         |   |
+| services                    | Determines which services should be run when the localstack starts.                                                          | String[]                     | All           |   |
+| imageTag                    | Use a specific image tag for docker container                                                                                | String                       | latest        |   |
+| hostNameResolver            | Used for determining the host name of the machine running the docker containers so that the containers can be addressed.     | IHostNameResolver            | localhost     |   |
+| environmentVariableProvider | Used for injecting environment variables into the container.                                                                 | IEnvironmentVariableProvider | Empty Map     |   |
+
+_NB : When specifying the the port in the `services` property, you cannot use `randomizePorts = true`_
+
 The *LocalStack* JUnit test runner is published as an artifact in Maven Central.
 Simply add the following dependency to your `pom.xml` file:
 


Code review comments:
diff_hunk: @@ -386,12 +386,25 @@ Or with JUnit 5 :
 
 ```
 @ExtendWith(LocalstackDockerExtension.class)
-@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
+@LocalstackDockerProperties(services = { "sqs", "kinesis:77077" })
 public class MyDockerCloudAppTest {
    ...
 }
 ```
 
+You can configure the Docker behaviour using the `@LocalstackDockerProperties` annotation with the following parameters:
+
+| property                    | usage                                                                                                                        | type                         | default value |   |
path: README.md
text: @user1:
nit: seems like there is an unused additional column on the right side of the table which can be removed

diff_hunk: @@ -386,12 +386,25 @@ Or with JUnit 5 :
 
 ```
 @ExtendWith(LocalstackDockerExtension.class)
-@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
+@LocalstackDockerProperties(services = { "sqs", "kinesis:77077" })
 public class MyDockerCloudAppTest {
    ...
 }
 ```
 
+You can configure the Docker behaviour using the `@LocalstackDockerProperties` annotation with the following parameters:
+
+| property                    | usage                                                                                                                        | type                         | default value |   |
+|-----------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------|---------------|---|
+| pullNewImage                | Determines if a new image is pulled from the docker repo before the tests are run.                                           | boolean                      | false         |   |
+| randomizePorts              | Determines if the container should expose the default local stack ports (4567-4583) or if it should expose randomized ports. | boolean                      | false         |   |
+| services                    | Determines which services should be run when the localstack starts.                                                          | String[]                     | All           |   |
+| imageTag                    | Use a specific image tag for docker container                                                                                | String                       | latest        |   |
+| hostNameResolver            | Used for determining the host name of the machine running the docker containers so that the containers can be addressed.     | IHostNameResolver            | localhost     |   |
+| environmentVariableProvider | Used for injecting environment variables into the container.                                                                 | IEnvironmentVariableProvider | Empty Map     |   |
+
+_NB : When specifying the the port in the `services` property, you cannot use `randomizePorts = true`_
path: README.md
text: @user1:
nit: "the the"