Debugging

The debugger runs a task on an agent and lets you stop it before any command, step through it and look at its variables, all from the editor. Use it to find out why a task does not do what you expect, before you push it.

#Starting a debug run

1. Save your changes: a debug run, like any run, uses the saved task.
2. Set breakpoints where the run should stop (optional, see below).
3. Click Debug in the editor toolbar.
4. In the dialog, choose the Agent (or Any available agent), fill in the task's INPUTS, and decide whether to Stop at errors no catch handles (to look at the variables).
5. Click Start debugging.

The debug panel opens under the editor. Debug needs the Debug tasks permission (Developer by default); in a local copy it runs your saved local copy, in the public view the public version.

Note: Without breakpoints the run stops only at an unhandled error (when that option is on) or when you press Pause.

#Breakpoints

A breakpoint stops the run before a command runs.

• Blocks view: click the dot at the left edge of a block (it shows when you hover), select blocks and press F9, or use Add breakpoint in the block's ⋯ menu. With several blocks selected, F9 sets or removes all of them.
• Code view: press F9 on a command's line, or click in the margin left of the line numbers.

A red dot marks a breakpoint. Sections such as Else or Catch cannot have one; put it on the first command inside instead. Breakpoints are kept in your browser for each task, and you can add or remove them while a debug run is going: the run uses the new set at once.

#The debug panel

When the run stops, the editor selects the command it stopped at and scrolls it into view. In the blocks view the block is highlighted with Stopped here (or Failed here for an error); in the code view the line is highlighted.

#Controls

The keys work anywhere on the editor page, including the code view.

Note: A task called with runtask runs as one step: you cannot step into it. Debug the called task on its own, giving it the same inputs.

#Variables

The VARIABLES pane shows each variable as a tree: open lists, records and data tables to see their items and fields. Values are shown as the agent holds them:

• passwords from credential variables are masked as ***;
• long text is cut after 2,000 characters, and lists and records after 200 entries;
• browser pages, sessions and other runtime objects are shown as text.

Variables are refreshed each time the run stops.

#Stopping at errors

With Stop at errors no catch handles turned on (the default), a command that fails outside any catch section does not end the run straight away. The run stops at the failing command with the Error tag and a banner with the message: look at the variables, then Continue to let the run fail, or Stop.

Errors inside a try section with a catch, and errors in a round of loop --type:queue, do not stop the run; they are handled as usual. Set a breakpoint in the catch section to look at its error variable (catch --error:err) there.

#Run from here and Debug from here

The ⋯ menu of a block has Run from here and Debug from here. The run starts at that command and skips the commands above it, except declarations: input, output and set with a --type still run, so the variables exist.

• Only commands on the main level of the task can be a starting point, including commands inside a Step (a step starts at its first command). Commands inside If, Loop or Try cannot, because their condition, loop or error handling would be skipped.
• Skipped commands do not run, so variables they would have filled keep their declared initial value. Set a meaningful initial value, or start a little earlier.
• Line numbers in the log and the debugger stay those of the editor.

Tip: Debug from here is useful for long tasks: test the end of a task without running the whole login and navigation each time.

#Run to here and Run this block now

The fastest way to get a step right is to try it where the robot actually is: in the browser it opened, with the variables it has at that moment.

1. Select the block you are working on and choose Run to here in its ⋯ menu (or press Ctrl+F10). The task starts in the debugger and stops before that block. It works for blocks anywhere, including inside If, Loop and Try. The stop counts for this run only; it does not leave a breakpoint behind.
2. While the run is stopped, select one or more blocks and choose Run this block now (Ctrl+Shift+Enter, or Run selected now in the debug panel). They run in the stopped run, with its open browsers, windows and variables, exactly as the editor has them now: saved or not. The variables in the panel show the result.
3. Wrong selector, wrong value? Change the block and run it again. The run stays where it stopped, so nothing has to start over.
4. When the block works, Save and Continue (F5), or Stop.

Notes:

• The blocks run one after another as if they were inserted at the place where the run stopped; the stopped run's own next command has not run yet.
• An error in those blocks is shown as a message and in the log; it does not fail the run. Breakpoints inside them do not stop.
• Only the selected blocks run (with their contents), not the blocks around them.

#Watching the robot

During any run, whoever looks at the agent machine sees which step runs (the Windows service, which has no desktop, shows nothing):

• Progress panel: the Botream Agent tray app shows a small panel at the bottom right with the task, the current command and line, the elapsed time, and buttons to pause and stop. It never takes the keyboard focus.
• Web pages: in a visible browser, before each click, typing or other element action a pointer glides to the element and an orange frame with the action's name ("Click", "Type"…) surrounds it for about a second.
• Desktop programs: before each element action the real mouse pointer jumps to the element and an orange frame surrounds it for a moment; sendkeys frames the element that has the keyboard focus, and mouse marks each position it uses.

Combine this with breakpoints and Step over to follow a task command by command on the agent machine.

#Other ways to investigate

• Watch the live log of a normal run on the execution page; see Monitoring.
• A failed run keeps its failing line, a screenshot and the variables, and Analyze with AI can explain it; see Error handling and retries.
• log --level:debug writes extra detail to the log while you test. Debug lines are kept unless an administrator turned off Keep debug log lines in Settings.

log --message:"Response body: $response.Body$" --level:debug