Barricade

Runtime configurable local server for Android




Introduction

Barricade allows apps to get responses to API requests by intercepting them using an OkHttp Network Interceptor. The responses are fetched from local assets based on the configuration.


Barricade also supports multiple responses per request, unlike other local server implementations and presents the user with a UI for modifying which response to return for a request at runtime. It also provides an option to change the response and latency of the API call programatically

Why Barricade

  • Barricade removes the hard dependency of an Android app on it's backend. Just with the API specification, developers can start developing and testing their apps without waiting for the backend to be set up.

  • Barricade is useful for covering all the edge cases that an API endpoint can have, by modifying the responses and response time of the API locally. This reduces the load of setting up tools like Charles proxy to test how the app reats to various responses.

  • Barricade allows configuring the response time of each API at runtime both programatically and from the UI. This help a lot in testing as various android components react differently to different response times.

  • Barricade helps in writing better unit, integration and instrumentation tests by allowing to toggle through predefined responses for every request.

How is it different from OkHttp's MockWebServer?

  • MockWebServer is queue-based which is ok for simple apps, but hard to use predictably when you have multiple calls getting fired at the same time. Barricade is call-specific so it'll always return the response you configure irrespective of the number of requests your app is making.

  • Barricade gives you a UI to easily change the configuration whenever you want so even your QA can test different scenarios easily,

  • Barricade can be used outside of tests. For example, you can easily build a full-fledged demo mode to allow users to try out the app without creating an account.

  • Barricade allows you to specify responses in files instead of plain strings which keeps your codebase clean.

Download

↓ Latest JAR

The source code of Barricade, and the sample app is available on GitHub.

Gradle


compile 'com.mutualmobile:barricade:(insert latest version)'
annotationProcessor 'com.mutualmobile:barricade-compiler:(insert latest version)'

Barricade supports Android 4.1+

Barricade Configuration

Barricade is the runtime class which is used to initialize and configure the library dynamically.

BarricadeConfig is the class which is generated at compile time based on the @Barricade annotations and data provided inside it.

BarricadeActivity is an activity class which provides a UI to select the default response for each API endpoint.


Below are the steps to configure Barricade in an Android application -


  1. Install Barricade in the onCreate() method of your Application class.

    @Override
public void onCreate() {
    super.onCreate();
    new Barricade.Builder(this, new BarricadeConfig()).enableShakeToStart(this).install();
    ...
}
    Note: Setting enableShakeToStart to true starts BarricadeActivity when device is shaked twice.

  2. Add your API response files to assets/barricade/<endpoint_name> for different types of responses (success, invalid, error etc).


  3. In the Retrofit service API interface, annotate the methods with @Barricade. The @Barricade annotation accepts 2 parameters:

    • endpoint - The name of the last path segment in the URL
    • responses - An array of @Response annotations corresponding to various responses barricade can return 
    @GET("/users/{user}/repos")
@Barricade(endpoint = "repos", responses = {
        @Response(fileName = "get_repos_success", isDefault = true),
        @Response(fileName = "get_repos_error", statusCode = 500)
}) Single<ReposResponse> getUserRepositories(@Path("user") String userId);
...

    Each @Response annotation corresponds to a unique response for the given endpoint. It takes 4 parameters:

    • fileName - The name of the response file in folder assets/barricade/endpoint/
    • statusCode - The status code of the API response (eg. 200, 404, 500, etc)
    • type - Response type (eg. "application/json", "application/xml", etc)
    • isDefault - Should be set to true for only one response for a given endpoint. This sets the enclosing response as the default for given endpoint

  4. Add BarricadeInterceptor to OkHttpClient

    OkHttpClient okHttpClient =
      new OkHttpClient.Builder().addInterceptor(new BarricadeInterceptor())
          ...
          .build();
  5. Done

Configure Barricade programmatically

  • Barricade can be enabled or disabled at runtime.

    To enable - Barricade.getInstance().setEnabled(true);

    To disable - Barricade.getInstance().setEnabled(false);

  • Change response for endpoints

    Barricade allows changing the response time and the default response for an endpoint at runtime.

    If enableShakeToStart was set to true during Barricade initialization, the following process can used to configure Barricade -

    • Open Barricade settings by shaking the device
    • Change the response time in milliseconds by clicking on the timer on top right
    • To change the required response for a request, click on the request from list and then select the response you want from the list of responses. This list is populated from the response files in assets folder

    You can also change the above settings programmatically which can be helpful for testing -

    Barricade.getInstance()
        .setDelay(100)
        .setResponse(BarricadeConfig.Endpoints.REPOS, BarricadeConfig.Responses.Repos.GetReposSuccess);

    Note: Changes made using setDelay and setResponse are persisted in SharedPreferences.

Contributing

If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request.

When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible.

License

Copyright 2016 Mutual Mobile

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.