Skip to main content
Version: 10.3

Simplified Robotics API cheatsheet

tip

The article contains a cheatsheet for using the main Robotics simplified API methods.

Selectors (locators)​

note

Before interacting with a UI element, locate it using the $() or $$() constructions.

$(), $$()​

// locating and manipulating element
UiElement uiElement = $(".css-class");
uiElement.doubleClick()

$(byLinkText("Purchase")).click();

// navigating to hidden element
$(".TreeNode").focus();

// finding the Nth element matching given criteria
$(withText("Open", 5)).hover();

// locating focused element
UiElement focusedEl = getFocusedElement()
if (focusedEl.getId() == "tuk-tuk") { focusedEl().click(2) }

// using element collections
UiElementCollection fieldCollection = $$(byXpath("//*[@name='field-product']"))
fieldCollection.each {
    println it.getText()
}

// getting element from collection
fieldCollection.last().val("butter")
UiElement firstField = fieldCollection.first()
UiElement sixthField = fieldCollection.get(5)

// filtering collection by condition
UiElement readonlyCollection = fieldCollection.filter(READONLY)
UiElement inactiveReadonlyCollection = readonlyCollection.exclude(cssClass("temp"))

// searching child elements
$(byTitle("Web Form")).find("div > table > tr:nth-child(5) > td").click()
int childRowCollection = $("#multirowTable").findAll("tr.active")

// searching parent and ancestor elements
UiElement parentClass = $("td").parent().getAttribute("class")
UiElement ancestorText = $("#exp-0").closest("div").text()

// alternatives to $() and $$()
getElement(byImage("https://site/img1.png"), 200, 300).click()
WebElement abbreviations = getElements(byTagName("abbr"))

Selector types​

Web:
    byCssSelector      // default, same as $('.selector')
    byXpath

    byId
    byName
    byClassName
    byTagName
    byTitle
    byValue
    by('attribute_name', 'attribute_name')
    byAttribute('name','value')

    withText
    byText
    byLinkText
    byPartialLinkText


Desktop:
    CSS selectors      // $('.Button[text='Click me']')
    Object selectors   // $('[CLASS:Button; INSTANCE:2]')
    byXpath            // for Java apps only
    byImage('link', offsetX, offsetY)

Opening apps and browsers​

open(), openAndFocus(), openIE()​

// open a website
open("https://www.wikipedia.org")

// open an application
open("calc.exe")

// open an app and switch to the newly opened window
openAndFocus("notepad.exe", 3000, 250)

// in Universal driver, you can open a specific browser
openFirefox("https://www.wikipedia.org")
openChrome("https://workfusion.com")
openIE("https://google.com/chrome/browser/desktop/index.html")
openEdge("https://edition.cnn.com")

// opening new browser tabs
openLinkInNewWindow(byCssSelector(".container a.create-new"))
openLinkInNewWindow("https://automationacademy.com")
openNewWindow()

Excel, files and folders​

openExcel(), Resource, downloadFileOnAgent()​

// opening excel file for manipulating it
String filePath = "C:/downloads/report.xlsx"
openExcel(filePath)
switchSheet(filePath, "Fact")
String temp = getCell(filePath, "B1")

// manipulating with local files and folders
String filePath = downloadFileOnAgent(s3Path)
Resource.append(filePath, "___ New Content ___", "utf-8")
String content_utf8 = Resource.read(filePath, 'utf-8')
Resource.createDirectoryOverwrite("D:\\temp\\new\\"")

// downloading and uploading files to/from RPA Server
String filePathOnAgent = downloadFileOnAgent("https://s3-path/1.csv")
downloadFileOnAgent("https://s3-path/1.csv", "C:/Temp/new-file.csv")

byte[] byteFileContent = downloadFileFromAgent("C:/Temp/1.csv")
String stringFileContent = downloadTextFileFromAgent("C:/Temp/2.csv")

deleteFileOnAgent("C:/Temp/1.csv")

def textFilePath = sendToAgent("new file text content")
def binaryFilePath = sendToAgent(byteFileContent, "D:/new/new-file.csv")
tip

Mouse​

click(), hover(), dragAndDrop()​

// clicking in different ways
$('#nav-bar').click()
$$(byTagName('p')).get(2).click(3)  // or tripleClick(), doubleClick()
$('#nav-bar').contextClick()

// clicking by coordinates
mouse().click(20, 20)
mouse().wheelClick(100, 78)

mouseDown(coordinates)
mouseUp(int,int)

// moving mouse, hovering, scrolling
mouseMove(100, 500)
$('#nav-bar').hover()
$('#nav-bar').scrollTo()
$('#nav-bar').scrollDown(7)   // or scrollUp(5)

// submitting forms
$('.btn__act').submit()

// clicking with offset
$('.MyMenu').click(20,135)

// drag and drop by selectors or coordinates offset
actions().dragAndDrop($(byImage("${imagePath}/source.png")), xOffset, yOffset)
         .perform()

actions().clickAndHold($(byImage("${imagePath}/image.png")))
         .moveToElement($(byImage("${imagePath}/image.png")))
         .release($(byImage("${imagePath}/image.png")))
         .perform()

actions().dragAndDrop(
         $(byImage("${imagePath}/source-folder.png")),
         $(byImage("${imagePath}/target-folder.png")))
         .perform()
tip

See more about advanced user interactions.

Keyboard​

sendKeys(), pressEnter(), Keys.chord()​

// sending text
$("#input-username").sendKeys("Jimmy")

// sending multiple keys sequentially
sendKeys(Keys.DOWN, Keys.ENTER)

// sending key combinations
sendKeys(Keys.chord(Keys.CONTROL, "a"))

// holding keys to perform complex actions
keyboard().pressKey(Keys.SHIFT)
sendKeys(Keys.DOWN, Keys.DOWN)
keyboard().releaseKey(Keys.SHIFT)

// pressing popular keys and combinations
pressCtrlC()
pressCtrlV()
pressEnter()

// combining text and action keys
sendKeys("username{Enter}")
// will type the "username" and press Enter key

// switching to raw keys mode
switchSendRawKeysMode(true)
sendKeys("username{Enter}")
// will type the "username{Enter}" string
// without pressing the Enter key


// typing into window regardless of its active language
sendKeys("{UTF 怒helloनमस्ते}")


// typing DEL 4 times
sendKeys("{DEL 4}")
tip

To learn more about Web and Desktop keystrokes, refer to SendKeys keystrokes.

Conditions and assertions​

should(), has(), is()​

$(byXpath("//p[2]")).shouldHave(text("Hello"))
$('.loading_progress').should(DISAPPEAR)
$("input").shouldNotHave(cssClass("active"))
$("#mydiv").shouldHave(attribute("fileId"))
$(withText("Your message has been sent.")).shouldBe(VISIBLE)
$("h1").should(matchRegexp("Hello\s*John"))
$("#logoutLink").should(APPEAR)
$("#myInput").waitUntil(partialValue("John"), 5000)

$$(".errorMessage").first().shouldBe(VISIBLE, ENABLED)
$$("td").shouldHaveSize(5)

$("#errorMessage").should(APPEAR).shouldBe(ENABLED)
AssertionConditionsLogical operators
  • should()
  • shouldNot()
  • shouldHave()
  • shouldNotHave()
  • shouldBe()
  • shouldNotBe()
  • has()
  • is()
  • hasPartialValue()
  • shouldHaveSize(n)
  • APPEAR
  • DISABLED
  • DISAPPEAR
  • EMPTY_ELEMENT
  • ENABLED
  • EXIST
  • FOCUSED
  • HIDDEN
  • PRESENT
  • READONLY
  • SELECTED
  • VISIBLE
  • cssClass()
  • attribute()
  • text()
  • textCaseInSensitive()
  • matchRegexp()
  • value()
  • partialValue()
  • id()
  • name()
  • type()
  • and(name, conditions)
  • or(name, conditions)
  • not(condition)
tip

Windows and frames​

// switching to window by its attribute
switchTo().window("[CLASS:Notepad]")
window("[TITLE:Photoshop]")

// works faster than window()
switchToExistingWindow("[CLASS:Notepad]", 100L)

// switching to window by its order
switchToLastWindow()
switchToRootWindow()
switchToPrevWindow()
switchToNextWindow()

// switching to iframe
switchTo().frame("iframeResult")
switchTo().parentFrame()
switchTo().defaultContent()

// closing window(s)
close()
closeAllAnotherWindows()
closeAllWindows()

// Changing window size
minimizeWindow()
maximizeWindow()
zoom(2.5)

// navigation in history
forward()
back()
refresh() // only for web

// Handling popups and alerts
confirm()
confirm("Do you want to exit?")
dismiss()
tip

Timeouts and waits​

// setting timeouts for different actions (milliseconds)
pageLoadTimeout(5000)        // for open(), openAndFocus(), switch() - web or window
implicitlyWaitTimeout(3000)  // used for finding element $(); collections $$() do not use timeout
scriptTimeout(30 * 1000)     // for JavaScript or Groovy scripts

// setting all timeouts in one command
timeouts(40 * 1000)

// set timeout for explicit waits
setFluentWaitTimeout(3 * 1000)
setFluentWaitPollingInterval(200)

// check the existence of element - if it might be missing
fluentWait()
  .ignoring(org.openqa.selenium.NoSuchElementException.class)
  .until(ExpectedConditions.presenceOfElementLocated(byCssSelector("#new")))

// explicit wait usage, only for elements which exist
$(".demo-el").waitUntil(VISIBLE)
$(".demo-el").waitWhile(SELECTED)

Wait()
  .withMessage("message")
  .withTimeout(5, java.util.concurrent.TimeUnit.SECONDS)
  .pollingEvery(500, java.util.concurrent.TimeUnit.MILLISECONDS)
  .until(...)

// explicit wait with custom timeout and polling interval
$(".demo-el").waitWhile(READONLY, 3000, 200)

// pausing script execution - not recommended in production
sleep(3000)
tip

WebDriver waits

Clipboard​

// copying to clipboard
selectAllTextAndCopy()
pressCtrlC()

$("p.news").tripleClick()
copySelectedText()

copyPuttyWindowText()

// getting clipboard text
String clipboard = clipboardText()
$(byXpath("//input[3]")).pressCtrlV()

// setting clipboard text
setClipboardText("new_content")

Screenshots​

// desktop - using org.sikuli.script or java.awt.Robot
String path = executeGroovyScript(javaScreenshot.toString())

// browser
byte[] screen = driver().getScreenshotAs(OutputType.BYTES)  // or BASE64, FILE
byte[] bytes = screenshotAsImage()
tip

Taking screenshots

Get and set value​

// getting value, text, attribute
String emailValue = $("#email").val()          // or getValue()
String iNumber = $("#invoice-n").attr("name")  //or getAttribute(), name()
String someText = $(byXpath("//p[2]")).text()  // or getText()
String[] allPosts = $$("p.content").getTexts()
String tag = $(".btn").getTagName()

// setting value and text
$("#email").val("wf-robot@mail.com") // or setValue()
$(byXpath("//input[3]")).text("new text")

// resetting field text
$$(".nav").get(5).clear()

// getting location and coordinates
$(byImage("${imageLink}")).getRect().getWidth()
$(byImage("${imageLink}")).getLocation()
$(withText("create")).getSize()

// radio-buttons
UiElementCollection oRadioButton = $$(byName("occupation"))
if (oRadioButton.get(0).isSelected()) {
  oRadioButton.get(1).setSelected(true)
}

// dropdowns
UiElement optionsList = $(byId("continents"))
optionsList.selectOption(2)
optionsList.selectOptionByValue("AFR")

println optionsList.getSelectedText()
println optionsList.getSelectedValue()
println optionsList.getSelectedOption().getText()
tip

CheckBox, RadioButton, DropDown, MultipleSelect

Scripting​

// executing a Groovy Script on RPA Node
Object scriptResult = executeGroovyScript(console_script.toString())

// JavaScript or AutoIt
def messages = ['Hello ', 'from ']
executeScript("alert(arguments[0][0] + arguments[0][1] + arguments[1])", messages, 'JS')
// Output: "Hello from JS"
tip

JavaScriptExecutor

Explicitly set driver in Universal Script​

import com.workfusion.odf2.compiler.BotTask;
import com.workfusion.odf2.core.task.AdHocTask;
import com.workfusion.odf2.core.task.TaskInput;
import com.workfusion.odf2.core.task.output.TaskRunnerOutput;
import com.workfusion.odf2.core.webharvest.rpa.RpaDriver;
import com.workfusion.odf2.core.webharvest.rpa.RpaFactory;
import com.workfusion.odf2.core.webharvest.rpa.RpaRunner;
import com.workfusion.rpa.driver.Driver;
import com.workfusion.rpa.helpers.RPA;
import org.openqa.selenium.By;
import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.WebElement;
import org.slf4j.Logger;

import javax.inject.Inject;

import static com.workfusion.rpa.helpers.RPA.$;
import static com.workfusion.rpa.helpers.UiConditions.text;

@BotTask(requireRpa = true)
@Requires({ControlTowerServicesModule.class})
public class ApplyUniversalRPADriver implements AdHocTask {

    private final RpaRunner rpaRunner;
    private final Logger logger;
    private final SecretsVaultService secretsVault;
    @Inject
    public ApplyUniversalRPADriver(RpaFactory rpaFactory, Logger logger, SecretsVaultService secretsVault){
        this.rpaRunner = rpaFactory
                .builder(RpaDriver.UNIVERSAL)
                .closeOnCompletion(true)
                .build();
        this.logger = logger;
        this.secretsVault = secretsVault;
    }

    @Override
    public TaskRunnerOutput run(TaskInput taskInput) {

        rpaRunner.execute(driver ->{
            this.universalDriverClouser(driver);
        });

        return taskInput.asResult()
                .withColumn("example_bot_task_output", "completed_successfully");
    }

    private void firefoxJobClouser(Driver driver){
        RPA.openFirefox("https://train-invoiceplane.workfusion.com");
        $("#login").click();
        SecureEntryDTO secureEntry = secretsVault.getEntry("robotCredentials");
        $("#email").val(secureEntry.getKey());
        $("#password").val(secureEntry.getValue());
        $(By.name("btn_login")).click();
    }
    private void chromeJobClouser(Driver driver){
        RPA.openChrome("https://www.w3schools.com/xml/tryit.asp?filename=tryajax_first");
        RPA.switchTo().frame("iframeResult");
        $("#demo > h1").shouldHave(text("The XMLHttpRequest Object"));
        RPA.sleep(2000);
        $("#demo > button").shouldHave(text("Change Content")).click();
    }

    private void ieJobClouser(Driver driver){
        RPA.openIE("https://www.google.com/");
        driver.findElement(By.id("APjFqb")).sendKeys("RPA");
        RPA.pressEnter();
        RPA.sleep(2000);
    }
    private void notepadJobClouser(Driver driver){
        //driver.switchDriver("universal");
        RPA.sleep(2000);
        RPA.open("notepad");
        RPA.sleep(2000);
        RPA.switchTo().window("[CLASS:Notepad]");
        RPA.sendKeys("foo");
    }

    private void universalDriverClouser(Driver driver){

        // open a web-application in Firefox and log in
        this.firefoxJobClouser(driver);
        RPA.sleep(2000);

        // open a web-page in Chrome and click
        this.chromeJobClouser(driver);
        RPA.sleep(2000);

        // open a web-page in Internet Explorer, enter text, and click
        //this.ieJobClouser(driver);

        // open notepad and type text into it
        this.notepadJobClouser(driver);
    }

}