JavaScriptDebuggingToolsFunctionalSpecs

Contents


DRAFT

NetBeans 6.5 JavaScript Debugging Tools Functional Specs

Introduction

This document described the functionality of the JavaScript debugging tools that will be available in the NetBeans 6.5 IDE.

Requirements and Assumptions

  • The JavaScript Debugging tools (see the tools section) will be a collection of tools available in the NetBeans 6.5 IDE for debugging, inspecting and monitoring web applications running in the desktop browser.
  • The JavaScript Debugging tools integration will be available for:
  • Web (J2EE) projects
  • Ruby on Rails project
  • PHP projects
  • Grails projects (?)
  • The JavaScript debugging tools will be available as part of the standard NetBeans IDE bundles.
  • The JavaScript Debugging tools will be available as an optional service under the control of user through the Plugin Manager. This requirement originated from the PHP IDE bundle requirements.
  • The JavaScript debugging tools will be available for debugging a web application at an arbitrary URL.

Tools

The JavaScript debugging tools comprises of the following set of tools:

  • JavaScript Debugger - the JavaScript Debugger provides the user the ability to debug the JavaScript code running inside web application in the web browser.
  • HTTP Monitor - the HTTP Monitor tools provides the user the ability to view the HTTP (including the AJAX) request/response traffic between the browser and the server(s).
  • DOM/CSS Inspector - the DOM/CSS Inspector provides the user the ability to view the DOM of the web pages in the web browser. It allows the inspection of the styles associated with the selected elements in the DOM. The DOM in this instance is the dynamic DOM which may have resulted from changes resulting from the script execution.

Supported Tools vs. Browser vs. Platform Matrix for NetBeans 6.5

Browser Platforms Supported Tools
Firefox Solaris, Linux, Mac OS, Windows XP, Windows Vista JavaScript Debugger, HTTP Monitor, DOM/CSS Inspector
Internet Explorer 7 Windows XP, WIndow Vista JavaScript Debugger


I18N/L10N

All the user visible messages of the JavaScript debugging tools will be fully I18Ned so that that localizations teams can implement the L10N. (TBD - expand)

TBD - describe the issues related to encoding as they relate to the NetBeans IDE, the Web Browser and the Web Applications that can be debugged using the JavaScript debugging tools.

Accessibility

All the user interface of the JavaScript debugging tools will be fully accessible. (TBD - expand)

Functional Specs

Build

The JavaScript Debugging tools will be part of the regular NetBeans 6.5 IDE builds.

Installation and Packaging

The JavaScript debugging tools are supported for several project types. Therefore the JavaScript debugging tools will be part of the cluster that is shared across several NetBeans IDE bundles - more specifically Web & Java EE, Ruby and PHP. The most likely candidate for this is the "ide9" cluster. Thus the JavaScript debugging tools will be available in all the NetBeans IDE bundles.

Issue: what about pure the Java SE NetBeans IDE bundle? Do the JavaScript debugging tools make sense for the Java SE NetBeans IDE bundle? This issue applies to the JavaScript editing support also. Issue: How is the Grails project support going to be packaged in NetBeans IDE? Which bundle?

Optional Component

The JavaScript debugging tools will be an optional component under the control of the NetBeans IDE user. The JavaScript debugging tools will use the standard mechanism of a kit to allow the user to enable and disable the JavaScript debugging tools through the NetBeans IDE Plugin Manager. When the user deactivates the JavaScript Debugging tools through the Plugin Manager all the associated GUI elements will be removed and the the functionality will not be available to the user in NetBeans IDE.

Image:JavaScriptDebuggingToolsKit_JavaScriptDebuggingToolsFunctionalSpecs.png

Issue: Will the JavaScript debugging tools, by default, be enabled for certain NetBeans IDE bundles vs., by default, be disabled for other NetBeans IDE bundles (e.g. PHP IDE)? Does the NetBeans IDE installer provide such ability?

Integration with NetBeans Projects

The integration of JavaScript debugging tools with the NetBeans projects will be provided through an additional category called Debug in the project properties dialogs (see below). This category is visible when the JavaScript Debugging tools are in activated state. The user has the choice of debugging the server side of the application, client side of the application or both. Based on the selection the server side and/or client side debugging sessions will be launched when the debug actions are invoked.

When the user deactivates the JavaScript Debugging tools through the Plugin Manager the Debug category in the Project Properties dialog will not be shown. The Debug Main Project and Debug File actions will only launch the server side debugging session.

JavaScript Debugger support for Internet Explorer

On the Windows platform, the user has the choice of selecting either the Firefox Browser or the Internet Explorer for client side JavaScript debugging.

HIE Issue: What should happen to the Internet Explorer radio button on platforms other than Windows platform where it is not available? Should the radio buttons be simply not shown that case? In it's place the label for the client side debugging check box could be updated to reflect Firefox as the only choice?

Web (J2EE) Project

Image:WebProjectPropertiesDebugCategory_JavaScriptDebuggingToolsFunctionalSpecs.png

Ruby on Rails Project

Image:RailsProjectPropertiesDebugCategory_JavaScriptDebuggingToolsFunctionalSpecs.png

PHP Project

Image:PHPProjectPropertiesDebugCategory_JavaScriptDebuggingToolsFunctionalSpecs.png

Grails Project (TBD)

Breakponts

The user will be able to set/unset the breakpoints in the JavaScript functions using the Run:Toggle Line Breakpoint (Ctrl-F8) action in the menu bar:

Image:RunToggleLineBreakpointAction_JavaScriptDebuggingToolsFunctionalSpecs.png

or the Toggle Line Breakpoint (Ctrl-F8) action in the HTML or JavaScript editor context menu:

Image:ToggleLineBreakpointPopupMenuAction_JavaScriptDebuggingToolsFunctionalSpecs.png

The breakpoint will be shown in the HTML and JavaScript editor's left side gutter using the standard breakpoint icon(s).

Image:HtmlEditor_JavaScriptDebuggingToolsFunctionalSpecs.png

Image:JavaScriptEditor_JavaScriptDebuggingToolsFunctionalSpecs.png

The JavaScript Debugger primarily works with the HTML and JavaScript code as seen by the browser. In case of pure HTML pages and JavaScript files that are sent to the browser verbatim it is possible to map the HTML and JavaScript source seen by the browser to the corresponding artifacts in the NetBeans Web project. In such cases the user will work with the source editor of those project artifacts for setting breakpoints etc. Similarly the source editor for the project artifact will be used to show the current call stack frame annotation as the user steps through the JavaScript code. However, in certain cases, such as web page resulting from a JSP page, it is not always possible to map the HTML seen by the browser to the JSF page source artifact in the project. In such cases the content of the HTML page as seen by the browser will be loaded in a virtual buffer which will be opened in the HTML editor. The user will use this HTML editor window, to set breakpoints or while stepping through the code. The breakpoints set in such a buffer will be expressed in terms of the corresponding URL as seen by the browser and will appear as such in the Breakpoints window. Similarly the Sources window will show the URL as seen by the browser.

The breakpoint will also be listed in the Breakpoints window.

Image:BreakpointsWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Breakpoints action shows Breakpoints Window.

When the debugger is running the Resolved location column shows the URL as seen by the browser.

The breakpoints can be customized using the following breakpoint customizer:

Image:CustomizeBreakpoint_JavaScriptDebuggingToolsFunctionalSpecs.png

The customization dialog allows setting of hit count, hit count filter and/or condition expression. When a condition expression is specified, the breakpoint stops only if the condition expression evaluates to true. You can use !(condition) to negate the sense of condition.

NOTE: The New Breakpoint... action does not apply to JavaScript. The action is added by the Java debugger support. Unfortunately it cannot be disabled.

CAUTION: You will be able to set breakpoints in .jsp, .rhtml or .php files. But these are server side breakpoints.

debugger
keyword support

The JavaScript execution can be suspend by inserting the
debugger;
statement in your JavaScript code if the Suspend on Debugger keyword is selected in the Tools:Options dialog.

Launching of JavaScript debugging tools

Debug Main Project and Debug File Actions

If the user has selected the Debug Client Side checkbox in the Debug category of the project properties dialogs - the JavaScript debugging tools will be launched when the user invokes the Debug Main Project or the Debug File Action. On windows, depending on the user selection the web application will be run in the Firefox browser or the Internet Explorer. On other platforms Firefox will be used to launch the web application.

On windows platform the user may want launch the Firefox and Internet Explorer debugging sessions simultaneously. One way to do that is to launch the first (Firefox or Internet Explorer based on the current selection) debugging sessions, going to the project properties dialog to change the selection and launching the second session (Internet Explore or Firefox). However this is cumbersome. To avoid that the following explicit actions will be supported on the Debug toolbar:

Image:DebugMainProjectMenu_JavaScriptDebuggingToolsFunctionalSpecs.png

HIE Issue: Is this complicated UI necessary? For simplicity we could not use this. Need HIE input here.

Detection and Installation of Firefox Browser extension

The JavaScript debugging tools for Firefox are implemented using a Firefox extension which works in conjunction with the popular Firebug 1.1beta+ debugger. Therefore before starting the tools a check for presence of the Firebug 1.1beta+ and NetBeans Firefox Extension will be performed. If not found the following message dialog will be shown:

Image:InstallFirefoxDebuggerExtensionsBoth_JavaScriptDebuggingToolsFunctionalSpecs.png

and an automatic installation of the extensions will be started. Depending on whether the user already had Firebug 1.1beta or later installed or not the following dialogs will be shown.

Image:NetBeansFirefoxExtensionInstallation_JavaScriptDebuggingToolsFunctionalSpecs.png

Image:FireBugInstallation_JavaScriptDebuggingToolsFunctionalSpecs.png

After the user installs the extensions and restarts the Firefox, the NetBeans Firefox extension can be seen in the Firefox add-on dialog:

Image:Add-ons_JavaScriptDebuggingToolsFunctionalSpecs.png

NetBeans Firefox Extension icon is shown in the Firefox Status bar:

Image:NetBeansFirefoxExtensionStatusBarIcon_JavaScriptDebuggingToolsFunctionalSpecs.png

NetBeans Firefox Extension icon has a popup menu action to show the NetBeans Firefox Extension's About dialog:

Image:AboutNetBeansFirefoxExtension_JavaScriptDebuggingToolsFunctionalSpecs.png

After this the debugging session can start.

Installation of Internet Explorer

The JavaScript debugger for Internet Explorer is implemented using a Browser Helper Object (aka BHO) implemented as a .dll that works in conjunction with the Microsoft Script Debugger component. A similar check for presence of the NetBeans BHO and the Microsoft Script Debugger component will be performed. If the Microsoft Script Debugger component is not found the user will be instructed to download and install it. If the NetBeans BHO is not found, it will be installed with user's consent.

After this the debugging session can start.

TODO - Screenshots

Debugging Window

The Window:Debugging Menu has the actions to open debugging tools windows.

Image:WindowDebugging_JavaScriptDebuggingToolsFunctionalSpecs.png

When the debugging session starts a default set of windows in a default layout will be opened by the NetBeans IDE.

HIE Issue: Should we handle this in a special way for JavaScript debugger? Should we show the sessions window when the user has selected the server side and client side debugging so that the user sees the two sessions in the Sessions window?

JavaScript Debugging

Image:SessionsWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Sessions action shows the Sessions window.

Debugger Actions

The following screenhot shows the Debug toolbar when the debugger is suspended:

Image:SuspendedStateToolbar_JavaScriptDebuggingToolsFunctionalSpecs.png

The following screenhot shows the Debug toolbar when the debugger is not suspended:

Image:RunningStateToolbar_JavaScriptDebuggingToolsFunctionalSpecs.png

The debugger actions:

  • Finish Debugging Session - obvious
  • Resume - after a breakpoint (Enabled when the debugger is suspended)
  • Pause - the debugger will suspend at the next execution of JavaScript
  • Step Over - step over a JavaScript line.
  • Step In - step into a function call in a JavaScript line.
  • Step Out - step out of the current function call
  • Run to Cursor - is not currently supported

Sources window

Sources window shows the loaded scripts/files. For .html and .js files in user's project the debugger will automatically show the file object's path. The Go to source action opens the script in an editor. For remote resources the URL path of the file will be shown. This is also true for pages rendered as a result of .jsp file in user's project. Go to Source action on such sources will show the file in a read-only editor. The content of the editor is same the content in Browser's cache.

Image:SourcesWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Sources action shows the Sources window.

If the user has turned off the browser disk cache, the user will see a blank editor as the content of the URL cannot be obtained.

Threads window

In JavaScript each Window or a Frame is an execution context for JavaScript. The Threads window will show the Window and Frame structure of the page. The Go to Source action opens the source of the window or frame in an editor tab. The comments about remote resources in the Sources window above apply here also.

Image:ThreadsWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Threads action shows the Threads window.

Threads window showing a multi framed web page:

Image:ThreadsWindowMultiFrame_JavaScriptDebuggingToolsFunctionalSpecs.png

Call Stack window

When the debugger is suspended, the Call Stack window shows the call stack. Go to Source action shows the source of the script associated with the Callstack frame. When the debugger suspends for any reason, initially the top most stack frame will be selected automatically. The local variables of the selected Callstack frame will be shown in the Local Variables window. The watches configured in the Watches window will be evaluated in the selected Callstack frame. Double clicking on the Callstack frame selects it. Then it's Local Variables and values of watches in that context can be explored.

Image:CallStackWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Call Stack action shows the Callstack Window.

The call stack frame locations are also annotated in the editor windows:

Image:CallStackAnnotations_JavaScriptDebuggingToolsFunctionalSpecs.png

Local Variables window

When the debugger is suspended the Local Variables window shows the local variable of selected Callstack frame. It shows two top nodes:

  • scope - scope of the function call of the current call stack frame
  • this - the value of this

The scope node is always expanded. Aside from showing local variables and parameters of the function call associated with the selected Callstack frame the following additional nodes are shown:

  • arguments - so that user can see actual arguments - which may be less or more than the declared formal parameters
  • arguments.length - so that user can see number of actual arguments passed in
  • arguments.callee.length - so that user can see expected number of arguments as declared in the function signature
  • parent scope - information about outer scope
  •  :
  •  :
  • parent scope - information about outer scope of outer scope and so on.
  •  :
  •  :
  • parent scope - information about outer scope of outer scope of outer scope and so on.

Image:LocalVariablesWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Local Variables action shows the Local Variables window.

As the user steps through the code the values of some local variables may change. Such local variables are shown in bold in the Local variables window.

Image:LocalVariablesWindowNextGeneration_JavaScriptDebuggingToolsFunctionalSpecs.png

Watches Window

Arbitrary JavaScript expressions can be used as watches. The debugger will evaluate the watch expressions in the context of selected Callstack frame and if successful display the value of the expression in the Watches window. The user can add and remove the watches using the actions in the Watches window's popup menu. The user can also add new watches using the New Watch... action in the editor's popup menu.

Image:WatchesWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:Watches action shows the Watches window.

HTML and JavaScript editor

  • Data tool tips when the debugger is suspended

When the debugger is suspended the user can hover the caret over a JavaScript identifier in the editor and if the identifier is valid in the selected call stack frame it's value will be displayed in a tooltip. The user can select a javascript expression. The value of the expression will be shown in a tooltip.

Image:Tooltip_JavaScriptDebuggingToolsFunctionalSpecs.png

URL Debugging

Debug URL action

The user can debug an arbitrary URL using the Run:Attach Debugger... action. The action will show a dialog with possible attaching debuggers in a combobox. Seleting __JavaScript Debugger_ in the combobox shows a textfield to enter the URL of the application to be debugged. After entering the URL (e.g. http://www.netbeans.org) and clicking OK button starts the URL debugging session.

Image:AttachDebugger_JavaScriptDebuggingToolsFunctionalSpecs.png

Sources window

While debugging a URL like this the Sources window will show the URL paths of the .html and .js resources.

Image:RemoteSourcesWindow_JavaScriptDebuggingToolsFunctionalSpecs.png

HTML and JavaScript editor

For remote resources a read-only editor will be shown. The Editor tab will show the shortened URL path. The tooltip on the tab will show the full URL path. The user can set the breakpoints in remote scripts using the same mechanism as the file editor (see Breakpoints section above).

Image:RemoteJavaScriptEditor_JavaScriptDebuggingToolsFunctionalSpecs.png

JavaScript Debugging Tools Options

Image:JavaScriptToolsOptions_JavaScriptDebuggingToolsFunctionalSpecs.png

Suspend on First Line

When selected the JavaScript debugger suspends on the first line of JavaScript execution in the web application.

Image:SuspendOnFirstLine_JavaScriptDebuggingToolsFunctionalSpecs.png

Suspend on Exceptions

When selected the JavaScript debugger will suspend when the JavaScript code throws an exception.

Things to note:

  • an Error object thrown on line 14 in the source code.
  • the Session window shows the correct reason of suspension
  • the local variables window shows the exception using the node [[[exception | [exception]]. As you can see you can expand the exception object to show it's properties.

Image:SuspendedOnException_JavaScriptDebuggingToolsFunctionalSpecs.png

Suspend on Errors

TBD

Suspend on Debugger Keyword

When selected the JavaScript debugger suspends on the execution of
debugger;
statement in JavaScript code.

Image:SuspendOnDebuggerKeyword_JavaScriptDebuggingToolsFunctionalSpecs.png

Client HTTP Monitoring

The HTTP monitor shows the HTTP requests and responses between the Firefox browser and the servers. This includes the AJAX requests and responses.

Image:http_monitor_window_JavaScriptDebuggingToolsFunctionalSpecs.png

TODO: Fill in details.

The Window:Debugging:Client HTTP Monitor action shows the Client HTTP Monitor window.

DOM/CSS Inspector

NOTE: This will not be implemented for 6.5

The DOM/CSS inspector window shows the full dynamic DOM and CSS styles selected element for the web application page running in the Firefox browser. The DOM/CSS Inspector window has two panes separated by a split name - the DOM view and CSS view. The DOM view shows a single tree structure that represents the DOM for the top level window (tab) including any child frames and iframes enclosed in the top level window (tab). The DOM view shows the dynamic structure of the DOM. As and when the DOM of the web page changes the DOM view is updated. A new DOM tree is loaded when the user navigates to a new page e.g. by following a hyperlink. Selecting the elements in the DOM view (temporarily) highlights the corresponding elements in the Firefox browser. The style and layout related information of the selected DOM element is shown in the Style and Layout tab of the CSS view. The Style tab shows shows the information about the CSS styles including the cascading. The Layout view shows the CSS box model information. The raw source of the DOM can be shown an editor window.

Image:DOMCSSInspectorLayout_JavaScriptDebuggingToolsFunctionalSpecs.png

The Window:Debugging:DOM/CSS Inspector action shows the DOM/CSS Inspector window.

General Issues

  • How do the JavaScript debugging tools relate to the JavaScript Library support and JMaki framework in terms of clusters, kits and modules?
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo