Debugging JavaScript in the MoSync SDK

The MoSync IDE features a fully-featured debugger for JavaScript code. You can set breakpoints in your code, install and run your application package on a device, and then see the code as it executes in the MoSync IDE. To use the debugger you need to use the Debug build configuration when building your package.

Debugging Options in the MoSync IDE

You can debug both C/C++ code and JavaScript code in the MoSync Eclipse-based IDE. For instructions on C/C++ debugging, see Using the C/C++ Debugger; for instructions on using the JavaScript debugger, continue reading.

JavaScript debugging only works with HTML5 projects that have a folder called /LocalFiles in the project root. This folder is automatically created if you select one of our HTML5 project templates (see Creating Projects from Templates.)

JavaScript debugging is supported on Android and iOS devices and simulators/emulators.

General guides and tutorials related to the debugging and troubleshooting of applications can be found in our online documentation in the section called Debugging, Testing, Performance.

Setting up the Debugger

1. Check that JavaScript debugging is enabled by right-clicking on your project in Project Explorer view and selecting Enable JavaScript Debugging. (This is only necessary for projects created prior to 3.2.) If no such menu item can be seen, the project is not a JavaScript project or it does not have a LocalFiles folder.
2. Set the current build configuration to “Debug”.
3. Make sure that the build setting Use Debug Runtimes in Project > Properties > MoSync Project > Build Settings > Packaging is selected.
4. Make sure that debugging is enabled; open the preferences dialog and select MoSync Tool > JavaScript On-Device Debug > Enable JavaScript On-Device Debug.

Setting a Breakpoint

The JavaScript Debugger supports three types of breakpoints:

• Line breakpoints (in .js and .html files) — lets you stop program execution at the line number you select.
• Script load breakpoints — lets you stop execution when a script loads. The execution will stop before the first line of the script is executed.
• Suspend upon exception — when enabled, suspends the script whenever an exception is thrown in the code.

The debugger also supports breakpoint conditions and hit counts.

Setting a Line Breakpoint

To set a line breakpoint, double-click the margin of the line you want to set a breakpoint at.

Setting a Script Load Breakpoint

To set a script load breakpoint, click the script load breakpoint icon in the Breakpoints view.

(If you cannot see the breakpoints view, open the Debug perspective: Window > Open Perspective > Other... > Debug. Unless the IDE has been configured otherwise, you will be asked to open this perspective when a breakpoint is hit.)

Enabling Exception Breakpoints

To enable suspend upon exceptions, open the Preferences dialog and select JavaScript > Debug > Suspend On JavaScript Exceptions. This is enabled by default.

Setting Breakpoint Conditions and Hitcounts

To set conditions and hitcounts for a line breakpoint, right-click on the breakpoint marker in the line margin.

For script load breakpoint you can set conditions in the “Breakpoints” view.

When set, the hitcount will stop the breakpoint to suspend execution until it has been hit the specified number of times.

If a condition is set, the breakpoint will suspend execution only if this condition is met. There is an option to suspend execution if the condition either a) evaluates to true, or b) it changed since last time the breakpoint was hit.

Running the Debugger

To start the debugger, make sure that debugging is enabled as per the instructions above in “Setting up the Debugger”.

Next, the device must be able to connect to the debug server. For emulators, this is usually not a problem since they run on the same computer as the debug server. For devices sharing say a Wi-Fi connection with the computer the debug server runs on should be enough. You may need to enable Wi-Fi on your device.

Start the app by clicking either the Send to Device button (for on-device debugging, for more information see http://www.mosync.com/documentation/manualpage/sending-device):

Or the Debug (for on-simulator debugging) button:

Follow the on-screen instructions, if any.

If a breakpoint hits, you will see something like the image below. The red arrow points to a where the breakpoint was hit and execution suspended.

Inspecting Variables

Once execution suspends, you may inspect the variable scope at that point in the program. Just open the Variables view (which by default is visible as a tab to the right in the Debug perspective).

All the variables in the local scope are visible, including local variables and arguments to functions. The content of structures and arrays can be expanded by pressing the + sign next to them.

By clicking a stack frame you will be able to inspect the scope at any stack depth of the execution.

Stepping

Once a breakpoint is hit, you may perform these special debugger actions:

• Step Into executes the next line in the program, regardless of where this line is located.
• Step Over — If the next line to execute enters a function, the execution will suspend once that function has exited.
• Step Return executes the rest of the function and returns to the caller.
• Drop to Frame rewinds execution to a previous point in the program. To use Drop To Frame, select one of the stack frames (where the red arrow points in the image above) and press the corresponding tool icon. The execution will rewind to the start of the function being suspended.

These actions can be performed by pressing the corresponding icons in the toolbar (in the same order as the list above):

Suspend Execution

To suspend execution at any point of time, press the Suspend icon:

This will cause the JavaScript execution to suspend at the earliest possible time.

Terminate Execution

To terminate the program being debugged, press the Terminate icon:

This will terminate the program on the device.

Evaluation

There is an option to evaluate arbitrary JavaScript code. This can be done in two ways:

1. From the console view (where log messages appear). Just type the JavaScript expression to evaluate and press enter. The evaluation result will appear in the console.
2. By selecting some text in a JavaScript file, then right-click and select Evaluate JavaScript.

If execution is suspended, the JavaScript will be evaluated in the scope of the top stack frame.
Please note that any evaluated JavaScript expression that modifies the UI will take effect once execution starts again.

Hot code replace

The JavaScript debugger offers basic ”Hot Code Replace” functionality. When a file is changed in a project, the client will refresh and reload those files. To change this default behaviour, open the Preferences dialog and select Do Nothing in the MoSync Tool > JavaScript On-Device Debug > When source code changes list box.

Note: for version 3.2 only HTML (.html) and JavaScript (.js) files are updated on the device/emulator. To update any other files you need to rebuild and upload the app again.

To refresh and reload even though Do Nothing is selected, select the current launch in the Debug view and press the corresponding Reload toolbar icon:

Troubleshooting

• “I cant debug at all” — Check that the device is connected to the same network as the debug server. If it is not and if you can’t connect it, you could try to debug using an emulator instead of a real device.
• “My program seems to hang on the device but no breakpoint has been hit in the debugger” — Sometimes the client and server gets out of sync. Try to reload the program as described in the section Hot code replace.
• “When I step one line, I occasionally end up in a completely different place in the code” — Due to the single-thread nature of JavaScript, the step into, step over and step return operations may have this result, but it happens only rarely. Especially timed executions triggered by the JavaScript setTimeout function suffer from this problem. We plan to fix this in future releases of the MoSync JavaScript On-Device Debugger.
• "I just went to grab some coffee and now I get some error dialog saying my session timed out" — If something causes the app being debugged is sent to the background, the IDE will lose its connection and within half a minute or so it will time out.