Beagle (Android library)

A smart and reliable companion library for debugging your Android apps.

Beagle

Usage

Add the following to your top level Gradle file:

allprojects {
    repositories {
        …
        maven { url "https://jitpack.io" }
    }
}

...and this to the module-level build script (check the widget below the code snippet for the latest version):

dependencies {
    …
    def beagleVersion = "1.1.1"
    debugImplementation "com.github.pandulapeter.beagle:beagle:$beagleVersion"
    releaseImplementation "com.github.pandulapeter.beagle:beagle-noop:$beagleVersion"
}

The latest version is:

The library has to be initialized with an Application instance (preferably in the Application's onCreate() method) by calling:

Beagle.imprint(this)

After this a list of modules (tricks) needs to be provided, but this can be changed at any time and the UI will be automatically updated. See this implementation for a detailed example.

Screenshots

beagle

Tricks

Any number of generic modules can be added in any order as long as they have a unique ID:

  • Divider - Displays a horizontal line.
  • Padding - Displays an empty space of specified size.
  • Text - Displays simple text content.
  • LongText - Displays a longer piece of text that can be collapsed into a title.
  • Image - Displays a drawable.
  • TODO: TextInput - Allows the user to enter free text.
  • Slider - Allows the user to adjust a numeric value.
  • TODO: ColorPicker - Allows the user to pick a color.
  • Toggle - Displays a switch with configurable title and behavior - ideal for feature toggles.
  • Button - Displays a button with configurable text and action.
  • KeyValue - Displays a list of key-value pairs that can be collapsed into a title.
  • SimpleList - Displays an expandable list of custom items and exposes a callback when the user makes a selection. A possible use case could be providing a list of test accounts to make the authentication flow faster.
  • SingleSelectionList - Displays a list of radio buttons. A possible use case could be changing the base URL of the application to simplify testing on different backend environments.
  • MultipleSelectionList - Displays a lst of checkboxes.
  • LogList - Displays an expandable list of your custom logs. An example use case could be logging analytics events. Each item can be tapped for more information if you specified a payload. To log an event, simply call Beagle.log().

Unique modules can only be added once as they are specific to a single use case:

  • Header - Displays a header on top of the drawer with general information about the app / build.
  • KeylineOverlayToggle - Displays a switch that, when enabled, draws a grid over your app with configurable dimensions that you can use to check the alignments of your Views.
  • TODO: ForceRtToggle - Forces RTL layout orientation (on/off).
  • AppInfoButton - Displays a button that links to the Android App Info page for your app.
  • ScreenshotButton - Displays a button that takes a screenshot of the current layout and allows the user to share it.
  • TODO: StringGeneratorButton - Generates a string based on the user's preferences and copies it to the clipboard.
  • NetworkLogList - Displays an expandable list of historical network activity. Each item can be tapped for more information. To use this functionality, the custom beagleNetworkInterceptor needs to be added to the OkHTTP Client's builder, as implemented here.
  • DeviceInformationKeyValue - Displays information about the current device and the OS.

The module list can be changed at any time (from any thread) using the following functions:

Beagle.learn(tricks)
Beagle.learn(trick, positioning)
Beagle.forget(id)

See this file for documentation about every supported module.

Customization

  • The UI of the drawer can be personalized by specifying an Appearance instance when initializing the library.
  • To properly support back navigation, all activities must check if the drawer consumes the event. This is implemented here.
  • The drawers can be disabled / enabled at runtime by modifying the value of Beagle.isEnabled. This could be useful if you want to restrict access to the debug drawer features based on user type.

Known issues

  • If your app already has a DrawerLayout (especially with a drawer on GravityCompat.END) you will probably have some issues.
  • The library depends on AndroidX. If your app uses the legacy support library, it will probably introduce some conflicts.
  • The library depends on OkHttp version 4. If your app uses an older version, you should update it.

GitHub