CumulusCI Robot Framework Keywords

Pauses execution and enters the Python debugger.

This keyword uses the Salesforce API to get information about a community.

This keyword requires the exact community name as its first argumment.

• If no key is given, all of the information returned by the API will be returned by this keyword in the form of a dictionary
• If a key is given, only the value for that key will be returned.

Some of the supported keys include name, siteUrl, and loginUrl. For a comprehensive list see the API documentation, or call this keyword without the key argument and examine the results.

An API call will be made the first time this keyword is used, and the return values will be cached. Subsequent calls will not call the API unless the requested community name is not in the cached results, or unless the force_refresh parameter is set to True.

Returns the namespace prefix (including __) for the specified package name. (Defaults to project__package__name_managed from the current project config.)

Returns an empty string if the package is not installed as a managed package.

Returns a dictionary of the org information for the current target Salesforce org

Returns the login url which will automatically log into the target Salesforce org. By default, the org_name passed to the library constructor is used but this can be overridden with the org option to log into a different org.

If userfields are provided, the username and access token for the given user will be used. If not provided, the access token for the org's default user will be used.

Example:

${login url}=  Login URL  alias=dadvisor

Runs a named CumulusCI task for the current project with optional support for overriding task options via kwargs.

Note: task_name can be prefixed with the name of another project, just the same as when running the task from the command line. The other project needs to have been defined in the 'sources' section of cumulusci.yml.

The task output will appear in the robot log.

Examples:

Runs a CumulusCI task class with task options via kwargs.

Use this keyword to run logic from CumulusCI tasks which have not been configured in the project's cumulusci.yml file. This is most useful in cases where a test needs to use task logic for logic unique to the test and thus not worth making into a named task for the project

The task output will appear in the robot log.

Examples:

Sets the LOGIN_URL variable in the suite scope which will automatically log into the target Salesforce org.

Typically, this is run during Suite Setup

Verifies that the page appears to be the requested page

If the page matches the given page object or contains the given page object, the keyword will pass.a

When this keyword is called, it will try to get the page object for the given page_tyope and object_name, and call the method `_is_current_page`.

Custom page objects may define this function in whatever manner is necessary to determine that the current page is or contains the given page object. The only requirement is that this function raise an exception if it determines the current page either doesn't represent the page object or doesn't contain the page object.

The default implementation of the function uses the page URL and compares it to a pattern based off of the page_type and object_name.

Return an instance of a page object

This is useful if you want to call a single page object method from some other keyword without having to go to another page or load the page object into a page.

This works a lot like robot's built-in "get library instance" keyword, but you can specify the page object by page type and object name rather than the library name, and it will autoload the appropriate library (assuming its module has been imported).

Go to the page of the given page object.

The URL will be computed from the page_type and object_name associated with the object, plus possibly additional arguments.

Different pages support different additional arguments. For example, a Listing page supports the keyword argument `filter_name`, and a Detail page can be given an object id, or parameters for looking up the object id.

If this keyword is able to navigate to a page, the keyword `load page object` will automatically be called to load the keywords for the page.

Custom page objects may define the function `_go_to_page`, which will be passed in all of the keyword arguments from this keyword. This allows each page object to define its own URL mapping using whatever algorithm it chooses. The only requirement of the function is that it should compute an appropriate url and then call `self.selenium.go_to` with the URL.

It is also recommended that the keyword wait until it knows that the page has finished rendering before returning (eg: by calling `self.salesforce.wait_until_loading_is_complete()`)

Load the keywords for the page object identified by the type and object name

The page type / object name pair must have been registered using the cumulusci.robotframework.pageobject decorator.

Logs page objects and their keywords for all page objects which have been imported into the current suite.

Wait for the given page object modal to appear.

This will wait for modal to appear. If an expected heading is provided, it will also validate that the modal has the expected heading.

Example:

Wait for modal to appear    New    Contact   expected_heading=New Contact

Wait for an element represented by a page object to appear on the page.

The associated page object will be loaded after the element appears.

page_type represents the page type (Home, Details, etc)) and object_name represents the name of an object (Contact, Organization, etc)

Serves as a breakpoint for the robot debugger

Note: this keyword is a no-op unless the debug option for the task has been set to True. Unless the option has been set, this keyword will have no effect on a running test.

Clicks a link in record header.

Clicks a button in a Lightning modal.

Clicks a button in an object's actions.

Clicks a link in the related list with the specified heading.

This keyword will automatically call Wait until loading is complete.

Clicks a link in the popup menu for a related list item.

heading specifies the name of the list, title specifies the name of the item, and link specifies the name of the link

Clicks a button in the heading of a related list.

Waits for a modal to open after clicking the button.

Closes the open modal

Call the Create Webdriver keyword.

Retry on connection resets which can happen if custom domain propagation is slow.

Validates the currently selected Salesforce App

Deletes records that were created while running this test case.

(Only records specifically recorded using the Store Session Record keyword are deleted.)

For records representing jobs or processes, compare the record's start-time to its end-time to see how long a process took.

Arguments: obj_name: SObject to look for last record start_field: Name of the datetime field that represents the process start end_field: Name of the datetime field that represents the process end order_by: Field name to order by. Should be a datetime field, and usually is just the same as end_field. where: Optional Where-clause to use for filtering Other keywords are used for filtering as in the Salesforce Query keywordf

The last matching record queried and summarized.

Example: ${time_in_seconds} = Elapsed Time For Last Record ... obj_name=AsyncApexJob ... where=ApexClass.Name='BlahBlah' ... start_field=CreatedDate ... end_field=CompletedDate ... order_by=CompletedDate

Verify that the form field for the given label is the expected value

Example:

Field value should be    Account Name    ACME Labs

Generate bulk test data

This returns an array of dictionaries with template-formatted arguments which can be passed to the Salesforce Collection Insert keyword.

You can use {{number}} to represent the unique index of the row in the list of rows. If the entire string consists of a number, Salesforce API will treat the value as a number.

Example:

The following example creates three new Contacts:

@{objects} =  Generate Test Data  Contact  3
...  Name=User {{number}}
...  Age={{number}}

The example code will generate Contact objects with these fields:

[{'Name': 'User 0', 'Age': '0'},
 {'Name': 'User 1', 'Age': '1'},
 {'Name': 'User 2', 'Age': '2'}]

Python Expression Syntax is allowed so computed templates like this are also allowed: {{1000 + number}}

Python operators can be used, but no functions or variables are provided, so mostly you just have access to mathematical and logical operators. The Python operators are described here:

https://www.digitalocean.com/community/tutorials/how-to-do-math-in-python-3-with-operators

Contact the CCI team if you have a use-case that could benefit from more expression language power.

Templates can also be based on faker patterns like those described here:

https://faker.readthedocs.io/en/master/providers.html

Most examples can be pasted into templates verbatim:

@{objects}=  Generate Test Data  Contact  200
...  Name={{fake.first_name}} {{fake.last_name}}
...  MailingStreet={{fake.street_address}}
...  MailingCity=New York
...  MailingState=NY
...  MailingPostalCode=12345
...  Email={{fake.email(domain="salesforce.com")}}

Return the id of all open browser ids

Parses the current url to get the object id of the current record. Expects url format like: [a-zA-Z0-9]{15,18}

Return fake data

This uses the Faker library to provide fake data in a variety of formats (names, addresses, credit card numbers, dates, phone numbers, etc) and locales (en_US, fr_FR, etc).

The fake argument is the name of a faker property such as first_name, address, lorem, etc. Additional arguments depend on type of data requested. For a comprehensive list of the types of fake data that can be generated see Faker providers in the Faker documentation.

The return value is typically a string, though in some cases some other type of object will be returned. For example, the date_between fake returns a datetime.date object. Each time a piece of fake data is requested it will be regenerated, so that multiple calls will usually return different data.

This keyword can also be called using robot's extended variable syntax using the variable ${faker}. In such a case, the data being asked for is a method call and arguments must be enclosed in parentheses and be quoted. Arguments should not be quoted when using the keyword.

To generate fake data for a locale other than en_US, use the keyword Set Faker Locale prior to calling this keyword.

Examples

# Generate a fake first name
${first_name}=  Get fake data  first_name

# Generate a fake date in the default format
${date}=  Get fake data  date

# Generate a fake date with an explicit format
${date}=  Get fake data  date  pattern=%Y-%m-%d

# Generate a fake date using extended variable syntax
Input text  //input  ${faker.date(pattern='%Y-%m-%d')}

Return the current value of a form field based on the field label

Returns a rendered locator string from the Salesforce lex_locators dictionary. This can be useful if you want to use an element in a different way than the built in keywords allow.

Returns the Record Type Id for a record type name

Returns the number of items indicated for a related list.

Navigates to the Home view of a Salesforce Object

Navigates to the Home view of a Salesforce Object

Navigates to the Home view of a Salesforce Object

Navigates to the Home tab of Salesforce Setup

Navigates to the Object Manager tab of Salesforce Setup

Validates that a checkbox field in the record header is checked

Validates that a checkbox field in the record header is unchecked

Validates that a field in the record header has a link as its value

Validates that a field in the record header has a text value. NOTE: Use other keywords for non-string value types

Validates that a field in the record header does not have a link as its value

Validates that a field in the record header does not have a value. NOTE: Use other keywords for non-string value types

Initialize the Salesforce custom location strategies

Note: This keyword is called automatically from Open Test Browser

Fill in one or more labeled input fields fields with data

Arguments should be pairs of field labels and values. Labels for required fields should not include the asterisk. Labels must be exact, including case.

This keyword uses the keyword Locate Element by Label to locate elements. More details about how elements are found are in the documentation for that keyword.

For most input form fields the actual value string will be used. For a checkbox, passing the value "checked" will check the checkbox and any other value will uncheck it. Using "unchecked" is recommended for clarity.

Example:

Input form data
...  Opportunity Name         The big one       # required text field
...  Amount                   1b                # currency field
...  Close Date               4/01/2022         # date field
...  Private                  checked           # checkbox
...  Type                     New Customer      # combobox
...  Primary Campaign Source  The Big Campaign  # picklist

This keyword will eventually replace the "populate form" keyword once it has been more thoroughly tested in production.

Scrolls down until the specified related list loads.

If the related list isn't found, the keyword will scroll down in 100 pixel increments to trigger lightning into loading the list. This process of scrolling will be repeated until the related list has been loaded or we've tried several times (the default is 10 tries)

Find a lightning component, input, or textarea based on a label

If the component is inside a fieldset, the fieldset label can be prefixed to the label with a double colon in order to disambiguate the label. (eg: Other address::First Name)

If the label is inside nested ligntning components (eg: <lightning-input>...<lightning-combobox>...<label>), the lightning component closest to the label will be returned (in this case, lightning-combobox).

If a lightning component cannot be found for the label, an attempt will be made to find an input or textarea associated with the label.

This is registered as a custom locator strategy named "label"

Example:

The following example is for a form with a formset named "Expected Delivery Date", and inside of that a date input field with a label of "Date".

These examples produce identical results:

${element}=  Locate element by label    Expected Delivery Date::Date
${element}=  Get webelement             label:Expected Delivery Date::Date

Logs all of the browser capabilities as reported by selenium

Opens the Saleforce App Launcher Modal

Note: starting with Spring '20 the app launcher button opens a menu rather than a modal. To maintain backwards compatibility, this keyword will continue to open the modal rather than the menu. If you need to interact with the app launcher menu, you will need to create a custom keyword.

If the retry parameter is true, the keyword will close and then re-open the app launcher if it times out while waiting for the dialog to open.

Enters a value into an input or textarea field.

'name' represents the label on the page (eg: "First Name"), and 'value' is the new value.

Any existing value will be replaced.

Enters multiple values from a mapping into form fields.

Enters a value into a lookup field.

Remove a record from the list of records that should be automatically removed.

Inserts records that were created with Generate Test Data.

objects is a list of data, typically generated by the Generate Test Data keyword.

A 200 record limit is enforced by the Salesforce APIs.

The object name and Id is passed to the Store Session Record keyword, and will be deleted when the keyword Delete Session Records is called.

As a best practice, either Delete Session Records or *Delete Records and Close Browser from Salesforce.robot should be called as a suite teardown.

Example:

@{objects}=  Generate Test Data  Contact  200
...  FirstName=User {{number}}
...  LastName={{fake.last_name}}
Salesforce Collection Insert  ${objects}

Updates records described as Robot/Python dictionaries.

objects is a dictionary of data in the format returned by the Salesforce Collection Insert keyword.

A 200 record limit is enforced by the Salesforce APIs.

Example:

The following example creates ten accounts and then updates the Rating from "Cold" to "Hot"

${data}=  Generate Test Data  Account  10
...  Name=Account #{{number}}
...  Rating=Cold
${accounts}=  Salesforce Collection Insert  ${data}

FOR  ${account}  IN  @{accounts}
    Set to dictionary  ${account}  Rating  Hot
END
Salesforce Collection Update  ${accounts}

Deletes a Salesforce object by object name and Id.

Example:

The following example assumes that ${contact id} has been previously set. The example deletes the Contact with that Id.

Salesforce Delete  Contact  ${contact id}

Gets a Salesforce object by Id and returns the result as a dict.

Example:

The following example assumes that ${contact id} has been previously set. The example retrieves the Contact object with that Id and then logs the Name field.

&{contact}=  Salesforce Get  Contact  ${contact id}
log  Contact name:  ${contact['Name']}

Creates a new Salesforce object and returns the Id.

The fields of the object may be defined with keyword arguments where the keyword name is the same as the field name.

The object name and Id is passed to the Store Session Record keyword, and will be deleted when the keyword Delete Session Records is called.

As a best practice, either Delete Session Records or Delete Records and Close Browser from Salesforce.robot should be called as a suite teardown.

Example:

The following example creates a new Contact with the first name of "Eleanor" and the last name of "Rigby".

${contact id}=  Salesforce Insert  Contact
...  FirstName=Eleanor
...  LastName=Rigby

Constructs and runs a simple SOQL query and returns a list of dictionaries.

By default the results will only contain object Ids. You can specify a SOQL SELECT clause via keyword arguments by passing a comma-separated list of fields with the select keyword argument.

You can supply keys and values to match against in keyword arguments, or a full SOQL where-clause in a keyword argument named where. If you supply both, they will be combined with a SOQL "AND".

order_by and limit keyword arguments are also supported as shown below.

Examples:

The following example searches for all Contacts where the first name is "Eleanor". It returns the "Name" and "Id" fields and logs them to the robot report:

@{records}=  Salesforce Query  Contact  select=Id,Name
...          FirstName=Eleanor
FOR  ${record}  IN  @{records}
    log  Name: ${record['Name']} Id: ${record['Id']}
END

Or with a WHERE-clause, we can look for the last contact where the first name is NOT Eleanor.

@{records}=  Salesforce Query  Contact  select=Id,Name
...          where=FirstName!='Eleanor'
...              order_by=LastName desc
...              limit=1

Updates a Salesforce object by Id.

The keyword returns the result from the underlying simple_salesforce insert method, which is an HTTP status code. As with `Salesforce Insert`, field values are specified as keyword arguments.

The following example assumes that ${contact id} has been previously set, and adds a Description to the given contact.

&{contact}=  Salesforce Update  Contact  ${contact id}
...  Description=This Contact created during a test
Should be equal as numbers ${result}  204

Scroll the element identified by 'locator'

This is a replacement for the keyword of the same name in SeleniumLibrary. The SeleniumLibrary implementation uses an unreliable method on Firefox. This keyword uses a more reliable technique.

For more info see https://stackoverflow.com/a/52045231/7432

Navigates to a Salesforce App via the App Launcher

Navigates to a tab via the App Launcher

Selects a record type while adding an object.

Alias for SeleniuimLibrary 'Switch Window'

This keyword was removed from SeleniumLibrary 5.x, but some of our tests still use this keyword. You can continue to use this, but should replace any calls to this keyword with calls to 'Switch Window' instead.

Run a single selenium command and retry once.

The retry happens for certain errors that are likely to be resolved by retrying.

Set the locale for fake data

This sets the locale for all calls to the Faker keyword and ${faker} variable. The default is en_US

For a list of supported locales see Localized Providers in the Faker documentation.

Example

Set Faker Locale    fr_FR
${french_address}=  Faker  address

This keyword captures a computed rather than measured elapsed time for performance tests.

For example, if you were performance testing a Salesforce batch process, you might want to store the Salesforce-measured elapsed time of the batch process instead of the time measured in the CCI client process.

The keyword takes a single argument which is either a number of seconds or a Robot time string (https://robotframework.org/robotframework/latest/libraries/DateTime.html#Time%20formats).

Using this keyword will automatically add the tag cci_metric_elapsed_time to the test case and ${cci_metric_elapsed_time} to the test's variables. cci_metric_elapsed_time is not included in Robot's html statistical roll-ups.

Example:

Set Test Elapsed Time 11655.9

Performance test times are output in the CCI logs and are captured in MetaCI instead of the "total elapsed time" measured by Robot Framework. The Robot "test message" is also updated.

This keyword captures any metric for performance monitoring.

For example: number of queries, rows processed, CPU usage, etc.

The keyword takes a metric name, which can be any string, and a value, which can be any number.

Using this keyword will automatically add the tag cci_metric to the test case and ${cci_metric_<metric_name>} to the test's variables. These permit downstream processing in tools like CCI and MetaCI.

cci_metric is not included in Robot's html statistical roll-ups.

Example:

Set Test Metric    Max_CPU_Percent    30

Performance test metrics are output in the CCI logs, log.html and output.xml. MetaCI captures them but does not currently have a user interface for displaying them.

Runs a simple SOQL query and returns the dict results

The query parameter must be a properly quoted SOQL query statement. The return value is a dictionary. The dictionary contains the keys as documented for the raw API call. The most useful key is records, which contains a list of records which were matched by the query.

Example

The following example searches for all Contacts with a first name of "Eleanor" and a last name of "Rigby", and then prints the name of the first record found.

${result}=  SOQL Query
...  SELECT Name, Id FROM Contact WHERE FirstName='Eleanor' AND LastName='Rigby'
Run keyword if  len($result['records']) == 0  Fail  No records found

${contact}=  Get from list  ${result['records']}  0
Should be equal  ${contact['Name']}  Eleanor Rigby

Start an elapsed time stopwatch for performance tests.

See the docummentation for *Stop Performance Timer* for more information.

Example:

Start Performance Timer Do Something Stop Performance Timer

Record the results of a stopwatch. For perf testing.

This keyword uses Set Test Elapsed Time internally and therefore outputs in all of the ways described there.

Example:

Start Performance Timer Do Something Stop Performance Timer

Stores a Salesforce record's Id for use in the Delete Session Records keyword.

This keyword is automatically called by Salesforce Insert.

Run the WAIT_FOR_AURA_SCRIPT.

This script polls Aura via $A in Javascript to determine when all in-flight XHTTP requests have completed before continuing.

Wait for LEX page to load.

(We're actually waiting for the actions ribbon to appear.)

Wait for modal to close

Wait for modal to open

Waits until we are able to render the initial salesforce landing page

It will continue to refresh the page until we land on a lightning page or until a timeout has been reached. The timeout can be specified in any time string supported by robot (eg: number of seconds, "3 minutes", etc.). If not specified, the default selenium timeout will be used.

This keyword will wait a few seconds between each refresh, as well as wait after each refresh for the page to fully render (ie: it calls wait_for_aura())

Sets the 'options.binary_location' value in the chrome options dictionary to the value of the environment variable CHROME_BINARY, if set.

This keyword is not intended to be used by test scripts

This keyword is used to set the chrome options dictionary values required to run headless chrome.

This keyword is not intended to be used by test scripts

This will close all open browser windows and then delete all records that were created with the Salesforce API during this testing session.

Returns a dictionary of chrome options, for use by the keyword `Open Test Browser`.

This keyword is not intended to be used by test scripts.

This is registered as a custom locator strategy named text. It is shorthand for the locator //*[text()=...]

Example:

Wait until page contains element text:Mobile Publisher

This is registered as a custom locator strategy named title. It is shorthand for the locator //*[@title=...]

Example:

Wait until page contains element title:Object Manager

Opens a test browser to the org.

The variable ${BROWSER} determines which browser should open. The following four browsers are explicitly supported: chrome, firefox, headlesschrome, and headlessfirefox. Any other value will be passed directly to the SeleniumLibrary 'Open Browser' keyword.

Once the browser has been opened, it will be set to the given size (default=${DEFAULT BROWSER SIZE})

If you open multiple browsers you can use the optional argument `alias` to give each browser a name. This name can be used when calling the `Switch Browser` keyword from SeleniumLibrary

The optional argument 'useralias' may be used to specify a specific user by their alias; if not specified then the org's default user will be used.

The keyword `Log Browser Capabilities` will automatically be called. The keyword will also call `Wait Until Salesforce is Ready` unless the `wait` parameter is set to False.

Opens a Chrome browser window and navigates to the org This keyword isn't normally called directly by a test. It is used by the `Open Test Browser` keyword.

Opens a Firefox browser window and navigates to the org This keyword isn't normally called directly by a test. It is used by the `Open Test Browser` keyword.

Opens the firefox browser in headless mode This keyword isn't normally called directly by a test. It is used by the `Open Test Browser` keyword.

Logs the name of the current page object

The current page object is also returned as an object

Click the named modal button (Save, Save & New, Cancel, etc)

Closes the open modal

Logs the name of the current page object

The current page object is also returned as an object

Verify that the modal contains the following errors

This will look for the given message in the standard SLDS component (<ul class='errorsList'>)

Verify that a dialog is showing requiring a review of the given fields

This works by looking for a the "we hit a snag" popup, and then looking for an anchor tag with the attribute force-recordediterror_recordediterror, along with the given text.

Populate a field on the modal form

Name must the the label of a field as it appears on the modal form.

Example

Populate field  First Name  Connor
Populate field  Last Name   MacLeod

Populate the modal form

Arguments are of the form key=value, where 'key' represents a field name as it appears on the form (specifically, the text of a label with the class 'uiLabel').

Example:

Populate form
...  First Name=Connor
...  Last Name=MacLeod

Sets the value of a dropdown form field from one of the values in the dropdown

label represents the label on the form field (eg: Lead Source)

If a modal is present, the modal will be searched for the dropdown. Otherwise the first matching dropdown on the entire web page will be used.

Waits until the modal is no longer visible

If the modal isn't open, this will not throw an error.

Logs the name of the current page object

The current page object is also returned as an object

Logs the name of the current page object

The current page object is also returned as an object

Click the named modal button (Save, Save & New, Cancel, etc)

Closes the open modal

Logs the name of the current page object

The current page object is also returned as an object

Verify that the modal contains the following errors

This will look for the given message in the standard SLDS component (<ul class='errorsList'>)

Verify that a dialog is showing requiring a review of the given fields

This works by looking for a the "we hit a snag" popup, and then looking for an anchor tag with the attribute force-recordediterror_recordediterror, along with the given text.

Populate a field on the modal form

Name must the the label of a field as it appears on the modal form.

Example

Populate field  First Name  Connor
Populate field  Last Name   MacLeod

Populate the modal form

Arguments are of the form key=value, where 'key' represents a field name as it appears on the form (specifically, the text of a label with the class 'uiLabel').

Example:

Populate form
...  First Name=Connor
...  Last Name=MacLeod

Sets the value of a dropdown form field from one of the values in the dropdown

label represents the label on the form field (eg: Lead Source)

If a modal is present, the modal will be searched for the dropdown. Otherwise the first matching dropdown on the entire web page will be used.

Waits until the modal is no longer visible

If the modal isn't open, this will not throw an error.