Debugging in the Toolkit¶
You can debug the code in the currently active document window. Select one of the debugging commands to either run or to single-step through the program.
Selecting a debugging target¶
The current engine is the one whose data and state is displayed in the Toolkit’s panes. If an application has only one engine, its engine becomes current when you select the application as the target. If there is more than one engine available in the target application, you can select an engine in the list to make it current.
When you open the Toolkit, the Toolkit itself is the default target application. When you select another target, if the target application that you select is not running, the Toolkit prompts for permission and launches the application. Similarly, if you run a script that specifies a target application that is not running (using the #target directive), the Toolkit prompts for permission to launch it. If the application is running but not selected as the current target, the Toolkit prompts you to switch to it.
If you select an application that cannot be debugged in the Toolkit, an error dialog reports that the Toolkit cannot connect to the selected application.
The ExtendScript Toolkit is the default editor for JSX files. If you double-click a JSX file in a file browser, the Toolkit looks for a #target directive in the file and launches that application to run the script; however, it first checks for syntax errors in the script. If any are found, the Toolkit displays the error in a message box and quits silently, rather than launching the target application. For example:
- You can use the up- and down-arrow keys to scroll through previous entries, or place the cursor with the mouse. Pressing ENTER executes the line that contains the cursor, or all selected lines.
- The right-click context menu provides the same editing commands as that of the document window.
- You can copy, cut, and paste text, and undo and redo previous actions.
- You can select text with the mouse, and use the normal copy and paste shortcuts.
- The flyout menu allows you to clear the current content.
- Commands entered in the console execute with a timeout of one second. If a command takes longer than one second to execute, the Toolkit generates a timeout error and terminates the attempt.
Controlling code execution¶
|Run/Continue||F5 (Windows) Ctrl R (Mac OS)||Starts or resumes execution of a script. Disabled when script is executing.|
|Stop||Shift F5 (Windows) Ctrl K (Mac OS)||Stops execution of the script and generates a runtime error. Enabled when a script is executing.|
Visual indication of execution states¶
When the execution of a script halts because the script reached a breakpoint, or when the script reaches the next line when stepping line by line, the document window displays the current script with the current line highlighted in yellow.
If the script encounters a runtime error, the Toolkit halts the execution of the script, displays the current script with the current line highlighted in orange, and displays the error message in the status line. Use the Data Browser to get further details of the current data assignments.
Scripts often use a try/catch clause to execute code that may cause a runtime error, in order to catch the error programmatically rather than have the script terminate. You can choose to allow regular processing of such errors using the catch clause, rather than breaking into the debugger. To set this behavior, choose Debug > Don’t Break On Guarded Exceptions. Some runtime errors, such as Out Of Memory, always cause the termination of the script, regardless of this setting.
When debugging a script, it is often helpful to make it stop at certain lines so that you can inspect the state of the environment, whether function calls are nested properly, or whether all variables contain the expected data.
- To stop execution of a script at a given line, click to the left of the line number to set a breakpoint. A red dot indicates the breakpoint.
- Click a second time to temporarily disable the breakpoint; the icon changes color.
- Click a third time to delete the breakpoint. The icon is removed.
Some breakpoints need to be conditional. For example, if you set a breakpoint in a loop that is executed several thousand times, you would not want to have the program stop each time through the loop, but only on each 1000th iteration.
To set a conditional breakpoint in a loop, for example, the conditional expression could be
"i >= 1000",
which means that the program execution halts if the value of the iteration variable i is equal to or greater
It is often useful to check the boundary conditions for loops; to do this, you can set the condition for a breakpoint within a loop to trigger on the first and last iterations. You can set breakpoints on lines that do not contain any code, such as comment lines. When the Toolkit runs the program, it automatically moves such a breakpoint down to the next line that actually contains code.
The Breakpoints panel¶
The Breakpoints panel displays all breakpoints set in the current document window. You can use the panel’s flyout menu to add, change, or remove a breakpoint.
You can edit a breakpoint by double-clicking it, or by selecting it and choosing Add or Modify from the panel menu. A dialog allows you to change the line number, the breakpoint’s enabled state, and the condition statement. You can also specify a hit count, which allows you to skip the breakpoint some number of times before entering the debugger. The default is 1, which breaks at the first execution.
When execution reaches this breakpoint after the specified number of hits, the debugger evaluates this condition. If it does not evaluate to true, the breakpoint is ignored and execution continues. This allows you to break only when certain conditions are met, such as a variable having a particular value.
Each breakpoint is indicated by an icon to the left of the line number in the document window, and an icon and line number in the Breakpoints panel. Different icons are used in the document window and in the Breakpoints panel.
|Document window||Breakpoints panel||Description|
|Unconditional breakpoint. Execution stops here.|
|Unconditional breakpoint, disabled. Execution does not stop.|
|Conditional breakpoint, disabled. Execution does not stop.|
Evaluation in help tips¶
You can use the Data Browser to examine and set variable values. - Click a variable name to show its current value in the edit field at the top of the panel. - To change the value, enter a new value and press ENTER. If a variable is Read only, the edit field is disabled.
The flyout menu for this panel lets you control the amount of data displayed:
- Undefined Variables toggles the display of variables whose value is undefined (as opposed to null).
- Functions toggles the display of all functions that are attached to objects. Most often, the interesting data in an object are its callable methods.
Each variable has a small icon that indicates the data type. An invalid object (that is, a reference to an object that has been deleted) shows the object icon crossed out in red. An undefined value has no icon.
You can inspect the contents of an object by clicking its icon. The list expands to show the object’s properties (and methods, if Functions display is enabled), and the triangle points down to indicate that the object is open.
The call stack¶
The Call Stack panel is active while debugging a program. When an executing program stops because of a breakpoint or runtime error, the panel displays the sequence of function calls that led to the current execution point. The Call Stack panel shows the names of the active functions, along with the actual arguments passed in to that function.
For example, this panel shows a break occurring at a breakpoint in a function RGBColorPicker():
The function containing the breakpoint is highlighted in the Call Stack panel. The line containing the breakpoint is highlighted in the Document Window.
You can click any function in the call hierarchy to inspect it. In the document window, the line containing the function call that led to that point of execution is marked with a green background. In the example, when you select the run() function in the call stack, the Document Window highlights the line in that function where the RGBColorPicker() function was called.
Switching between the functions in the call hierarchy allows you to trace how the current function was called. The Console and Data Browser panels coordinate with the Call Stack panel. When you select a function in the Call Stack:
- The Data Browser panel displays all data defined in the selected context.