Add a simple example with how to use the mock server container (#1950)

* Add a simple example with how to use the mock server container

* Move examples for mockserver to unit tests

Author: worldtiki

docs/modules/mockserver.md

@@ -1,5 +1,21 @@
 # Mockserver Module
 
+Mock Server can be used to mock HTTP services by matching requests against user-defined expectations.
+
+## Usage example
+
+The following example shows how to start Mockserver.
+
+<!--codeinclude-->
+[Creating a MockServer container](../../modules/mockserver/src/test/java/org/testcontainers/containers/MockServerContainerTest.java) inside_block:creatingProxy
+<!--/codeinclude-->
+
+And how to set a simple expectation using the Java MockServerClient.
+
+<!--codeinclude-->
+[Setting a simple expectation](../../modules/mockserver/src/test/java/org/testcontainers/containers/MockServerContainerTest.java) inside_block:testSimpleExpectation
+<!--/codeinclude-->
+
 ## Adding this module to your project dependencies
 
 Add the following dependency to your `pom.xml`/`build.gradle` file:
@@ -16,3 +32,4 @@ testCompile "org.testcontainers:mockserver:{{latest_version}}"
     <scope>test</scope>
 </dependency>
 ```
+

modules/mockserver/src/test/java/org/testcontainers/containers/MockServerContainerTest.java

@@ -1,6 +1,7 @@
 package org.testcontainers.containers;
 
 import lombok.Cleanup;
+import org.junit.Rule;
 import org.junit.Test;
 import org.mockserver.client.MockServerClient;
 
@@ -11,12 +12,43 @@
 import java.net.URLConnection;
 
 import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.equalTo;
 import static org.mockserver.model.HttpRequest.request;
 import static org.mockserver.model.HttpResponse.response;
 import static org.rnorth.visibleassertions.VisibleAssertions.assertThat;
 
 public class MockServerContainerTest {
 
+    // creatingProxy {
+    @Rule
+    public MockServerContainer mockServer = new MockServerContainer();
+    // }
+
+    private static String responseFromMockserver(MockServerContainer mockServer, String path) throws IOException {
+        URLConnection urlConnection = new URL(mockServer.getEndpoint() + path).openConnection();
+        @Cleanup BufferedReader reader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream()));
+        return reader.readLine();
+    }
+
+    @Test
+    public void shouldReturnExpectation() throws Exception {
+        // testSimpleExpectation {
+        new MockServerClient(mockServer.getContainerIpAddress(), mockServer.getServerPort())
+            .when(request()
+                .withPath("/person")
+                .withQueryStringParameter("name", "peter"))
+            .respond(response()
+                .withBody("Peter the person!"));
+
+        // ...a GET request to '/person?name=peter' returns "Peter the person!"
+        // }
+
+        assertThat("Expectation returns expected response body",
+            responseFromMockserver(mockServer, "/person?name=peter"),
+            containsString("Peter the person")
+        );
+    }
+
     @Test
     public void shouldCallActualMockserverVersion() throws Exception {
         String actualVersion = MockServerClient.class.getPackage().getImplementationVersion();
@@ -25,33 +57,14 @@ public void shouldCallActualMockserverVersion() throws Exception {
 
             String expectedBody = "Hello World!";
 
-            assertThat("MockServer returns correct result",
-                responseFromMockserver(mockServer, expectedBody, "/hello"),
-                containsString(expectedBody)
-            );
-        }
-    }
+            new MockServerClient(mockServer.getContainerIpAddress(), mockServer.getServerPort())
+                .when(request().withPath("/hello"))
+                .respond(response().withBody(expectedBody));
 
-    @Test
-    public void shouldCallDefaultMockserverVersion() throws Exception {
-        try (MockServerContainer mockServerDefault = new MockServerContainer()) {
-            mockServerDefault.start();
-            String expectedBody = "Hello Default World!";
-
-            assertThat("MockServer returns correct result for default constructor",
-                responseFromMockserver(mockServerDefault, expectedBody, "/hellodefault"),
-                containsString(expectedBody)
+            assertThat("MockServer returns correct result",
+                responseFromMockserver(mockServer, "/hello"),
+                equalTo(expectedBody)
             );
         }
     }
-
-    private static String responseFromMockserver(MockServerContainer mockServer, String expectedBody, String path) throws IOException {
-        new MockServerClient(mockServer.getContainerIpAddress(), mockServer.getServerPort())
-            .when(request(path))
-            .respond(response(expectedBody));
-
-        URLConnection urlConnection = new URL(mockServer.getEndpoint() + path).openConnection();
-        @Cleanup BufferedReader reader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream()));
-        return reader.readLine();
-    }
 }