Setting up Debugging of the Chrome DevTools App

Here are some notes-to-self on setting up debugging of the Chrome DevTools app, based on these Chrome Developer tools notes.

Note that if you just want to open another instance of DevTools on an existing instance of DevTools (for example, just to see the generated html for the DevTools screens themselves), you can do this by just using the keyboard shortcut while you are in DevTools itself. On a Mac, this is Cmd+Opt+I. If I had realized this earlier, I probably would not have even gotten into the details for this post, which deals with (among other things) modifying the DevTools app. An interesting diversion, though.

While debugging DevTools can be done on just about any OS, the stuff below is on Mac OS.

Get the DevTools Source

DevTools is just a javascript/css/html app. Which is cool.

The code for it is under the Blink project, which itself is the rendering engine for Chromium/Chrome.

In order to get the Devtools app, first get the Blink source code (docs say it can take 30-60 minutes - I don't remember how long it took for me):

git clone https://chromium.googlesource.com/chromium/blink

...then cd into the blink/Source/devtools directory and serve devtools with a web server. I use Python's SimpleHTTPServer, although I have to look up the case-sensitive spelling every time:

Brad-Lyons-iMac:devtools bradflyon$ pwd
/Users/bradflyon/Documents/blink/Source/devtools
Brad-Lyons-iMac:devtools bradflyon$ python -m SimpleHTTPServer 8080

The js/css/html files for DevTools are in the blink/Source/devtools/front_end directory. The main file that stuff runs within is inspector.html. This file pulls in a handful of css files, about 150 javascript files, and has a short body block - just a "regular" html file. This is cool.

<!doctype html>
<html>
<head>
   <!-- include some css -->
   <!-- pull in lots of javascript files -->
</head>
<body class="undocked" id="-blink-dev-tools"></body>
</html>
Summary of Contents of blink/Source/devtools/front_end/inspector.html

Run a "Canary" Build of Chrome

Canary is a special version of Chrome - this is not the "normal" stable version, but instead has many of the newer features built into it. There is an even more of a bleeding edge version of Chrome, but Canary sits somewhere in between stable and the bleeding edge. The word "Canary" is used in reference to canaries being used in coal mines to provide early warning of deadly gases. A nice summary article on Chrome Canary by Steve Campbell is here. I love the way Google used color on the icon for it.

The instructions for setting up debugging with and contributing to DevTools mention running an edge build, but I haven't found that necessary. I was thinking that maybe it's the same thing as Canary, but then maybe by "edge build" they mean the "raw build" that is built "right off the trunk" and "may be tremendously buggy", which you can get at https://download-chromium.appspot.com/. I found the docs confusing on this point, but - again - Canary seemed to work for me so far in my limited tinkering with this.

You can get Canary from https://www.google.com/intl/en/chrome/browser/canary.html

To set up things so that you can use the DevTools web app you downloaded above, you first run Canary in the terminal with some special flags (notice that I use port 8080, since that is where I am serving DevTools from above):

/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary --remote-debugging-port=9222 --no-first-run --remote-debugging-frontend="http://localhost:8080/front_end/inspector.html" --user-data-dir=blink/chromeServerProfile
Running Canary on a Mac for DevTools Hacking
Make sure the --remote-debugging-frontend port is the same you are using for DevTools above (I'm using 8080 here), and you might want to change the location for the --user-data-dir

When you run Canary as noted above, you'll see the browser pop up - here's what it looks like for me the first time:

What Canary looks like when it first opens...

Debug/Tweak/Hack at DevTools - Inception Level 1

This was a confusing part for me. On the DevTools site, they make a reference to the movie Inception, which is appropriate as what you will be doing is using Chrome to inspect itself. You can even inspect it inspecting itself. And inspect that one. Kind of a Canary navel gazing.

To begin, first go to the site localhost:9222. If you're running Canary for the first time per the instructions above (on Mac, at least), you should see a page similar to this:

The "Inspectable pages" screen with no other windows open

Before going further, open a new window in Canary go to some other page in that Window. In my case, I'll go to a page I'm playing with as part of learning more about javascript closures, which is at http://localhost:8083/createObject.html on my machine. After I do this and then refresh the "localhost:9222" page, here is what the "Inspectable pages" page looks like:

Choosing what to inspect

So what happens when you click one of the "Inspectable pages"?

What happens is that an instance of DevTools will open, using the DevTools app you downloaded from Blink, and pointed at the page you clicked on.

You could use this for verifying how your modifications of DevTools are behaving when you use it on other pages.

You can confirm that "your" DevTools is being used by tweaking one of the DevTools files, and restarting the webserver serving DevTools. For example, you could change the application title that controls the tab title, which is in the file blink/Source/devtools/front_end/Settings.js


var Preferences = {
    maxInlineTextChildLength: 80,
    minConsoleHeight: 75,
    minSidebarWidth: 100,
    minSidebarHeight: 75,
    minElementsSidebarWidth: 200,
    minElementsSidebarHeight: 200,
    minScriptsSidebarWidth: 200,
    //Original: applicationTitle: "Developer Tools - %s",
    applicationTitle: "Hey - I Changed Developer Tools - %s",
    experimentsEnabled: false
}
Tweaking DevTools to See an Effect
This is at about line 32 of blink/Source/devtools/front_end/Settings.js

After you make the change above, restart the webserver serving DevTools, then refresh localhost:9222 and pick the file you want to analyze again (there's a chance you'll need to restart Canary from the command line, too, as sometimes it will cache things more than you'd like). In my case, I can how see the effect of my change because the title on the tab is what I changed it to - cool!

I have the power... to change the DevTools title

Debug/Tweak/Hack at DevTools - Inspecting the Inspector

This is the part that really took me a bit to fully appreciate within the context of this toolset. What motivated me to even start looking at this was to see what DevTools is doing under the hood as part of its Heap Snapshot tool, as this would seem to go a long way towards better understanding javascript closures. So, what I need to do is see what DevTools is doing - put in break points, twiddle code to see the effect, etc. To do this here requires an extra step, so that the basic steps are:
  1. Fire up Canary per above
  2. Open the page that the to-be-watched DevTools will be watching
  3. Open DevTools for the page
  4. Go to localhost:9222 and choose to inspect DevTools itself from step 3

Here's what the "Inspectable pages" looked like in my case, where I've added a note about which one to select

Selecting to inspect DevTools itself - keep your totem handy

And here's how things look with the whole gang

"My" DevTools on left,
watching bundled DevTools in the middle,
which is watching a "normal" web page

Note that as of now (12/7/2013), when I have the second instance of DevTools open I can't get local editing to work - the "Add Folder to Workspace" does nothing, and so I am having to edit with an outside editor. However, these changes can apparently be seen by just refreshing the DevTools window, without having to restart anything.

Just the Beginning...

Hopefully, though, this might get you close to poking around with DevTools yourself. Please let me know if I've overlooked something, etc. There's fancier things to do. You could be using your modified DevTools for both of the DevTools involved, for example, and there's debugging, breakpoints, and tons of cool stuff.

Or, as my "Inspectable pages" now tempts, I could keep going...

Epilogue - a Convenience Script

After the stuff is set up per above, starting a new debugging session each time can be initiated with the following little script, which will open up both the page to be looked at and the "Inspectable pages" tab:
#!/usr/bin/env bash
# Startup script for Canary in debug mode
#    so you can debug Chrome DevTools
# (based on https://gist.github.com/hemanth/7611535, which is based
#   on https://medium.com/p/8c8896f5cef3i by Andrey Lushnikov)
#
FRONT_END_DIR=~/Documents/blink/Source/devtools
USER_PROFILE_DIR=chrometest

case "$1" in
    start)
            #If there is no second argument, use a default one
            if [ -n "$2" ]; then
              thePage=$2
            else
              thePage="http://www.google.com"
              echo "Using default page"
            fi
            #Stop the python SimpleHTTPServer if it is running...
            echo "Stopping SimpleHTTPServer if it is running on 8080"
            kill -9 `ps -ax | awk '/[S]impleHTTPServer 8080/{print $1}'` \
                   > /dev/null 2>&1
            pushd $FRONT_END_DIR > /dev/null 2>&1
            python -m SimpleHTTPServer 8080 &
            popd > /dev/null 2>&1
            echo "Starting Canary..."
            #Start Canary - for now, not in the background
            /Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary \
                --remote-debugging-port=9222 \
                --no-first-run \
                --remote-debugging-frontend="http://localhost:8080/front_end/inspector.html" \
                --user-data-dir=$USER_PROFILE_DIR \
                localhost:9222 $thePage
            ;;
    stop)
            #Stop the python SimpleHTTPServer if it is running...
            echo "Stopping SimpleHTTPServer if it is running on 8080"
            kill -9 `ps -ax | awk '/[S]impleHTTPServer 8080/{print $1}'` > /dev/null 2>&1
            ;;
    esac

Popular Posts