search

indragiek / InAppViewDebugger

A UIView debugger (like Reveal or Xcode) that can be embedded in an app for on-device view debugging
MIT License
1.88k stars 109 forks source link
debugger debugging ios ipad iphone swift ui uiview view visualization

readme

InAppViewDebugger

License CocoaPods Carthage compatible

InAppViewDebugger

InAppViewDebugger is a library that implements a view debugger with a 3D snapshot view and a hierarchy view, similar to Reveal and Xcode's own view debugger. The key distinction is, as the project title suggests, that this can be embedded inside the app and used on-device to debug UI issues without needing to be tethered to a computer.

Features

Requirements

Installation

CocoaPods

Add the following line to your Podfile:

pod 'InAppViewDebugger', '~> 1.0.3'

Carthage

Add the following line to your Cartfile:

github "indragiek/InAppViewDebugger" "1.0.3"

Usage

Swift

import InAppViewDebugger

@IBAction func showViewDebugger(sender: AnyObject) {
  InAppViewDebugger.present()
}

Objective-C

@import InAppViewDebugger;

// alternative import (they're the same):
// #import <InAppViewDebugger/InAppViewDebugger-Swift.h>

- (IBAction)showViewDebugger:(id)sender {
  [InAppViewDebugger present];
}

lldb

(lldb) expr -lswift -- import InAppViewDebugger
(lldb) expr -lswift -- InAppViewDebugger.present()

The present function shows the UI hierarchy for your application's key window, presented over the top view controller of the window's root view controller. There are several other methods available on InAppViewDebugger for presenting a view debugger for a given window, view, or view controller.

Controls

Focusing on an Element

To focus on the subhierarchy of a particular element, long press on the element to bring up the action menu and tap "Focus". The long press can be used both in the hierarchy view and the 3D snapshot view. The "Log Description" action will log the description of the element to the console, so that if you're attached to Xcode you can copy the address of the object for further debugging.

Focusing on an Element

Adjusting Distance Between Levels

The slider on the bottom left of the snapshot view can be used to adjust the spacing between levels of the hierarchy:

Adjusting Distance Between Levels

Adjusting Visible Levels

The range slider on the bottom right of the snapshot view can be used to adjust the range of levels in the hierarchy that are visible:

Adjusting Visible Levels

Showing/Hiding Headers

Each UI element has a header above it that shows its class name. These headers can be hidden or shown by long pressing on an empty area of the snapshot view to bring up the action menu:

Showing/Hiding Headers

Showing/Hiding Borders

Similarly to the headers, the borders drawn around each element can also be shown or hidden:

Showing/Hiding Borders

Customization

Colors, fonts, and other attributes for both the snapshot view and the hierarchy view can be changed by creating a custom Configuration. The configuration is then passed to a function like InAppViewDebugger.presentForWindow(:configuration:completion:).

Extending for Other UI Frameworks

The current implementation only supports UIView hierarchies, but this can easily be extended to support other UI frameworks by conforming to the Element protocol. See ViewElement to see what an example implementation looks like — by providing a the frame, a snapshot image, and a few other pieces of information, all of the features described above will work for your own framework.

A Snapshot instance represents a recursive snapshot of the current state of a UI element hierarchy, and is constructed using an Element. The snapshot can then be passed to

InAppViewDebugger.presentWithSnapshot(:rootViewController:configuration:completion:)

to show the view debugger.

Credits

Contact

License

InAppViewDebugger is licensed under the MIT License. See LICENSE for more information.