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
- For the Excel API description, refer to Excel Class.
- For the files and folders API, Files and Folders | Resource Class.
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)
| Assertion | Conditions | Logical operators |
|---|---|---|
|
|
|
tip
UIConditionsclassExpectedConditionsclass
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()
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)
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()
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()
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"
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);
}
}