About Drosera

Drosera is a JavaScript debugger for WebKit that can be used with any application that uses WebKit. Like the Web Inspector, over 90% of it is written in HTML, CSS and JavaScript.

Getting Drosera

Drosera is included with all of the WebKit nightly builds, or you can build it yourself by running the build-drosera tool found in WebKitTools/Scripts.

Enabling Drosera

Drosera requires the Safari 3 Beta or one of the nightly builds. It cannot be used with Safari 2.

If you are using a nightly build of WebKit, Drosera is already enabled for you.

To allow Drosera to attach to Safari 3, enter the following command in Terminal:

defaults write com.apple.Safari WebKitScriptDebuggerEnabled -bool true

If you would like to debug your own WebKit-based application using Drosera, simply replace com.apple.Safari in the above command with your own application's bundle identifier or add the WebKitScriptDebuggerEnabled with a value of true to your Info.plist.

Using Drosera

Once Drosera is launched, you're presented with the Attach window, showing all running applications capable of being debugged with Drosera. Select the application you want to debug to load the debugging window.

Breakpoints

Double clicking a line number in the editor window sets a new breakpoint. To delete a breakpoint, simply drag the breakpoint arrow from the line number.

The breakpoint popup allows you to enable/disable the breakpoint, view how many times the code path has been reached, and whether to pause code execution or log output to the console when the breakpoint is reached. When pause is selected, you may enter JavaScript to be evaluated for conditional breaking, while log mode will evaluate any JavaScript and log its output to the console.

Console

Drosera's console is similiar to the JavaScript console in the Safari debug menu and shows the same errors and warnings. Breakpoints set to log mode allow output to be displayed in the console, and while a script is paused, JavaScript can be executed directly in the console.

Function and Variable Stacks

While a script is paused, you can examine the contents of the variables within various scopes of the code.

Drosera on Windows

Most of Drosera has been ported to windows and can now run and attach to a Safari on Windows instance. Drosera is not currently in a nightly and will need to be built from the source.

Design

Drosera

Much of the design of Drosera on Windows is intentionally extremely similar to the design of Drosera on Mac, however, because of the many small differences, for clarity, this section will only focus on the design on Windows without identifying the divergences.

TheDrosera class initializes the UI, sets up its own WebView where it shows its JavaScript, and creates a DebuggerClient class which it polls repeatedly, waiting for the DebuggerClient to establish a connection with a WebKit app that can be debugged.

The DebuggerClient primarily, acts as the UI and FrameLoad delegate for Drosera's main window and also the Console window. The DebuggerClient also passes UI Commands to the DebuggerDocument to be executed in Drosera's own JavaScript, and owns the DebuggerDocument.

The DebuggerDocument is the object that interacts directly with the ServerConnection and Drosera's own JavaScript. The DebuggerDocument has a set of callbacks that Drosera's own JavaScript can call which then call platform-dependent versions of a given function to execute their request. The DebuggerDocument also has functions that allow other objects, like the ServerConnection object, to make calls into Drosera's own JavaScript.

The ServerConnection object implements IWebScriptDebugListener and encapsulates all of the interactions with the remote WebKit server.

WebKit

This section describes the design of the parts of Webkit, and JavaScriptCore that exist to allow Drosera to interact with WebKit.

In WebKit there is a WebScriptDebugServer which is started when WebKit starts and listens for a DCOM connection. Once a connection is made it will begin to interact with Drosera via Drosera's ServerConnection class. WebScriptDebugServer informs Drosera about every line of JavaScript executed.

The WebScriptDebugger is also in WebKit and is told by JavaScript when a line of code is executed and keeps state information locally then informs the WebScriptDebugServer about the executing JavaScript.

In JavaScriptCore there is a debugger class that only is instantiated if Drosera connects to the WebScriptDebugServer and if so it tells the WebScriptDebugger when JavaScript is executing.

Two classes that WebScriptDebugger uses to keep track of the JavaScript state are WebScriptCallFrame, which represents a JavaScript call frame and can process javascript with respect to that call frame, and WebScriptScope, which provides the variable names and values for a given call frame.

Pause Example

When "pause" is selected from the toolbar command in the UI a message is received by the Drosera class which passes the command onto the DebuggerClient which uses the DebuggerDocument to directly call pause in Drosera's own JavaScript. Drosera's JavaScript set's a local variable and then tells the DebuggerDocument to pause by calling the appropriate callback method. This method calls the platform dependent version of pause which tells the ServerConnection object to pause, who, in turn, uses a remote procedure call to tell webkit it wishes to pause it. The WebScriptDebugServer sets an internal variable and then returns to normal execution.

If JavaScript source is parsed, about to execute a statement or exiting a function, the JavaScriptCore debugger class will notify the WebScriptDebugger. The WebScriptDebugger will update it's internal state (increasing or decreasing the stack depth if necessary) and then call the appropriate WebScriptDebugServer function to represent what occurred in the JavaScript. The WebScriptDebugServer will notify any listeners it has of the even in JavaScript, which may or may not cause subsequent calls back into the WebScriptDebugServer from Drosera, or cause more JavaScript to be executed, but upon finishing the notification of listeners of the original JavaScript event the WebScriptDebugServer will check if it has been told to pause. If it has, it will stay in a look that only listens for new instructions from the remote debugger. Once Drosera tells the WebScriptDebugServer that it is no longer paused, WebKit's execution will continue as normal.