Debug TruClient 2.0 scripts

This topic describes different options to debug a TruClient script.

In this topic:

View replay errors

If any steps failed during replay, they are marked with an error icon in the TruClient Development window. Hover the mouse over these icons to view descriptions of the errors.

Back to top

Run the script step by step

You can run your script step by step, to view the replay more slowly and in a controlled manner. Select the arrow next to the Replay button in the browser and select Replay step by step. Repeat this for each step to continue the step-by-step replay.

Back to top

View the replay logs

TruClient maintains log files that record various operations performed when running a script in interactive mode, and from VuGen. These log files can be useful when debugging a TruClient script.

You can view details of your script's replay in the VuGen Output Pane. Select Output Pane > <Browser name> - Interactive Replay.

TruClient log files are stored in the TruClient script folder:

interactive_replay_<Browser type>.txt	Log file that records various operations performed when running a script in interactive mode. Example: interactive_replay_TruClientBrowser.txt
mdrv.log	Log file that records various operations performed when running a script from VuGen.

Back to top

Enable the object identification debug log

Enable the object identification debug log to understand why TruClient was not able to identify an object using the TruClient identification or Descriptors ID methods.

To enable the object identification debug log:

1. In the script folder, create a .json file and name it additionalSettings.json.

2. Add the following configuration to the file:

   Copy code

   {
   "TruClient": {
   "EnableIdentDescriptorsDebug": true,
   "EnableIdentDebug": true
       }
   }

3. If TruClient is unable to identify an object, the log contains information similar to the following:

   t=00006967ms: Error -205177: ** 3.1: Click on Search combobox ** failed - target object was not found.       
   Snapshot Info [MSH 1 0]    [MsgId: MERR-205177]  
    *Comment* Object not found
   t=00006970ms: Error -205177: Step ID: step:{b80a25a2-ec24-4186-8d1a-d72e6f525461}                                                   *Comment* Internal step information
   Test Object: testObj:{246c634d-e8bb-4c1e-9a33-899bff8c9a1b}
   Elected object: <input class="b_searchbox" id="sb_form_q" name="q" title="Enter your search term" value="" maxlength="1000" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" type="search">  
    *Comment* Candidate object to elect
   Total votes received: -1  
    *Comment* Votes outcome
   Electors voted:  *Comment*  Electors vote.
   0. Elector: leaf, Value: true, Recorded Score: 0.01, Replay Voted Score: 0.01                                                                           
   1. Elector: position, Value: {"pos":"absolute"}, Recorded Score: 0.1, Replay Voted Score: -0.2
   2. Elector: role, Value: "combobox", Recorded Score: 0.05, Replay Voted Score: -1

   * indicates comments added to describe log sections.

Back to top

Breakpoints

Breakpoints instruct the script to stop running during a replay in interactive mode. They can be used to help debug your script. During replay, you can use the Inspector panel to inspect the values of variables at the breakpoint.

A breakpoint is indicated by a red circle icon to the left of the step number.

To use breakpoints:

1. Use one of these methods to insert a breakpoint in your script:

   • Right-click the relevant step and select Toggle breakpoint. Select the option again to remove the breakpoint.

   • Click to the left of the step number to display the icon. Click on the breakpoint icon to remove it.

2. Replay the script or the step. you replay the script, the Inspector panel is displayed. The Inspector panel displays all parameters and user-defined variables.

3. To display the value for a variable at the breakpoint, enter the variable expression in the box at the top of the Inspector panel, and then click Add an expression .

   The expression is added to the Inspector panel.

Back to top

Debug scripts using snapshots

TruClient generates snapshots according to the snapshot generation settings. You can use the snapshots generated during replay to debug scripts by viewing the snapshots of the failed step(s).

To view snapshots for failed steps:

For UI details, see Snapshots for TruClient 2.0 scripts.

Back to top

Step levels

You can set TruClient to filter the steps by their level when replaying a script.

Assigning step levels

Before recording, on the General settings > Interactive options tab, enable Create level 2 or level 3 steps during recording.

During recording, each step is assigned a level number between 1-3 (the level is displayed in the step ). Lower numbers represent higher levels:

• Level 1 steps are necessary to the business process. Failing to run them may cause subsequent steps to fail.
• Level 2 steps affect the application in a way that is probably not important to the business process.
• Level 3 steps have no apparent effect on the application.

For example, a step is assigned level 2 if it occurs in an area of the application that has no effect.

Filtering steps at the script level

You control the steps that are displayed in the Development window from the Script level dropdown in the menu bar:

• Select to display level 1 steps only (highest level, default setting).
• Select to display level 1 and 2 steps.
• Select to display all steps.

The hidden steps are ignored during interactive replay.

Steps are displayed in the user interface only if they run at the current script level, but the numbering of steps always reflects all of the recorded steps.

The following screen shot displays a small script. Note that the step numbers skip from 3 to 5; step 4 is hidden in a different level.

After changing the display settings to level 3, all steps are now displayed, and will run if replayed in interactive mode.

Modifying the step level

You can override TruClient's step level assignment, so that the step is included or excluded at the level at which you replay.

Example:

Mouseover steps are generally assigned level 3, since many mouseover steps are recorded simply by the user moving the mouse and do not affect the application state.

However, if a mouseover opens a list to click an option, the action fails if the mouseover is not replayed first.

To fix this, lower the script level to 3 to display all steps. Open the relevant step and change the step level to level 1. (If the step is part of a group step, both the group step and the individual step must be modified.)

The step is now included when the script level is returned to level 1.

Automatic leveling during replay

The level of a step is normally set during recording. If the level is set too low, the replay may fail, for example, generating an object not found error. During replay, TruClient checks if there are steps at a level lower than the current script replay level that can affect the outcome of the current step. If found, the meaningful step is moved to a higher level.

Back to top

Handling short events

Sometimes event replay is too short. For example, there might be a mouseover that opens a dropdown menu or list box. The object must be open before an option is selected.

During replay, the list closes when the mouseover event ends, and the next action to click on an option fails, because the list is not open.

There are two ways to handle this situation:

• Change the Mouse over step end event to Action completed.
• Remove both the Mouse over and the Click steps, and replace them with an Evaluate JavaScript step which performs both actions in the same step.

Back to top

Insert Wait steps

Sometimes a script fails to replay because an object required by a step is not available immediately after the End event of the previous step. In this case, it is recommended to "slow down" the script, so there is enough time for the object to load.

You can do this by inserting Wait-type steps from the Steps box Functions tab. Use the steps to ensure that the next step does not start until the wait condition is true.

There are two types of Wait steps:

Type	Description	After insertion:
Wait	Delays the next step for the specified time.	Configure the interval in the argument section of the step
Wait for object	Delays the next step until: The specified object is loaded. This is the default setting (the argument value is set to true). The object does not exist. If the object exists when the step executes, the step waits until the object disappears, or the object times out (the first event). If the object does not exist when the step executes, the step ends.	Select Choose an object, and select the target object in the application. To delay the step until the object does not exist, in the Arguments section of the step, set the Exists values to false.

You can run a script without the wait steps, by selecting the Ignore wait steps option on the General settings > Interactive options tab.

Another option to resolve pacing issues is to change the Object timeout of the failing step in the Step section of the step's properties.

Back to top

Resolve step timeouts

Steps may time out for several reasons:

Back to top

Resolve object identification issues

If an error is discovered during replay, you can highlight the object that failed, and TruClient automatically recognizes the selected step. For details, see Object identification in TruClient 2.0 scripts.

You can also use the Descriptor editor to improve or control object identification in your TruClient scripts, by adding or editing conditions. For details, see Descriptors for TruClient 2.0 scripts.

Back to top

Selecting items in dynamic lists

If the names of the items in a list are dynamic, then the selection of an item on the list may fail during replay.

For example, the list may include cities based on the text entered so far (auto-complete). Based on the text typed in, the list constantly changes.

There are two ways to solve this issue:

• Use an alternative step that selects an item from the list using the ordinal identifier, instead of the text of the actual item.

• If the text is only partially dynamic, you can use a regular expression to locate the required item, based on partial text matching.

Back to top

Debugging plug-ins

To further improve debugging capabilities, you can install plug-ins such as DOM Inspector or Firebug. These can provide additional information on the application object properties.

Back to top

See also:

• Configure TruClient 2.0 General settings
• Snapshots for TruClient 2.0 scripts