REST API mocking made easy.
RESTMock is a library working on top of Square's okhttp/MockWebServer. It allows you to specify Hamcrest matchers to match HTTP requests and specify what response to return. It is as easy as:
RESTMockServer.whenGET(pathContains("users/andrzejchm"))
.thenReturnFile(200, "users/andrzejchm.json");
Article
- Setup
- HTTPS
- Response chains
- Response delays
- Request verification
- Logging
- Android Sample Project
- Donation
- License
Here are the basic rules to set up RESTMock for Android
Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url "https://jitpack.io" }
}
}
Add the dependency
dependencies {
androidTestImplementation 'com.github.andrzejchm.RESTMock:android:${LATEST_VERSION}' // see "Releases" tab for latest version
}
It's good to start server before the tested application starts, there are few methods:
To make it simple you can just use the predefined RESTMockTestRunner
in your UI tests. It extends AndroidJUnitRunner
:
defaultConfig {
...
testInstrumentationRunner 'io.appflate.restmock.android.RESTMockTestRunner'
}
If you have your custom test runner and you can't extend RESTMockTestRunner
, you can always just call the RESTMockServerStarter
. Actually RESTMockTestRunner
is doing exactly the same thing:
public class MyAppTestRunner extends AndroidJUnitRunner {
...
@Override
public void onCreate(Bundle arguments) {
super.onCreate(arguments);
RESTMockServerStarter.startSync(new AndroidAssetsFileParser(getContext()),new AndroidLogger());
...
}
...
}
By default, the RESTMockTestRunner
uses AndroidAssetsFileParser
as a mocks file parser, which reads the files from the assets folder. To make them visible for the RESTMock you have to put them in the correct folder in your project, for example:
.../src/androidTest/assets/users/defunkt.json
This can be accessed like this:
RESTMockServer.whenGET(pathContains("users/defunkt"))
.thenReturnFile(200, "users/defunkt.json");
If the response You wish to return is simple, you can just specify a string:
RESTMockServer.whenGET(pathContains("users/defunkt"))
.thenReturnString(200, "{}");
If you wish to have a greater control over the response, you can pass the MockResponse
RESTMockServer.whenGET(pathContains("users/defunkt")).thenReturn(new MockResponse().setBody("").setResponseCode(401).addHeader("Header","Value"));
You can always build dynamic MockResponse
s by using the RecordedRequest
object
RESTMockServer.whenGET(pathContains("users/defunkt")).thenAnswer(new MockAnswer() {
@Override
public MockResponse answer(RecordedRequest request) {
return new MockResponse()
.setBody(request.getHeaders().get("header1"))
.setResponseCode(200);
}
});
You can either use some of the predefined matchers from RequestMatchers
util class, or create your own. remember to extend from RequestMatcher
The most important step, in order for your app to communicate with the testServer, you have to specify it as an endpoint for all your API calls. For that, you can use the RESTMockServer.getUrl()
. If you use Retrofit, it is as easy as:
RestAdapter adapter = new RestAdapter.Builder()
.baseUrl(RESTMockServer.getUrl())
...
.build();
take a look at #68 for better reference
By default, RESTMockServer will serve responses using Http. In order to use HTTPS, during initialization you have to pass RESTMockOptions
object with useHttps
set to true:
RESTMockServerStarter.startSync(new AndroidAssetsFileParser(getContext()),new AndroidLogger(), new RESTMockOptions.Builder().useHttps(true).build());
there is a possibility to set up your own SSLSocketFactory
and TrustManager
, if you do not specify those, then default ones will be created for you. You can easly retrieve them with RESTMockServer.getSSLSocketFactory()
and RESTMockServer.getTrustManager()
to be able to build your client that will accept the default certificate:
new OkHttpClient.Builder().sslSocketFactory(RESTMockServer.getSSLSocketFactory(), RESTMockServer.getTrustManager()).build();
A sample how to use https with RESTMock in android tests can be found in androidsample
gradle module within this repository.
You can chain different responses for a single request matcher, all the thenReturn*()
methods accept varags parameter with response, or you can call those methods multiple times on a single matcher, examples:
RESTMockServer.whenGET(pathEndsWith(path))
.thenReturnString("a single call")
.thenReturnEmpty(200)
.thenReturnFile("jsonFile.json");
or
RESTMockServer.whenGET(pathEndsWith(path))
.thenReturnString("a single call", "answer no 2", "answer no 3");
Delaying responses is accomplished with the delayBody(TimeUnit timeUnit, long delay)
and delayHeaders(TimeUnit timeUnit, long delay)
method. Delays can be specified in chain, just like chaining responses:
RESTMockServer.whenGET(pathEndsWith(path))
.thenReturnString("a single call")
.delayBody(TimeUnit.SECONDS, 5)
.delayBody(TimeUnit.SECONDS, 10)
.delayBody(TimeUnit.SECONDS, 15);
or
RESTMockServer.whenGET(pathEndsWith(path))
.thenReturnString("a single call")
.delayBody(TimeUnit.SECONDS, 5, 10, 15);
Which will result in 1st response body being delayed by 5 seconds, 2nd response by 10 seconds and 3rd, 4th, 5th... by 15 seconds.
Mechanics of the responseHeader(...)
method are the same as those in responseBody(...)
. The only difference is that response headers are being delivered with a delay. This comes handy if your app is acting on response headers, which would've been delivered immediately if you used the delayBody(...)
method.
Check out this example:
RESTMockServer.whenGET(pathEndsWith(path))
.thenReturnString("1st call")
.delay(TimeUnit.SECONDS, 5)
.thenReturnString("2nd call")
.delay(TimeUnit.SECONDS, 10)
.delay(TimeUnit.SECONDS, 15)
.thenReturnString("3rd call")
.delay(TimeUnit.SECONDS, 20, 30, 40)
this will result in 1st call
being delayed by 5 seconds, 2nd call
delayed by 10 seconds, 3rd call
delayed by 15 seconds, another one by 20 seconds, and another by 30 seconds, and then every consecutive response with 40 seconds delay
It is possible to verify which requests were called and how many times thanks to RequestsVerifier
. All you have to do is call one of these:
//cheks if the GET request was invoked exactly 2 times
RequestsVerifier.verifyGET(pathEndsWith("users")).exactly(2);
//cheks if the GET request was invoked at least 3 times
RequestsVerifier.verifyGET(pathEndsWith("users")).atLeast(3);
//cheks if the GET request was invoked exactly 1 time
RequestsVerifier.verifyGET(pathEndsWith("users")).invoked();
//cheks if the GET request was never invoked
RequestsVerifier.verifyGET(pathEndsWith("users")).never();
Additionaly, you can manualy inspect requests received by RESTMockServer. All you have to do is to obtain them trough:
//gets 5 most recent requests received. (ordered from oldest to newest)
RequestsVerifier.takeLast(5);
//gets 5 oldest requests received. (ordered from oldest to newest)
RequestsVerifier.takeFirst(5);
//gets all GET requests. (ordered from oldest to newest)
RequestsVerifier.takeAllMatching(isGET());
RESTMock supports logging events. You just have to provide the RESTMock with the implementation of RESTMockLogger
. For Android there is an AndroidLogger
implemented already. All you have to do is use the RESTMockTestRunner
or call
RESTMockServerStarter.startSync(new AndroidAssetsFileParser(getContext()),new AndroidLogger(), new RESTMockOptions());
or
RESTMockServer.enableLogging(RESTMockLogger)
RESTMockServer.disableLogging()
You can check out the sample Android app with tests here
If you think the library is awesome and want to buy me a beer, you can do so by sending some...
- ETH here:
0xf7354a0F7B34A380f6d68a2661bE465C10D6AEd7
- BTC here:
12bU3BMibFqbBBymaftXTDnoHojFymD7a6
- NEO or GAS here:
AX1ovzRN2N28WJrtehjYXjwtHSvcqva6Ri
Copyright (C) 2016 Appflate.io
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.