Robot Debugger#
CumulusCI includes a rudimentary Robot debugger which can be enabled by
setting the robot_debug option of the robot task to true. When the
debugger is enabled you can use the
Breakpoint keyword from the
Salesforce
Library keyword
library to pause execution.
Once the Breakpoint keyword is encountered you will be given a prompt
from which you can interactively issue commands.
For the following examples we’ll be using this simple test:
*** Settings ***
Resource cumulusci/robotframework/Salesforce.robot
Suite Setup Open test browser
Suite Teardown Close all browsers
*** Test Cases ***
Example test case
log this is step one
Breakpoint
log this is step two
log this is step three
Enabling the debugger#
To enable the debugger you must set the robot_debug option to true
for the robot task. You should never do this in the project’s
cumulusci.yml file. Doing so could cause tests to block when run on a
CI server such as MetaCI.
Instead, you should set it from the command line when running tests locally.
For example, assuming you have the example test in a file named
example.robot, you can enable the debugger by running the robot task
like this:
$ cci task run robot --robot_debug true --suites example.robot
Setting breakpoints#
The Salesforce keyword library includes a keyword named [Breakpoint]{.title-ref}. Normally it does nothing. However, once the debugger is enabled it will cause the test to pause. You will then be presented with a prompt where you can interactively enter commands.
$ cci task run robot --robot_debug true --suites example.robot
2019-10-01 15:29:01: Getting scratch org info from Salesforce DX
2019-10-01 15:29:05: Beginning task: Robot
2019-10-01 15:29:05: As user: test-dp7to8ww6fec@example.com
2019-10-01 15:29:05: In org: 00D0R000000ERx6
2019-10-01 15:29:05:
==============================================================================
Example
==============================================================================
Example test case .
:::
::: Welcome to rdb, the Robot Framework debugger
:::
Type help or ? to list commands.
> Example.Example test case
-> <Keyword: cumulusci.robotframework.Salesforce.Breakpoint>
rdb>
Note: the Breakpoint keyword has no effect on a test if the
robot_debug option is not set to true. While we don’t encourage you
to leave this keyword in your test cases, it’s safe to do so as long as
you only ever set the robot_debug option when running tests locally.
Getting Help#
Whenever you see the debugger prompt rdb>, you can request help by
typing help or ? and pressing return. You will be given a list of
available commands. To get help with a specific command you can type
help followed by the command you want help on.
rdb> help
Documented commands (type help <topic>):
========================================
continue locate_elements quit shell vars
help pdb reset_elements step where
rdb> help vars
Print the value of all known variables
rdb>
Examining Variables#
There are two ways you can examine the current value of a Robot variable. The simplest method is to enter the name of a variable at the prompt and press return. The debugger will show you the value of that single variable:
rdb> ${BROWSER}
chrome
To see a list of all variables and their values, enter the command
vars.
rdb> vars
┌────────────────────────────────────┬──────────────────────────────────────────────────┐
│ Variable │ Value │
├────────────────────────────────────┼──────────────────────────────────────────────────┤
│ ${/} │ / │
├────────────────────────────────────┼──────────────────────────────────────────────────┤
│ ${:} │ : │
├────────────────────────────────────┼──────────────────────────────────────────────────┤
│ ${BROWSER} │ chrome │
├────────────────────────────────────┼──────────────────────────────────────────────────┤
... <more output> ...
Executing Robot keywords#
You can execute Robot keywords at the prompt by entering the command
shell (or the shortcut !) followed by the keyword and arguments just
as you would in a test. The following example runs the SeleniumLibrary
keyword Get
Location:
rdb> shell get location
status: PASS
result: https://ability-enterprise-4887-dev-ed.lightning.force.com/lightning/setup/SetupOneHome/home
Notice that the shell command will run the keyword and then report the
status of the keyword and display the return value.
Note: just like in a test, you must separate arguments from keywords by two or more spaces.
Setting Robot variables#
To capture the output of a keyword into a variable, you do it the same way you would do it in a test: use a variable name, two or more spaces, then the keyword:
rdb> ! ${loc} get location
status: PASS
${loc} was set to https://ability-enterprise-4887-dev-ed.lightning.force.com/lightning/setup/SetupOneHome/home
rdb> ${loc}
https://ability-enterprise-4887-dev-ed.lightning.force.com/lightning/setup/SetupOneHome/home
In addition to setting variables from the results of keywords, you can
also set variables with the shell command using the built-in keywords
Set Test
Variable,
Set Suite
Variable,
or Set Global
Variable.
rdb> ! set test variable ${message} hello, world
status: PASS
result: None
rdb> ${message}
hello, world
Locating elements on the web page#
One of the most powerful features of the debugger is the ability to locate elements on the screen. This makes it easy to experiment with xpaths or other types of locators.
In the following example, we want to find all items on the page that contain the title “Learn More”:
rdb> locate_elements //button[@title='Learn More']
Found 1 matches
The elements will be highlighted with a yellow border:
To remove the highlighting you can use the debugger command
reset_elements
Step through the test#
The debugger allows you to step through a test one keyword at a time.
From the rdb prompt, enter the command step to continue to the next
step in the test.
rdb> step
.
> Example.Example test case
-> <Keyword: BuiltIn.Log this is step two>
The last two lines help to give context. It is showing that you are
currently right before the keyword BuiltIn.Log this is step 2. To get
a full stack you can issue the command where
rdb> where
0: -> Example
1: -> Example.Example test case
2: -> BuiltIn.Log
Continuing or quitting the test#
To let the test continue to the end, or to the next Breakpoint
keyword, issue the command continue. To stop execution gracefully (ie:
allow all test and suite teardowns to run), issue the command quit.