more documentation about mocks

Author: ryber

mkdocs/docs/mocks.md

@@ -11,7 +11,7 @@ A series of mocks for use with Unirest for unit testing. Mocked clients will not
         C -->|Normal Runtime| F[Java HttpClient]
 ```
 
-## Expectations
+## Expecting Requests
 You can either mock the default static implementation or a per instance implementation. In both cases you need to register the mock with Unirest.
 
 ### Static Mocking
@@ -49,7 +49,7 @@ class MyTest {
     }
 ```
 
-## Multiple Expects
+### Multiple Expects
 HTTP requests can have many parts, some of which are automatic or at least uninteresting from the standpoint of testing. This means that setting up an exact expectation to match the request exactly can be tedious. 
 
 You can register as many expects as you like. Which one is used for any particular invocation of Unirest depends on a points system. Each expectation is evaluated and given points for each positive part while any negative part immediately discards the expect. The expectation that has the most points "wins".
@@ -86,7 +86,7 @@ In this example, we have three expectations, one doesn't match at all. and two o
     }
 ```
 
-## Verifying Expects
+### Verifying Expects
 Sometimes we only want to know that the needful was done. In this case we can validate our mock. The simplest way is to call verifyAll which will validate that all expects were called at least once.
 
 ```java
@@ -120,6 +120,88 @@ If you want to get more specific we can keep around our expectations and validat
     }
 ```
 
+### Expected Body Matching
+You can match specific body content with some limitations. Complex bodies must implement ```BodyMatcher```. There are two implementations available: ```EqualsBodyMatcher``` which is used for simple equality and ```FieldMatcher``` which is for form params. You can create your own.
+
+#### Simple Bodies
+```java
+    @Test
+    void simpleBody() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.POST, "http://zombo.com")
+                .body("I can do anything? Anything at all?")
+                .thenReturn()
+                .withStatus(201);
+
+        assertEquals(201,
+                Unirest.post("http://zombo.com").body("I can do anything? Anything at all?").asEmpty().getStatus()
+        );
+    }
+```
+
+#### Form Params
+```java
+    @Test
+    void formParams() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.POST, "http://zombo.com")
+                .body(FieldMatcher.of("foo", "bar",
+                                      "baz", "qux"))
+                .thenReturn()
+                .withStatus(201);
+
+        assertEquals(201,
+                Unirest.post("http://zombo.com")
+                        .field("foo", "bar")
+                        .field("baz", "qux")
+                        .asEmpty().getStatus()
+        );
+    }
+```
+
+## Expected Responses
+You can set all properties of a response.
+```java
+    @Test
+    void response() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.GET, "http://zombo.com")
+                .thenReturn("Care for some tea mum?")
+                .withHeader("x-zombo-brewing", "active")
+                .withStatus(418, "I am a teapot");
+
+        var response = Unirest.get("http://zombo.com").asString();
+
+        assertEquals(418, response.getStatus());
+        assertEquals("I am a teapot", response.getStatusText());
+        assertEquals("Care for some tea mum?", response.getBody());
+        assertEquals("active", response.getHeaders().getFirst("x-zombo-brewing"));
+    }
+```
+
+### Responses with JSON Bodies
+The mocking framework will use whatever ObjectMapper is configured with Unirest to marshall Pojos to expected responses.
+
+```java
+
+    static class Teapot { public String brewstatus = "on"; }
+    @Test
+    void pojos() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.GET, "http://zombo.com")
+                .thenReturn(new Teapot());
+
+        var response = Unirest.get("http://zombo.com").asString();
+
+        assertEquals("{\"brewstatus\":\"on\"}", response.getBody());
+    }
+```
+
+
 
 
 

unirest-modules-mocks/src/test/java/kong/tests/DocumentationExamplesTest.java

@@ -122,4 +122,66 @@ void multipleValidates(){
         zombo.verify();
         homestar.verify(Times.never());
     }
+
+    @Test
+    void simpleBody() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.POST, "http://zombo.com")
+                .body("I can do anything? Anything at all?")
+                .thenReturn()
+                .withStatus(201);
+
+        assertEquals(201,
+                Unirest.post("http://zombo.com").body("I can do anything? Anything at all?").asEmpty().getStatus()
+        );
+    }
+
+    @Test
+    void formParams() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.POST, "http://zombo.com")
+                .body(FieldMatcher.of("foo", "bar",
+                                      "baz", "qux"))
+                .thenReturn()
+                .withStatus(201);
+
+        assertEquals(201,
+                Unirest.post("http://zombo.com")
+                        .field("foo", "bar")
+                        .field("baz", "qux")
+                        .asEmpty().getStatus()
+        );
+    }
+
+    @Test
+    void response() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.GET, "http://zombo.com")
+                .thenReturn("Care for some tea mum?")
+                .withHeader("x-zombo-brewing", "active")
+                .withStatus(418, "I am a teapot");
+
+        var response = Unirest.get("http://zombo.com").asString();
+
+        assertEquals(418, response.getStatus());
+        assertEquals("I am a teapot", response.getStatusText());
+        assertEquals("Care for some tea mum?", response.getBody());
+        assertEquals("active", response.getHeaders().getFirst("x-zombo-brewing"));
+    }
+
+    static class Teapot { public String brewstatus = "on"; }
+    @Test
+    void pojos() {
+        MockClient mock = MockClient.register();
+
+        mock.expect(HttpMethod.GET, "http://zombo.com")
+                .thenReturn(new Teapot());
+
+        var response = Unirest.get("http://zombo.com").asString();
+
+        assertEquals("{\"brewstatus\":\"on\"}", response.getBody());
+    }
 }