Step Through a Template or Script

Once you have inserted a DEBUG instruction in a script, a resource, or in the template, you can begin stepping through the template, resource, or script to determine where your automation is causing unexpected results. The HotDocs Debugger includes several options for doing this.

Before debugging, however, you should understand how HotDocs processes the template, resource, or script:

When you first test assemble a template, resource, or script, HotDocs processes (or runs through) the entire template, resource, or script to create the interview, which it displays in the test assembly window. As you answer questions in the interview, some answers may cause HotDocs to reprocess the script so it can update the interview. (For example, answering a true/false question may gray or ungray other variables in a dialog. In order for these changes to happen, HotDocs must reprocess the template.) Depending on the complexity of your template, HotDocs may reprocess the template, resource, or script many times during a test assembly.

During a test, if HotDocs encounters a DEBUG instruction, it displays the HotDocs Debugger, which simply shows you how the template, resource, or script is being processed at that specific field or line using any answers that have been entered. This allows you to see how variables and instructions are being used to manipulate text in the document or data in the script or resource. Such analysis will help you understand why you may be seeing unexpected results in your test.

At any time, you can close the Debugger and return to the test assembly window. However, as long as you are in debugging mode, any time HotDocs processes a DEBUG instruction, the HotDocs Debugger will be redisplayed. This will happen each time you make a change to answers in the interview that cause it to be reprocessed.

Debugging mode happens when you have a DEBUG instruction in your script or template and the Enable Debugging button is selected (pressed down) at the test assembly window.

To debug your template, resource, or script using a certain set of answers, first test assemble and then save your answers in a test answer file. (See Use a Test Answer File.) Then debug your template. (See Insert Debugging Instructions in Templates and Scripts.)

To step through a template or script

Insert a DEBUG instruction in the script, resource or template and then test assemble the template. (See Insert Debugging Instructions in Templates and Scripts.)
When the HotDocs Debugger window appears, complete any of the following tasks:

To	Do This
Understand why the Debugger window is showing	Read the explanation at the top of the tabbed pane.
Examine either each field in the template or each line in the script	Click Step Into. The Debugger steps into that field or line to show how HotDocs has processed it using the answers you have provided, specifically: If you are in an INSERT instruction, the Debugger will step into the inserted clause, clause library, or template and show you how that file is being processed. If you are in a Computation variable field, the Debugger will step into the computation and show you how the script is being processed. If you are in a regular (non-computed) variable field, the Debugger will move you to the next field or line. As you step into components and instructions, you will notice that you are adding these levels of processing to the processing stack (which is a sequential list of templates and components you are processing).
Ignore a field or line in a script	Click Step Over. The Debugger will not step through any computations or subtemplates referenced in the field unless it encounters another explicit DEBUG instruction. For example, if you step over a computation field but the computation script includes a DEBUG instruction, HotDocs will stop at the DEBUG instruction in the computation script.
Move to the next item on the processing stack	Click Step Out. The Debugger will move you out of the current level of debugging and move you to the next item down on the processing stack (which is a sequential list of templates and components you are processing). For example, if you are debugging a computation in an inserted template, clicking Step Out will move you out of the computation and back to the inserted template. If you click Step Out again, the Debugger will return you to the parent template.
Stop processing any current DEBUG instructions	Click Continue. HotDocs continues processing the interview until it either finds another explicit DEBUG instruction (which will cause the Debugger to appear again) or it finishes processing the template. Changing answers in the interview may cause HotDocs to reprocess the interview, thus triggering another debug session. To keep this from happening, close the Debugger window and either remove the DEBUG instruction from the template or script, or disable the Debugger. (To do this, click the Enable Debugging button in the test assembly window toolbar.)
Cancel the debugging session	Click Stop. HotDocs closes the Debugger window and disables the Debugger. You are returned to the test assembly window. You can start the Debugger again by clicking the Enable Debugging button in the test assembly window toolbar.
View the current field or line of script and any answers used in processing it	Click the Default Watch List tab, which shows a list of variables referenced in the field or script as well as any answers for the variables. As HotDocs processes REPEAT instructions, it displays the value for the current iteration (or index) in the Answer column. As you step through the REPEAT instruction, you can watch the Debugger increment this index. The Debugger also displays the REPEAT COUNTER.
Track the answers for specific variables as the Debugger steps through the interview or script	Click the Custom Watch List tab. See Add Variables to the Debugger Watch List for details.
View the processing stack, or path of execution	Click the Processing Stack tab. The processing stack shows the sequential list of templates and components you are processing as well as the reason why a certain template or component was added to the stack. This can help you determine how HotDocs came to be processing the current field or line. As you step into components, those components are added to the top of the stack.
Keep HotDocs from debugging the template or script without removing the DEBUG instruction	Click Stop at the Debugger window. This closes and disables the Debugger window. (To start another debugging session, click the Enable Debugging button. HotDocs reprocesses the interview or script, which forces HotDocs to process the DEBUG instruction, thus causing the Debugger to open again.)