Package com.workfusion.rpa.helpers

Class UiElementCollection

java.lang.Object

java.util.AbstractCollection<UiElement>

java.util.AbstractList<UiElement>

com.workfusion.rpa.helpers.UiElementCollection

All Implemented Interfaces:

Iterable<UiElement>, Collection<UiElement>, List<UiElement>, SequencedCollection<UiElement>

public class UiElementCollection
extends AbstractList<UiElement>

This class wraps a list of UiElement and provides a new functionality.

A UiElementCollection is an immutable, List-compatible view over the elements matched by a selector (created via RPA.$$(...)). On top of the standard list operations it adds:

• positional access — first(), last(), get(int);
• assertions over the whole collection — shouldHave(UiCollectionCondition...), shouldBe(UiCollectionCondition...), shouldHaveSize(int);
• fluent waiting — waitUntil(UiCollectionCondition) / waitWhile(UiCollectionCondition);
• filtering — filter(UiCondition), exclude(UiCondition), find(UiCondition);
• bulk text extraction — getTexts().

When constructed from a By selector, the matching elements are resolved lazily so that waitUntil/waitWhile can re-query the page on each polling iteration.

Samples

$$(".errorMessage").first()shouldBe(visible, enabled);

$$("td").shouldHaveSize(5);

$$(".edit").getTexts();

See Also:

• List

Method Summary

Modifier and Type	Method	Description
static String	elementsToString(List<? extends com.workfusion.rpa.internal.api.element.WebElement> elements)	Builds a human-readable, multi-line string representation of an element collection.
UiElementCollection	exclude(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)	Returns a new collection with the elements that match the given condition removed (the inverse of filter(UiCondition)).
UiElementCollection	excludeWith(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)	Synonym for exclude(UiCondition); reads more naturally in some chains.
UiElementCollection	filter(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)	Returns a new collection containing only the elements that match the given condition.
UiElementCollection	filterBy(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)	Synonym for filter(UiCondition); reads more naturally in some chains.
UiElement	find(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)	Returns the first element that matches the given condition.
UiElement	findBy(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)	Synonym for find(UiCondition); reads more naturally in some chains.
UiElement	first()
UiElement	get(int index)	Returns the element at the given position in the collection.
String[]	getTexts()	Returns the visible text of every element in the collection, in order.
static String[]	getTexts(Collection<? extends com.workfusion.rpa.internal.api.element.WebElement> elements)	Fail-safe method for retrieving texts of given elements.
Iterator<UiElement>	iterator()
UiElement	last()
ListIterator<UiElement>	listIterator()
ListIterator<UiElement>	listIterator(int index)	Returns a list iterator over the elements of this collection, starting at the given position.
UiElementCollection	shouldBe(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition... conditions)	Asserts that the collection meets all the given conditions immediately (no waiting).
UiElementCollection	shouldHave(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition... conditions)	Asserts that the collection meets all the given conditions immediately (no waiting).
UiElementCollection	shouldHaveSize(int expectedSize)	Asserts that the collection currently contains exactly the given number of elements.
int	size()
String	toString()	Returns a human-readable, multi-line representation of the collection, intended for logging and debugging.
UiElementCollection	waitUntil(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition)	Wait until given collection meets given conditions.
UiElementCollection	waitUntil(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition, long timeoutMilliseconds)	Wait until given collection meets given conditions.
UiElementCollection	waitUntil(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition, long timeoutMilliseconds, long pollingIntervalMilliseconds)	Wait until given collection meets given conditions.
UiElementCollection	waitWhile(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition)	Wait while given collection meets given conditions.
UiElementCollection	waitWhile(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition, long timeoutMilliseconds)	Wait while given collection meets given conditions.
UiElementCollection	waitWhile(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition, long timeoutMilliseconds, long pollingIntervalMilliseconds)	Wait while given collection meets given conditions.

Methods inherited from class java.util.AbstractList

add, add, addAll, clear, equals, hashCode, indexOf, lastIndexOf, remove, set, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.List

addAll, addFirst, addLast, contains, containsAll, getFirst, getLast, isEmpty, remove, removeAll, removeFirst, removeLast, replaceAll, retainAll, reversed, sort, spliterator, toArray, toArray

Method Details

get

public UiElement get(int index)

Returns the element at the given position in the collection.

Specified by:

get in interface List<UiElement>

Specified by:

get in class AbstractList<UiElement>

Parameters:

index - zero-based position (0 is the first element)

Returns:

the element at that position

Throws:

IndexOutOfBoundsException - if the index is out of range

first

public UiElement first()

Returns:

the first element of the collection, or null if the collection is empty

last

public UiElement last()

Returns:

the last element of the collection, or null if the collection is empty

size

public int size()

Specified by:

size in interface Collection<UiElement>

Specified by:

size in interface List<UiElement>

Specified by:

size in class AbstractCollection<UiElement>

Returns:

the number of elements in the collection

shouldHaveSize

public UiElementCollection shouldHaveSize(int expectedSize)

Asserts that the collection currently contains exactly the given number of elements. Shorthand for shouldHave(size(expectedSize)). Checked immediately (no waiting).

Parameters:

expectedSize - expected number of elements in the collection

Returns:

this collection, for chaining

Throws:

IllegalStateException - if the actual size differs from expectedSize

shouldBe

public UiElementCollection shouldBe(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition... conditions)

Asserts that the collection meets all the given conditions immediately (no waiting). Reads naturally with "be"-style conditions, e.g. $$(".error").shouldBe(empty).

Parameters:

conditions - collection conditions that must all hold

Returns:

this collection, for chaining

Throws:

IllegalStateException - if any condition is not met

shouldHave

public UiElementCollection shouldHave(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition... conditions)

Asserts that the collection meets all the given conditions immediately (no waiting). Reads naturally with "have"-style conditions, e.g. $$(".error").shouldHave(size(3)).

Parameters:

conditions - collection conditions that must all hold

Returns:

this collection, for chaining

Throws:

IllegalStateException - if any condition is not met

waitUntil

public UiElementCollection waitUntil(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition)

Wait until given collection meets given conditions.

Throws:

IllegalStateException - if collection still is not matched to condition after the timeout

waitUntil

public UiElementCollection waitUntil(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition,
 long timeoutMilliseconds)

Wait until given collection meets given conditions.

Parameters:

timeoutMilliseconds - timeout in milliseconds.

Throws:

IllegalStateException - if collection still is not matched to condition after the timeout

waitUntil

public UiElementCollection waitUntil(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition,
 long timeoutMilliseconds,
 long pollingIntervalMilliseconds)

Wait until given collection meets given conditions.

Parameters:

timeoutMilliseconds - timeout in milliseconds.

pollingIntervalMilliseconds - interval in milliseconds, when checking condition

Throws:

IllegalStateException - if collection still is not matched to condition after the timeout

waitWhile

public UiElementCollection waitWhile(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition)

Wait while given collection meets given conditions.

Throws:

IllegalStateException - if collection still is not matched to condition after the timeout

waitWhile

public UiElementCollection waitWhile(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition,
 long timeoutMilliseconds)

Wait while given collection meets given conditions.

Parameters:

timeoutMilliseconds - timeout in milliseconds.

Throws:

IllegalStateException - if collection still is not matched to condition after the timeout

waitWhile

public UiElementCollection waitWhile(com.workfusion.rpa.helpers.conditionsnative.collection.UiCollectionCondition condition,
 long timeoutMilliseconds,
 long pollingIntervalMilliseconds)

Wait while given collection meets given conditions.

Parameters:

timeoutMilliseconds - timeout in milliseconds.

pollingIntervalMilliseconds - interval in milliseconds, when checking condition

Throws:

IllegalStateException - if collection still is not matched to condition after the timeout

filter

public UiElementCollection filter(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)

Returns a new collection containing only the elements that match the given condition. The original collection is left unchanged.

Parameters:

condition - the condition each retained element must satisfy

Returns:

a new collection with the matching elements (possibly empty)

filterBy

public UiElementCollection filterBy(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)

Synonym for filter(UiCondition); reads more naturally in some chains.

Parameters:

condition - the condition each retained element must satisfy

Returns:

a new collection with the matching elements (possibly empty)

See Also:

• filter(UiCondition)

exclude

public UiElementCollection exclude(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)

Returns a new collection with the elements that match the given condition removed (the inverse of filter(UiCondition)). The original collection is left unchanged.

Parameters:

condition - the condition identifying elements to exclude

Returns:

a new collection without the matching elements (possibly empty)

excludeWith

public UiElementCollection excludeWith(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)

Synonym for exclude(UiCondition); reads more naturally in some chains.

Parameters:

condition - the condition identifying elements to exclude

Returns:

a new collection without the matching elements (possibly empty)

See Also:

• exclude(UiCondition)

find

public UiElement find(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)

Returns the first element that matches the given condition.

Parameters:

condition - the condition the returned element must satisfy

Returns:

the first matching element, or null if none matches

findBy

public UiElement findBy(com.workfusion.rpa.helpers.conditionsnative.UiCondition condition)

Synonym for find(UiCondition); reads more naturally in some chains.

Parameters:

condition - the condition the returned element must satisfy

Returns:

the first matching element, or null if none matches

See Also:

• find(UiCondition)

getTexts

public String[] getTexts()

Returns the visible text of every element in the collection, in order. Fail-safe: if reading an element throws a WebDriverException (e.g. it went stale), the exception's string representation is stored in that slot instead of failing the call.

Returns:

an array of element texts, one per element (same order as the collection)

getTexts

public static String[] getTexts(Collection<? extends com.workfusion.rpa.internal.api.element.WebElement> elements)

Fail-safe method for retrieving texts of given elements.

Parameters:

elements - Any collection of WebElements

Returns:

Array of texts (or exceptions in case of any WebDriverExceptions)

elementsToString

public static String elementsToString(List<? extends com.workfusion.rpa.internal.api.element.WebElement> elements)

Builds a human-readable, multi-line string representation of an element collection. Intended for logging and debugging, not for test verifications.

Parameters:

elements - the elements to render; null yields "[not loaded yet...]" and an empty list yields "[]"

Returns:

a formatted string listing the elements

iterator

public Iterator<UiElement> iterator()

Specified by:

iterator in interface Collection<UiElement>

Specified by:

iterator in interface Iterable<UiElement>

Specified by:

iterator in interface List<UiElement>

Overrides:

iterator in class AbstractList<UiElement>

Returns:

an iterator over the elements of this collection, in order

listIterator

public ListIterator<UiElement> listIterator()

Specified by:

listIterator in interface List<UiElement>

Overrides:

listIterator in class AbstractList<UiElement>

Returns:

a list iterator over the elements of this collection, starting at the first element

listIterator

public ListIterator<UiElement> listIterator(int index)

Returns a list iterator over the elements of this collection, starting at the given position.

Specified by:

listIterator in interface List<UiElement>

Overrides:

listIterator in class AbstractList<UiElement>

Parameters:

index - position of the first element to be returned by the iterator

Returns:

a list iterator starting at the given position

Throws:

IndexOutOfBoundsException - if the index is out of range

toString

public String toString()

Returns a human-readable, multi-line representation of the collection, intended for logging and debugging. Fail-safe: any error while rendering is captured and returned as the string instead of being thrown.

Overrides:

toString in class AbstractCollection<UiElement>

Returns:

a formatted string listing the elements