Javascript Debugger for Android

jsHybugger allows you to debug web pages which runs inside a hybrid app (WebView, PhoneGap) or the default android web browser.

View on GitHub Install APK (1.1.1) Stable JAR (1.1.1) Devel JAR (1.2.0_r1)

Why jsHybugger?

Remote debugging capabilities on mobile devices are very useful, and the important browsers have already built-in support for this technic. But unfortunately this technic is not available for javascript code which runs inside a native app (WebView, PhoneGap) or the default android browser – that’s the reason why jsHybugger exists!

How it works?

Before your JS-Code is loaded and executed by the javascript engine inside your browser, jsHybugger will do an on-the-fly instrumentation of your code to make it debuggable. The instrumentation is very fast and the result is cached for further use. The runtime overhead is very small.

How to use?

To debug a page in the default Android browser, just install the jsHybugger App from play store and start it. The App acts as a reverse proxy which does the on-the-fly instrumentation. For the other use case – Debugging a native app (WebView, PhoneGap), you have to add the jsHybugger library to your android project.


jsHybugger features

  • add/remove/enable/disable line breakpoints
  • watch expressions
  • step into/over/out
  • pause on exception
  • call stack navigation
  • local variable inspection
  • remote console
  • javascript syntax and runtime error reporting
  • view/edit/delete Local Storage items
  • view/edit/delete Session Storage items
  • view/edit/delete WebSQL Database records (watch Video)
  • view page resources (images, scripts, html)
  • remote console support enhanced (stacktrace)
  • Debugger: enhanced object inspection
  • Debugger: conditional breakpoints
  • Debugger: continue to here
  • Frontend upgraded to Chrome Dev Tools 27.0.1453.90

jsHybugger Server

The jsHybugger server runs on your device/emulator and is responsible for the JS-code instrumentation and the communication between the debugging frontent (client) and the app to be debugged. Depending on the usage mode (Proxy mode/ Service mode), jsHybugger will be installed either as a standalone app or as part of your application.

Proxy Mode

The “proxy mode” is very easy to use and suitable for web pages which are loaded from a webserver and displayed in the default android browser or webview (theorectically you can also use it for other browsers, but i.e. chrome and firefox we already have their own remote debugging tools). In “proxy mode” jsHybugger works as a reverse proxy on port 8080, all HTTP traffic which is sent to this port is forwarded to the configured remote host/port.

Just install and configure the jsHybugger Proxy App or download APK and read the section “jsHybugger GUI” on this page. A good starting point is also to watch the following video or the slides.

 

Service Mode

The “service mode” is suitable for hybrid apps (i.e. PhoneGap) with “local” file (*.js, *.html, …) resources i.e.

Just download the jsHybugger.jar file and add it to your android project.

Add the following lines to your AndroidManifest.xml file.

<!-- JsHybugger needs network access -->
<uses-permission android:name="android.permission.INTERNET" />

<!--  JSHybugger webview content provider -->
<provider android:name="org.jshybugger.DebugContentProvider"
		  android:exported="false"
		  android:authorities="jsHybugger.org" />
  
<!--  JSHybugger debug service -->
<service android:name="org.jshybugger.DebugService"
		 android:exported="false"
		 android:enabled="true"/>

and change your acticity code to connect the webview to jsHybugger and prefix the url with content://jsHybugger.org/

// attach web view to debugging service 
DebugServiceClient.attachWebView(webView, this);

// load html resource via jsHybugger
webView.loadUrl("content://jsHybugger.org/file:///android_asset/www/index.html");

For PhoneGap add the following lines to your phonegap configuration (config.xml) file.

<!--  since cordova 2.6 - disable access origin check -->	
<access origin="*"/>

<!--  increase load timeout to 60 seconds -->			
<preference name="loadUrlTimeoutValue" value="60000" />

Take also a look at the examples in the GitHub repository and the How to use page on this site.

Important: If you are using large js files (non minified JS-libraries i.e. jquery), you should launch (Eclipse: Debug As Android Application) the app not in debug mode (first run only) for better instrumentation performance. After the app is executed once, the instrumented code files are cached and re-used on the next runs.


jsHybugger GUI

jsHybugger doesn’t provide it’s own GUI, instead you can use two well known programs for debugging

  • Chrome Browser + Developer Tools
  • Eclipse + Chrome DevTools Extension

Theoretically you can also use any other frontend as long it supports the Chrome Remote Debugging Protocol.

The jsHybugger Server will listen on TCP port 8888. To connect your GUI to the jsHybugger server you have two options:

  • use the Wi-Fi IP address of your phone to connect jsHybugger i.e. http://<phone_ip>:8888. You will find the Wi-Fi IP address on the jsHybugger start screen.
  • use ADB (android platform tool) to forward port 8888, and connect to http://localhost:8888
    1. Install the Android SDKThe Android DevTools (ADT) will provide you with the Android SDK out of the box. Once you’ve downloaded the ADT, unzip it to a directory on your system (e.g “Tools”).
    2. Enable USB debugging on your deviceIn order to debug over USB, you need to setup your Android device for development. Enable USB debugging on your device then system to detect your device as mentioned in the guide.To enable USB debugging:
      • On most devices running Android 3.2 or older, you can find the option under Settings > Applications > Development.
      • On Android 4.0 and newer, it’s in Settings > Developer options.
      • On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.
    3. Connect your device via USB
      cd <android SDK>/platform-tools 
      adb forward tcp:8888 tcp:8888
      
    4. Now open desktop Chrome and navigate to http://localhost:8888