PonyDebugger is a remote debugging toolset. It is a client library and gateway server combination that uses Chrome Developer Tools on your browser to debug your application's network traffic and managed object contexts.
To use PonyDebugger, you must implement the client in your application and connect it to the gateway server. There is currently an iOS client and the gateway server.
PonyDebugger is licensed under the Apache Licence, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html).
PonyDebugger sends your application's network traffic through ponyd, PonyDebugger's proxy server. You use Inspector's Network tools to debug network traffic like how you would debug network traffic on a website in Google Chrome.
PonyDebugger forwards network traffic, and does not sniff network traffic. This means that traffic sent over a secure protocol (https) is debuggable.
Currently, the iOS client automatically proxies data that is sent via NSURLConnection
. This means that it will automatically work with AFNetworking, and other libraries that use NSURLConnection
for network requests.
The Core Data browsing feature allows you to register your applcation's NSManagedObjectContext
s and browse all of its entities and managed objects. You browse data from the IndexedDB section in the Resource tab in Chrome Developer Tools.
These are read-only stores at the moment. There are plans to implement data mutation in a future release.
Prerequisite: Xcode's Command Line Tools must be installed from the "Downloads" preference pane.
curl -sk https://cloud.github.com/downloads/square/PonyDebugger/bootstrap-ponyd.py | \
python - --ponyd-symlink=/usr/local/bin/ponyd ~/Library/PonyDebugger
This will install ponyd
script to ~/Library/PonyDebugger/bin/ponyd
and
attempt to symlink /usr/local/bin/ponyd
to it. It will also download the
latest chrome dev tools source.
Then start the PonyDebugger gateway server
ponyd serve --listen-interface=127.0.0.1
In your browser, navigate to http://localhost:9000
. You should see the
PonyGateway lobby. Now you need to integrate the client to your application.
For more detailed instructions, check out the gateway server README_ponyd.
The PonyDebugger iOS client lets you to debug your application's network requests and track your managed object contexts.
- Requires iOS 5.0 or above
- Uses ARC (Automatic Reference Counting).
- Uses SocketRocket as a WebSocket client.
- Extract a tarball or zipball of the repository into your project directory. If you prefer, you may also add the project as a submodule. The iOS client uses SocketRocket as a dependency, and it is included as a submodule.
cd /path/to/YourApplication
mkdir Frameworks
git submodule add git://github.com/square/PonyDebugger.git Frameworks/PonyDebugger
git submodule update --init --recursive
- Add
PonyDebugger/PonyDebugger.xcodeproj
as a subproject.
- In your Project Settings, add the PonyDebugger target as a Target Dependency in the Build Phases tab.
- Link
libPonyDebugger.a
,libSocketRocket.a
, and the Framework dependencies to your project.
- In your project's Build Settings, add
$(CONFIGURATION_BUILD_DIR)/usr/local/include
as a non-recursive Header Search Path.
- PonyDebugger and SocketRocket take advantage of Objective C's ability to add categories on an object, but this isn't enabled for static libraries by default. To enable this, add the
-ObjC
flag to the "Other Linker Flags" build setting.
Your .app must be linked against the following frameworks/dylibs in addition to libPonyDebugger.a
and libSocketRocket.a
.
- libicucore.dylib
- CFNetwork.framework
- CoreData.framework
- Security.framework
- Foundation.framework
PonyDebugger's main entry points exist in the PDDebugger
singleton.
PDDebugger *debugger = [PDDebugger defaultInstance];
To open the connection to ws://localhost:9000/device
:
[debugger connectToURL:[NSURL URLWithString:@"ws://localhost:9000/device"]];
To manually close the connection:
[debugger disconnect];
To enable network debugging:
[debugger enableNetworkTrafficDebugging];
PonyDebugger inspects network data by injecting logic into NSURLConnectionDelegate
classes. If you want PonyDebugger to automatically find these classes for you:
[debugger forwardAllNetworkTraffic];
This will swizzle methods from private APIs, so you should ensure that this only gets invoked in debug builds. To manually specify delegate classes:
[debugger forwardNetworkTrafficFromDelegateClass:[MyClass class]];
These methods should be invoked before the connection is opened.
PonyDebugger also allows you to browse your application's managed objects. First, enable Core Data debugging:
[debugger enableCoreDataDebugging];
To register a managed object context:
[debugger addManagedObjectContext:self.managedObjectContext withName:@"My MOC"];
The repository contains a test application to demonstrate PonyDebugger's capabilities and usage.
CoreData.framework
must be linked, even if you do not use the Core Data browsing functionality.
Any contributors to the master PonyDebugger repository must sign the Individual Contributor License Agreement (CLA). It's a short form that covers our bases and makes sure you're eligible to contribute.
When you have a change you'd like to see in the master repository, send a pull request. Before we merge your request, we'll make sure you're in the list of people who have signed a CLA.
Some useful links: