HTML5 Mobile Debuggers' Manifesto
Debugging HTML5 web apps on the desktop is amazingly easy. Just fire up Webkit’s dev tools and you’re set. You can inspect the DOM, set breakpoints and step through running code, examine LocalStorage / WebDB. Life is good.
But when you make the leap to mobile devices, things get tricky. Mobile Chrome offers USB Remote Debugging, which makes the Webkit dev tools we know and love accessible on your desktop. But USB Remote Debugging is only available for Android 4 or greater. IOS offers very similar USB remote debugging tools, but again, only for the newest version of the OS.
The best debugging option differs depending on the mobile platform (iOS vs Android), platform version, browser, hardware (emulator/simulator vs physical device) and whether the application is a “raw” HTML5 webapp or is running in Phonegap as a native app.
In developing Ashley Madison’s upcoming New Mobile Experience, we regularly found ourselves fighting with the debugging tools, so we made a chart to document our recommended debugger option. We use it to remind us what tool to use. We’ll introduce the tools and walk you through some basic rules. When you need to debug your HTML5 Mobile App just consult the chart to find the best tool.
Hook up a cable, run some ADB commands, hit a url from your desktop browser. Gold. Unfortunately, this doesn’t work for phonegap applications as the “legacy” Android browser is responsible for rendering phonegap apps.
Just like Chrome’s remote debugging, but for IOS. Unlike the Android solution, this works for Phonegap too!
Launch a website or phonegap app on the IOS Simulator, then use this app to attach to the simulator and bring up full debug tools. Works well, but as it cannot run on an actual iOS device it doesn’t work for every case.
Console.log output generally shows up in Weinre/Chrome/iWebInspector, but often important messages go straight into the system logs. On Android this is accessible via the “adb logcat” command. With your android device connected via usb, on your desktop run “adb logcat browser:V ‘*:S’”. This pipes the logs from the mobile browser to your desktop machine and supresses all non browser log entries. For iOS, it seems the best way to get at these logs is to launch your phonegap app from within XCode.
Some Basic Rules
- As much as possible, always develop, test and debug on the desktop
Get as far as you can without leaving the desktop, using tools to approximate the mobile experience. We use Chrome Canary with the (Beta) Ripple extension and the developer toolbar docked to the right. Ripple emulates a mobile device well enough to use phonegap, but there are limits. For instance, testing APN or C2MD native push notifications really needs to be on the native device. Nor can you test animations and app performance using the desktop. In contrast to the actual device, everything is fast on the desktop.
- Never leave Weinre running when using one of the other debugging options. If your application connects to Weinre, things will go awry.
- Whenever possible use the preferred platform (bolded in our handy chart), and only jump to a platform with more limited debugging options as a last resort. In most cases, that means using IOS 6 Web Inspector for Phonegap applications and/or USB Remote Debugging on Android “Device” Chrome for web applications.
- Don’t blindly trust the tools. Weinre sometimes introduces bugs of it’s own and will sometimes misreport HTTP headers. Always confirm the existence of a bug without the debug tools active.
- The Android emulator is awful. Even on the fastest hardware, it’s unusably slow. Just don’t use it. If you don’t have an Android device, you can’t develop for Android. Sorry.
- Always have both the log viewer (adb logcat or console.app) running as well as the debug tool.
|Mobile Web||Android||4.0+||Physical||Chrome Remote Debug||ADB Logcat|
|Mobile Web||Android||< 4||Physical||Weinre||ADB Logcat|
|Mobile Web||Android||Any||Emulator||Do not use||Do not use|
|Mobile Web||IOS||<= 5||Simulator||iWebInspector||Console.app|
|Mobile Web||IOS||<= 5||Physical||Weinre||Console.app|
|Mobile Web||IOS||>= 6||Physical||Remote Web Inspector||Console.app|
|Mobile Web||IOS||>= 6||Simulator||Remote Web Inspector||Console.app|
|Phonegap||Android||Any||Emulator||Do not use||Do not use|
|Phonegap||IOS||<= 5||Simulator||iWebInspector||Launch within XCode|
|Phonegap||IOS||<= 5||Device||Weinre||Launch within XCode|
|Phonegap||IOS||>= 6||Simulator||Remote Web Inspector||Launch within XCode|
|Phonegap||IOS||>= 6||Device||Remote Web Inspector||Launch within XCode|