1 MockWebServer 2 ============= 3 4 A scriptable web server for testing HTTP clients 5 6 7 ### Motivation 8 9 This library makes it easy to test that your app Does The Right Thing when it 10 makes HTTP and HTTPS calls. It lets you specify which responses to return and 11 then verify that requests were made as expected. 12 13 Because it exercises your full HTTP stack, you can be confident that you're 14 testing everything. You can even copy & paste HTTP responses from your real web 15 server to create representative test cases. Or test that your code survives in 16 awkward-to-reproduce situations like 500 errors or slow-loading responses. 17 18 19 ### Example 20 21 Use MockWebServer the same way that you use mocking frameworks like 22 [Mockito](https://code.google.com/p/mockito/): 23 24 1. Script the mocks. 25 2. Run application code. 26 3. Verify that the expected requests were made. 27 28 Here's a complete example: 29 30 ```java 31 public void test() throws Exception { 32 // Create a MockWebServer. These are lean enough that you can create a new 33 // instance for every unit test. 34 MockWebServer server = new MockWebServer(); 35 36 // Schedule some responses. 37 server.enqueue(new MockResponse().setBody("hello, world!")); 38 server.enqueue(new MockResponse().setBody("sup, bra?")); 39 server.enqueue(new MockResponse().setBody("yo dog")); 40 41 // Start the server. 42 server.start(); 43 44 // Ask the server for its URL. You'll need this to make HTTP requests. 45 HttpUrl baseUrl = server.url("/v1/chat/"); 46 47 // Exercise your application code, which should make those HTTP requests. 48 // Responses are returned in the same order that they are enqueued. 49 Chat chat = new Chat(baseUrl); 50 51 chat.loadMore(); 52 assertEquals("hello, world!", chat.messages()); 53 54 chat.loadMore(); 55 chat.loadMore(); 56 assertEquals("" 57 + "hello, world!\n" 58 + "sup, bra?\n" 59 + "yo dog", chat.messages()); 60 61 // Optional: confirm that your app made the HTTP requests you were expecting. 62 RecordedRequest request1 = server.takeRequest(); 63 assertEquals("/v1/chat/messages/", request1.getPath()); 64 assertNotNull(request1.getHeader("Authorization")); 65 66 RecordedRequest request2 = server.takeRequest(); 67 assertEquals("/v1/chat/messages/2", request2.getPath()); 68 69 RecordedRequest request3 = server.takeRequest(); 70 assertEquals("/v1/chat/messages/3", request3.getPath()); 71 72 // Shut down the server. Instances cannot be reused. 73 server.shutdown(); 74 } 75 ``` 76 77 Your unit tests might move the `server` into a field so you can shut it down 78 from your test's `tearDown()`. 79 80 ### API 81 82 #### MockResponse 83 84 Mock responses default to an empty response body and a `200` status code. 85 You can set a custom body with a string, input stream or byte array. Also 86 add headers with a fluent builder API. 87 88 ```java 89 MockResponse response = new MockResponse() 90 .addHeader("Content-Type", "application/json; charset=utf-8") 91 .addHeader("Cache-Control", "no-cache") 92 .setBody("{}"); 93 ``` 94 95 MockResponse can be used to simulate a slow network. This is useful for 96 testing timeouts and interactive testing. 97 98 ```java 99 response.throttleBody(1024, 1, TimeUnit.SECONDS); 100 ``` 101 102 103 #### RecordedRequest 104 105 Verify requests by their method, path, HTTP version, body, and headers. 106 107 ```java 108 RecordedRequest request = server.takeRequest(); 109 assertEquals("POST /v1/chat/send HTTP/1.1", request.getRequestLine()); 110 assertEquals("application/json; charset=utf-8", request.getHeader("Content-Type")); 111 assertEquals("{}", request.getUtf8Body()); 112 ``` 113 114 #### Dispatcher 115 116 By default MockWebServer uses a queue to specify a series of responses. Use a 117 Dispatcher to handle requests using another policy. One natural policy is to 118 dispatch on the request path. 119 You can, for example, filter the request instead of using `server.enqueue()`. 120 121 ```java 122 final Dispatcher dispatcher = new Dispatcher() { 123 124 @Override 125 public MockResponse dispatch(RecordedRequest request) throws InterruptedException { 126 127 if (request.getPath().equals("/v1/login/auth/")){ 128 return new MockResponse().setResponseCode(200); 129 } else if (request.getPath().equals("v1/check/version/")){ 130 return new MockResponse().setResponseCode(200).setBody("version=9"); 131 } else if (request.getPath().equals("/v1/profile/info")) { 132 return new MockResponse().setResponseCode(200).setBody("{\\\"info\\\":{\\\"name\":\"Lucas Albuquerque\",\"age\":\"21\",\"gender\":\"male\"}}"); 133 } 134 return new MockResponse().setResponseCode(404); 135 } 136 }; 137 server.setDispatcher(dispatcher); 138 ``` 139 140 141 ### Download 142 143 Get MockWebServer via Maven: 144 ```xml 145 <dependency> 146 <groupId>com.squareup.okhttp</groupId> 147 <artifactId>mockwebserver</artifactId> 148 <version>(insert latest version)</version> 149 <scope>test</scope> 150 </dependency> 151 ``` 152 153 or via Gradle 154 ```groovy 155 testCompile 'com.squareup.okhttp:mockwebserver:(insert latest version)' 156 ``` 157 158 ### License 159 160 Licensed under the Apache License, Version 2.0 (the "License"); 161 you may not use this file except in compliance with the License. 162 You may obtain a copy of the License at 163 164 http://www.apache.org/licenses/LICENSE-2.0 165 166 Unless required by applicable law or agreed to in writing, software 167 distributed under the License is distributed on an "AS IS" BASIS, 168 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 169 See the License for the specific language governing permissions and 170 limitations under the License. 171
