7.2 The debugger

As in any development environment, at some point the need will arise to debug problems introduced into a test suite which cannot readily be solved by a straight-forward analysis of the elements and structure of the suite. To this end, QF-Test includes an intuitive debugger. Those of you familiar with debugging programs in Java or other programming languages will find this debugger similar in function and usefulness.

7.2.1 Entering the debugger

The QF-Test debugger can be started directly by selecting a node (or some nodes) to execute and pressing the step-in or step-over buttons, or by using the menu operations »Debugger«-»Step in« and »Debugger«-»Step over« or the keyboard shortcuts F7 and F8. See "Debugger commands" for a detailed explanation of these operations.

If you are running tests on your test suite and use the play button to start execution (see "Running tests"), the debugger will normally not be entered. However, the debugger will be activated automatically when any one of the following occur:

• A user-defined breakpoint is reached (see "Manipulating breakpoints" on turning on/off breakpoints).
• Execution is interrupted manually by pressing the pause button or F9 or selecting the »Run«-»Pause« menu item.
• A caught or uncaught exception is thrown, an error happens or a warning is logged and the respective option to break under that condition is set (see option Automatic breaks).

When the debugger suspends execution of the test, the node about to be executed will be shown with a colored frame around its icon that reflects the cause for the break. If the debugger is stopped due to manual intervention, a user breakpoint or when stepping, the frame will be black. When stopping due to a warning, error or exception the frame will be orange, red or thick red respectively, exactly like the error indicators in the run log.

Note When the debugger is entered due to a warning, error or exception it will move execution back to the beginning of the node that caused it, giving you a chance to fix the cause of the problem and re-execute that node. If this is undesirable or impossible you can simply skip the node (see "Debugger commands").

In the default workbench mode the debugger will be integrated into the normal test suite view. For non-workbench mode please refer to The debugger window.

7.2.2 Displaying the current variable values

In debugging mode the Variables and their values for the current point of test execution will be displayed in the lower part of the test suite window. The list has two parts: the primary (top part) and the fallback variable stacks. Variables with the same name can be bound by any number of nodes. The value actually used in the test is determined by the order of the nodes, top-down. This means when several nodes bind variables with the same name the value of the one which is furthest up the list will be used.

A single click on a node brings up its variable bindings in the right half of the variable display. There, the variable values can be edited, new variables can be added or existing ones removed. These changes immediately affect the current test run, but are of a temporary nature. They are not propagated to the nodes in which the variables were bound in the first place. The variable value is always a String after editing. You can double-click on the node in the variable definitions list to quickly navigate to the node in its associated test suite to set the value permanently.

The variable values are strings by default. In case a variable has a different type you will see it surrounded by brackets before the actual value. When you edit a value in the variable definitions list please be aware it will automatically be transformed to a string - recognizable by the parenthesis indicating the type having disappered.

For the primary stack all nodes are shown, even if they are not binding any variables, for the secundary stack only the nodes binding variables.

With the option »View«-»Terminal«-»Prefer tree over terminal« you can control whether variables definitions will fill the whole bottom part of the test suite window or only the right part below the node details.

7.2.3 Debugger commands

Most of the debugger commands are similar to those of any other debugger. However, some additional commands are included that deal with special situations.

Step-wise debugging of a test suite is available through three operations:

• The step-in button (F7, »Debugger«-»Step in«) executes the currently selected node and will set the execution mark to the next deepest node, regardless of how deep that node may lie in the node structure. This operation is useful, for example, to step into and debug a Procedure or Sequence.
• The step-over button (F8, »Debugger«-»Step over«) executes the currently selected node as well as any child nodes that lie under it and then sets the execution mark to the next node at the same level. This is helpful for being able to execute an entire Procedure or Sequence without stepping through each step individually.
• The step-out button (Ctrl⁠+⁠F7, »Debugger«-»Step out«) executes the currently selected node as well as any other nodes at the same level (including any child nodes of these nodes) and then sets the execution mark to the next node at the next higher level. This type of operation is useful when, for example, you are debugging a Procedure or Sequence and don't want to step through the rest of the nodes in it. By simply using step-out, you can execute the rest of the nodes and return.

The skip functions expand the QF-Test debugger in a powerful way which is not typically possible for a debugger in a standard programming environment. In short, they allow you to jump over one or more nodes without having to execute those nodes at all.

• The skip-over button (Shift⁠+⁠F9, »Debugger«-»Skip over«) jumps over the current node without executing it, moving the execution mark to the next node.
• The skip-out button (Ctrl⁠+⁠F9, »Debugger«-»Skip out«) ends the execution of the current Procedure or Sequence and jumps to the next node at the next higher level.

Even more powerful is the ability to continue the test run at any arbitrary node, even in a completely different test suite. QF-Test will keep as much of the current execution context as possible, including variable bindings. The closer the new target location is to the current point of execution, the more information can be salvaged.

You can switch execution to a different node by pressing Ctrl⁠+⁠, or by selecting the menu item »Run«-»Continue execution from here« or the respective item in the context menu. When you do so, execution will not continue immediately, only the next node to be executed will change. You can continue the test as usual by single-stepping or resuming the test run.

The following additional commands are available:

• The rethrow-exception button (»Debugger«-»Rethrow exception«) is only active when the debugger was entered due to an exception. It lets you rethrow the exception to be handled by the test suite just as if the debugger had never caught it in the first place.
• The locate-current-node button (»Debugger«-»Locate current node«) quickly moves the selection in the tree-view to the node that is about to be executed. It is a useful shortcut in case you get lost while moving around the test suite.

7.2.4 Manipulating breakpoints

Setting a breakpoint on a node will tell the debugger to suspend execution just before it enters that node. Breakpoints are displayed in the tree-view by prepending "(B)" to the name of a node.

Breakpoints can be set or removed individually with Ctrl⁠+⁠F8 or with the »Debugger«-»Breakpoint on/off« menu item. After finishing a debugging session you can use »Debugger«-»Clear all breakpoints« to remove any breakpoints that might have been left hanging around. This command will remove all breakpoints from all test suites.

Note Breakpoints are transient and will not be saved with the test suite.

7.2.5 The debugger window

When you are not working in workbench mode (Activate workbench view) the debugger has to be run in a dedicated debugger window by selecting »Debugger«-»Show debugger window« once the debugger has been entered.

The debugger can be run either from within the normal test suite view, or by opening a dedicated debugger window by selecting »Debugger«-»Show debugger window« once the debugger has been entered.

You can also cause the debugger window to open automatically whenever the debugger is entered by setting the option Always open debugger window in the global options dialog or under the »Debugger«-»Options« menu. If you open or close the debugger window explicitly, this is considered a "manual override" and this option will be ignored for the rest of the test run.

The debugger window is similar to a normal test suite window. You can select nodes and edit their attributes, but you cannot delete or insert nodes, there are no file operations and no recorder. For the more complex operations you can quickly jump from the debugger window to the same node in the respective test suite window by pressing Ctrl⁠+⁠T or selecting »Find node in test suite« from the »Edit« menu or the context menu.