DebugDrawer

A configurable debug drawer to use in your Android app. Inspired by u2020.

The debug drawer is something you can add to your debug builds to make your life easier as a developer or tester. It provides a convenient way of exposing development specific controls without cluttering up your user interface. There are quite a few possibilities this opens up, such as adding shortcuts, displaying diagnostic information, or anything you might want.

To give you some inspiration, this repository provides out of the box modules for:

• Configuring Retrofit endpoints and mock network behaviour
• Displaying device information
• Viewing and sharing Logcat entries collected by Timber
• Providing a more convenient entry into LeakCanary
• Selecting a logging level and piping OkHttp logs into Timber

Of course, you're free to implement your own modules as well.

Usage

This library assumes that for a given Activity you will populate one to many ViewGroups inside of it over its lifetime. Instead of calling setContentView() directly, define a function in both your debug and release builds to get the root ViewGroup that Activity should use to present a screen. This would look something like...

Debug

fun getRootContainerFor(activity: Activity): ViewGroup {
  return DebugDrawer.with(activity)
      .addSectionTitle("Device information")
      .addModule(DeviceInfoModule())
      // ...and whatever other modules you want to add.
      .buildMainContainer()
}

Release

fun getRootContainerFor(activity: Activity): ViewGroup {
  return activity.findViewById(android.R.id.content) as ViewGroup
}

You can then use this ViewGroup to populate your Activity's view, or use it as the container when push/popping Fragments or Controllers or whatever you fancy. For your debug builds this container will be inside of a DrawerLayout, allowing you to swipe from the "end" edge of your screen to get access to debug settings. For release builds you'll be pushing views into the root container as normal. If you have gesture navigation enabled, you can swipe in from the top 200dp of the screen to reveal the drawer instead of navigating back.

Making new modules

You have two options if you want to add custom modules to your drawer. You can implement DebugDrawerModule, or you can extend KeyValueDebugDrawerModule. The latter is useful if all you want to do is display some key value pairs. The former allows you to return whatever View you want. It also provides optional lifecycle callbacks if your module needs to bind and unbind to expensive resources.

The debugdrawer dependency has a few publicly exported style resources. You can use these styles (such as Widget.DebugDrawer.RowTitle) to ensure your custom module maintains a consistent appearance with other modules in the drawer. Yes, this is a development tool, but developers can appreciate nice UIs too!

Why another implementation?

It's true; there are a few other implementations of a reusable debug drawer out there. This project aims to have a simpler API, especially when it comes to creating custom modules. Also having the library written in Kotlin makes it more enjoyable to work on 😄 .

Sample apps

This repository provides two sample apps that demonstrate usage of the debug drawer. The simple-sample-app has no other dependencies and is about as bare-bones as you can get. The sample-app is a bit more complex. It interfaces with the Giant Bomb API to retrieve and display a list of video games, and aims to be closer to a real application.

Browsing through the implementation of sample-app should provide you with an idea of how you could add the debug drawer to your app. You might want to use dependency injection to assist in setting it up, or you could follow the example and try and roll something by hand. Whatever your choice, it doesn't need to be particularly complex.

Provided modules

LeakCanary

LeakCanary is a fantastic tool for detecting memory leaks in your app. The only problem with it is how it adds a launcher icon for each app you have installed that uses it. This module takes care of removing that launcher icon and cages LeakCanary in the debug drawer. It also provides a handy switch for toggling heap dumps on and off.

Timber

Timber provides some nice utility on top of Android's standard Log class. This modules aims to enhance it further by providing a mechanism to view logs from within your own app. In addition, it allows you to share the current collection of logs if you happen to see something interesting.

OkHttp logger

It can be incredibly useful to view HTTP requests and results when debugging your app. This module provides a dropdown menu in the drawer to select what level of logging you'd like to see for your HTTP requests. It relies on you using OkHttp as your HTTP client, and pipes its output into Timber.

To use it, first add HttpLogger.interceptor as an interceptor to your OkHttpClient. Then pass HttpLogger on to OkHttpLoggerModule.

Device info

Nothing too fancy, this module displays

• Manufacturer
• Model
• Screen resolution
• Screen density
• Current API version

Retrofit

This is one of the more complicated modules. Retrofit is a great tool for abstracting RESTful APIs, and often you might want to configure its behaviour. This is useful if you make use of retrofit-mock and want to modify NetworkBehavior at runtime, or maybe your debug app can target one of many different environments, such as development, staging, or production.

To begin, you must create a list of Endpoints. This list might include entries such as staging, or mock.

Next, create an instance of DebugRetrofitConfig. This class takes care of persisting settings between app launches, and forwarding any runtime modifications to NetworkBehavior. It also ensures that when you select a new Endpoint your entire app process is restarted.

Finally, you can add RetrofitModule to your debug drawer builder and it will take care of the rest. It might be easier to understand by looking at an example, so check out sample-app to see it in action.

Download

All artifacts are up on Maven Central.

For the main library

au.com.gridstone.debugdrawer:debugdrawer:0.9.7

For the LeakCanary module

au.com.gridstone.debugdrawer:debugdrawer-leakcanary:0.9.7

For the Retrofit module

au.com.gridstone.debugdrawer:debugdrawer-retrofit:0.9.7

For the Timber module

au.com.gridstone.debugdrawer:debugdrawer-timber:0.9.7

For the OkHttp logger

au.com.gridstone.debugdrawer:debugdrawer-okhttp-logger:0.9.7

Snapshots

Snapshots are also available by adding the repository

maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }

Letting you specify

au.com.gridstone.debugdrawer:debugdrawer:0.9.8-SNAPSHOT

Contributing

Pull requests are welcome, but we do want to keep this codebase fairly lean. Consider how much utility a new drawer module would provide to all Android developers. If it's usage is niche then it might be better maintained as a separate project. Feel free to open issues to discuss new module ideas.

When submitting code, please adhere to Gridstone's Kotlin style guide.

Licence

Copyright 2018 GRIDSTONE

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.