Interface ElementParent

The interface ElementParent provides abstraction of a 'parent' for an UI element.

public interface ElementParent<UI extends UiElement, L extends ElementLocator<UI>> {
...
}

Both Driver and UiElement extends this common interface and provide the same set of basic functionality described below.

Locating functions

There are two functions that accept an element locator and return either single UI element or list of UI elements.

A 'relative' locator should be supplied if find called on a UI element. In this case search will be done across elements children
(at the moment make sense only for BrowserElement, JavaElement and DesktopElement).
An 'absolute' locator should be supplied if find called on a Driver. In this case search always will be performed across all elements.

findElement

It is used to find an element that is present now, throws an exception if no matching elements are found.

UI findElement(L by);

findElements

Similar to "findElement", but returns a list of matching UI Elements (or empty list if nothing has been found). To use a particular UI Element from the list, you need to loop over the list of elements to perform action on selected element.

List<UI> findElements(L by);

Waiting functions

There are some functions that provides explicitly wait mechanism. They could be obtaining an UI Element or wait event on a page. Default waiting intervals are set in driver parameters (see @Driver and DriverParams)

All the functions has last parameter:

int... timeouts
timeouts optional wait intervals: 
 timeouts[0] - waiting interval in seconds
 timeouts[1] - polling interval in milliseconds

It allows specify timeout directly or use defaults by omit them.

waitForElement

Obtaining element by explicitly wait - call "findElement" till result has been found or until specified timeout. It also supports optional parameter which suppress an exception in case of "true" value and method returns "null" instead.

UI waitForElement(L locator, int... timeouts)
UI waitForElement(L locator, boolean optional, int... timeouts)

waitFor

This methods wait something that is defined by a waiting function. There are lot of pre-defined condition functions defined ExpectedConditions class, for example:

public class ExpectedConditions {
	public static <D extends Driver<UI>, UI extends UiElement> Function<D, Boolean> titleIs(String title) . . .
	public static <P extends ElementParent<UI, L>, UI extends UiElement, L extends ElementLocator<UI>> Function<P, UI> presenceOfElementLocated(L locator) . . .
	public static <UI extends UiElement> Function<UI, UI> visibilityOfElement() . . . 
	public static <P extends ElementParent<UI, L>, UI extends UiElement, L extends ElementLocator<UI>> Function<P, UI> visibilityOfElementLocated(L locator) . . .
	public static <UI extends UiElement, L extends ElementLocator<UI>> Function<UI, UI> elementToBeClickable()	. . . 
	public static <P extends ElementParent<UI, L>, UI extends UiElement, L extends ElementLocator<UI>> Function<P, UI> elementToBeClickable(L locator)	. . .
	public static <P extends ElementParent<UI, L>, UI extends UiElement, L extends ElementLocator<UI>> Function<P, Boolean> textToBePresentInElementValue(L locator, String text) . . .
	. . . 
}

The result of wait could be any object, there are lot of expected conditions return UIElement as a result.

<V> V waitFor(Supplier<V> supplier, int... timeouts) 
<V> V waitFor(Supplier<V> supplier, boolean optional, int... timeouts)
<P extends ElementParent<UI, L>, V> V waitFor(Function<P, V> function, int... timeouts)
<P extends ElementParent<UI, L>, V> V waitFor(Function<P, V> function, boolean optional, int... timeouts)

Examples

Below you can find some examples.

Locate menu inside a table row and click delete

	@FindBy(xpath = ".//tbody/tr")
	@Wait(required = false)
	private List<BrowserElement> items;
	
	public boolean deleteRow(int i) {
		BrowserElement el = items.get(i).waitFor(visibilityOfElementLocated(xpath(".//div[contains(@class,'options')]//a")), 1);
		if (el != null) {
			el.click();
			try {
				el = el.waitFor(visibilityOfElementLocated(xpath(".//..//li//form//button[contains(@class,'dropdown-button')]")), 1);
			} catch (Exception e) {
				log.warn("There is not delete button in options for row {}", i);
			}
			if (el != null) {
				el.click();
				el.getDriver().confirmAlert();
				return true;
			}
		}
		return false;
	}

Wait for save is completed

	public void waitForSave(Consumer<Exception> consumer) {
		// Wait for save is completed
		try {
			getDriver().waitFor(invisibilityOfElementLocated(BrowserSearch.cssSelector("#fullpage-loader")), 10);
		} catch (Exception e) {
			consumer.accept(e);
		}
	}

Interface Driver

The interface Driver provides API methods to interact with drivers in the same manner. This interface is implemented by the following classes:

BrowserDriver - to work with web-applications
DesktopDriver - to work with desktop applications (except Java application)
JavaDriver - to work with Java desktop applications
SapDriver - to work with SAP applications
ScreenDriver - to work with the any applications on image-based approach

Here are the list on driver methods:

get
getTitle
initPage
getInputDevices
getScreenshot
getScreenshotAsBytes
getScreenshotAsFile
getScreenshotAsBase64
findElement
findElements
clipboard
waitForElement
waitFor
linkApplication
getActiveWindow
getImplementation
quit

Work with an driver OS application

The driver has the following common methods to work with driver focused OS application, like open/close application.

get(String ...)

The first thing you will want to do after launching a bot is to open your application. This methods is used to open an application / website and it accepts the executable file path / website link (depends on driver type).

Depending on drivers, it has different arguments meaning. In additional every driver provides overloaded methods for more specific cases.

public void get(String ... params)

getTitle()

Returns the current driver focused application title.

public String getTitle()

quit()

Closes all opened OS application, and associated Page Object applications, then release driver resources.

This methods should not be called in case is driver obtained in task using @Driver annotation. The platform calls it automatically after task completes.

public void quit()

Window management

You can get the Window object to manage it (to change and get the size, change position). It returns the interface for managing the current window

getActiveWindow

public Window getActiveWindow()

Take screenshots

There are the following methods to obtain screenshots:

getScreenshot

public <X> X getScreenshot(Function<byte[], X> converter)

getScreenshotAsBytes

public byte[] getScreenshotAsBytes()

getScreenshotAsFile

public File getScreenshotAsFile()

getScreenshotAsBase64

public String getScreenshotAsBase64()

Get UI Elements

Elements could be obtained using ElementLocator. Here are the possible element locators:

BrowserSearch
JavaSearch
DesktopSearch
SapSearch
ScreenSearch

Each driver has its own specific type of elements and specific way to build the element locator. Refer to specific driver page. Here is example of some locators defined for BrowserDriver:

public class BrowserSearch implements ElementLocator<BrowserElement, BrowserDriver> {
	public static BrowserSearch id(String id) . . .
	public static BrowserSearch xpath(String xpath) . . .
	public static BrowserSearch cssSelector(String css) . . .
	. . . . .
}

Integration with Page Objects

The are some methods that is used for Page Object driver integration.

initPage(Page page)

Initializes a page object.

public void initPage(Page page)

linkApplication(AutoCloseable app)

Links an Application to the driver. Closes the linked application during driver quit().

public void linkApplication(AutoCloseable app)

Keyboard, Mouse, Clipboard

getInputDevices

Method which is supported by all drivers returns an abstraction which lets you access to Mouse and Keyboard devices (has appropriate getters).

public InputDevices getInputDevices()

For example:

import eu.ibagroup.easyrpa.engine.rpa.interactions.InputDevices;
import eu.ibagroup.easyrpa.engine.rpa.interactions.Mouse;
import eu.ibagroup.easyrpa.engine.rpa.interactions.Keyboard;

InputDevices inputDevices = driver.getInputDevices();
Mouse mouse = inputDevices.getMouse();
Keyboard keyboard = inputDevices.getKeyboard();

getKeyboard

This method returns an abstraction (Keyboard object) which allows you to perform an actions with the keyboard, such as sending, pressing and releasing keys.

public Keyboard getKeyboard()

The short example of how to press the "Ctrl + S" combination which is usually responsible for saving:

import eu.ibagroup.easyrpa.engine.rpa.interactions.Keyboard;
import org.openqa.selenium.Keys;

Keyboard keyboard = driver.getInputDevices().getKeyboard();
keyboard.pressKey(Keys.CONTROL);
keyboard.sendKeys("s");
keyboard.releaseKey(Keys.CONTROL);

It's important to use the keys constants from org.openqa.selenium.Keys.

Also it's important to have the same keyboard language selected in Windows tray menu as the characters language you send to keyboard methods. Otherwise you'll get an exception

getMouse

Before start using mouse actions, make sure your Windows display scaling is set up to 100%, otherwise a Robot will not be able to click on the needed elements.

Go to Start > Settings > System > Display.
In Scale and Layout, select 100% for Change the size of text, apps, and other items. The changes apply automatically.

This method returns an abstraction (Mouse object) which allows you to perform an actions with the mouse, such as right and left buttons clicking, mouse moving, doubleclicking.

public Mouse getMouse()

Mouse object has various type of methods to perform clicking, mouse moving and etc. which accept arguments such as "x" and "y" integer coordinates, Point object. Also mouse moving can be perform with offset:

public void click(Point where)
public void click(int x, int y)

public void doubleClick(Point where)
public void doubleClick(int x, int y)

public void contextClick(Point where)
public void contextClick(int x, int y)

public void mouseDown(Point where)
public void mouseDown(int x, int y)

public void mouseUp(Point where)
public void mouseUp(int x, int y)

public void wheelUp(int wheelAmt)
public void wheelDown(int wheelAmt)

public void wheelClick(Point where)
public void wheelClick(int x, int y)
 
public void mouseMove(Point where)
public void mouseMove(int x, int y)
public void mouseMove(Point where, long xOffset, long yOffset)
public void mouseMove(int x, int y, long xOffset, long yOffset)

Bellow is an example of how to perform mouse click and moving with offset:

driver.getInputDevices().getMouse().click(10, 10);
driver.getInputDevices().getMouse().mouseMove(10, 10, 40, 40);

clipboard

This method returns an abstraction (Cliboard object) which allows you to get, set and clean clipboard text.

public Clipboard clipboard()

Clipboard object contains the following methods:

public String getText()
public void setText(String text)
public void clean()

The short example of how get value from clipboard:

String valueFromClipboard = driver.clipboard().getText();

Drivers and UI Elements