Web App Development

Aardwolf - source-level remote Javascript debugging

Aardwolf is a Javascript debugger that can be used to step through code on a mobile device.

This post explains how to run it on a server and access the debugging UI.

Installing Aardwolf

First use ssh to login to your server. The Aardwolf page on Github describes the installation very well:
1) Begin by installing node.js and Git
2) Get the Aardwolf source code from GitHub: git clone git://github.com/lexandera/Aardwolf.git
3) Download the required libraries by running "npm link" in the checked-out directory
Installing node.js and git will vary by the package manager of your linux distribution. With Aptitude use these apt-get commands:

sudo apt-get install npm
sudo apt-get install git

After running the git clone command you will have an Aardwolf folder in your working directory.

Preparing your code

Aardwolf will serve the code of your mobile app from the server. Before sending the files to the client it modifies them to enable step-by-step debugging.

You can use, for example,FTP to upload the code. I used a public file on Dropbox:

wget https://dl.dropbox.com/u/12345/code.zip
unzip code.zip

You will need to make one modification to the html file that contains your app. It needs to load some Javascript code that will be served at /aardwolf.js:
<script src="/aardwolf.js"></script>
Make sure to include this file before all other Javascript code that is loaded from the server. The code as modified by Aardwolf will depend on an Aardwolf object.

Launching the remote debugger

Open the app.js file in the Aardwolf folder with node.js, passing the IP address of the server as the -h parameter and the directory containing the code of the mobile app as -d.

node app.js -h 12.34.567.89 / -d /home/whatever/code

Open 12.34.567.89:8000 in your browser to see the debugger UI.

You can open the app instance itself on your phone. Assuming the html file that you added the /aardwolf.js file to is called index.html open this URL in the browser: 12.34.567.89:8500/index.html

Try entering alert('test') in the Console box and click eval to see if it's working. (You should also see a "Mobile device connected." message).

Problems I ran into

XMLHttpRequest Exception

Sometimes I got this error message in the mobile browser:
Aardwolf encountered an error while sending data: Error: NETWORK_ERR: XMLHttpRequest Exception 101
The cause was a wrong IP address entered as the -h parameter to the application.

Getting no response from the mobile device

The mobile device would go to sleep for a short time and somehow the connection would be lost. After reloading the page in the mobile browser it started working again.


Follow me on Twitter
I'm building monitoring tool for site speed and Core Web Vitals.
➔ Start monitoring your website or run a free site speed test