Package allurium.lists

Class ListWC<T extends ListComponent>

java.lang.Object
allurium.lists.ListWC<T>
Type Parameters:
T - the type of the list components, which must implement ListComponent.

Features:

  • Supports dynamic type-based component initialization.
  • Provides robust mechanisms for interacting with and validating list content.
  • Integrates with Allure for enhanced test reporting.
  • Supports advanced filtering and assertions using Selenide's Condition and CollectionCondition.
  • Refreshes and rebuilds components dynamically.

Purpose:

  • Standardizes interaction with web component lists in tests.
  • Simplifies complex list operations and error handling.

Constructors:

Usage Example:


 // Define a custom list component
 public class TableRow implements ListComponent {

     public TableRow(SelenideLocator sl) {
         super(sl);
     }

     public String getId() {
         return getRoot().$x("//td[1]").text();
     }
 }

 // Initialize and use the ListWC
 ListWC<TableRow> tableRows = new ListWC<>(".table-row");
 TableRow row = tableRows.get("Row 1");
 row.assertVisible();

Thread-Safety:

The class is not thread-safe. Each thread should create its own instance if needed.
All Implemented Interfaces:
WebElementMeta
public class ListWC<T extends ListComponent> extends Object implements WebElementMeta
A universal utility for working with lists of web components such as table rows, cards, or complex widgets.

The `ListWC` class wraps `ElementCollection` and enhances it by providing strong typing for the contained elements. It supports common list operations such as filtering, element retrieval, assertions, and size checks. This class is highly configurable and integrates seamlessly with Allure for step reporting.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Optional<AbstractWidget>
    parent
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    ListWC(com.codeborne.selenide.ElementsCollection sourceElements, Class<T> componentsClass)
    Constructs a `ListWC` with the provided source elements and component class type.
    ListWC(String selenideSelector, Class<T> componentsClass)
    Constructs a `ListWC` using a Selenide selector string to identify list items and the component class type.
    ListWC(org.openqa.selenium.By listItemLocator)
    Constructs a `ListWC` using a Selenium By locator without specifying the component class type.
    ListWC(org.openqa.selenium.By listItemLocator, Class<T> componentsClass)
    Constructs a `ListWC` using a Selenium By locator to identify list items and the component class type.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    assertEmpty()
    Asserts that the list is empty (i.e., contains no components).
    void
    assertHasItem(String id)
    Asserts that the list contains an element with the specified ID.
    void
    assertHasItemsWithText(String text)
    Asserts that the list contains at least one element with the specified text.
    void
    assertHasNoItemsWithText(String text)
    Asserts that the list does not contain any element with the specified text.
    void
    assertHasNotItem(String id)
    Asserts that the list does not contain an element with the specified ID.
    void
    assertNotVisible()
    Asserts that no items in the list are visible.
    void
    assertSize(Integer size)
    Assertion: Verifies that the list size matches the provided expected value.
    void
    assertSizeGreaterThan(int size)
    Assertion: Verifies that the list size is greater than the specified value.
    void
    assertSizeLessThan(int size)
    Assertion: Verifies that the list size is less than the specified value.
    void
    assertVisible()
    Asserts that all items in the list are visible.
    void
    assertVisibleSize(int expectedSize)
    Assertion: Verifies that there is a specific number of visible components in the list.
    boolean
    equals(Object o)
     
    ListWC<T>
    filter(com.codeborne.selenide.WebElementCondition condition)
    Filters the current ListWC instance and returns a new instance containing only the elements that satisfy the specified condition.
    ListWC<T>
    filter(com.codeborne.selenide.WebElementCondition... conditions)
    Filters the current ListWC instance and returns a new instance containing only the elements that satisfy all of the specified conditions.
    T
    first()
    Retrieves the first element in the list.
    T
    get(Integer index)
    Retrieves the element at the specified index in the list.
    T
    get(String id)
    Retrieves an element from the list by a partial match of its ID, retrying if not immediately found.
    List<T>
    getAll()
     
    List<T>
    getComponents()
    Retrieves the list of components after refreshing the source elements.
    T
    getExact(String id)
     
    StringBuffer
    getMetaKeys()
    Gets the metadata keys associated with the UI element.
    List<T>
    getMultiple(String id)
    Retrieves all elements from the list whose id contains the specified value.
    Optional<T>
    getNullable(String id)
    Attempts to retrieve an element from the list that matches the given ID, returning an Optional.
    T
    getPrecise(String id)
    Retrieves an element from the list by its exact ID, retrying if not immediately found.
    List<T>
    getPreciseMultiple(String id)
    Retrieves all elements from the list whose id exactly matches the specified value.
    T
    getPreciseVisible(String id)
    Retrieves a visible element from the list by its exact ID, retrying if not immediately found.
    T
    getStrictly(String id)
    Deprecated.
    T
    getVisible(String id)
    Retrieves a visible element from the list by a partial match of its ID, retrying if not immediately found.
    int
    hashCode()
     
    boolean
    hasItem(String id)
    Checks whether the list contains an element with the exact specified ID.
    boolean
    hasItemWithText(String text)
    Checks whether the list contains an element with the specified text.
    boolean
    isDisplayed()
    Checks if any element in the list is currently visible on the page.
    T
    last()
    Retrieves the last element in the list.
    void
    logDump()
     
    ListWC<T>
    refresh()
    Refreshes the list by clearing the existing components and rebuilding them based on the current state of the source elements.
    void
    should(com.codeborne.selenide.WebElementsCondition... conditions)
    Asserts that the list satisfies the specified collection conditions.
    int
    size()
    Returns the total number of components in the list.
    String
    wrappedName()
    Wraps the list's name with the highlighter prefixes and suffixes.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface allurium.interfaces.WebElementMeta

    getDescription, getParent, getUiElementName, setAssignNameMethod, setDescription, setParent, setUiElementName

  • Field Details

  • Constructor Details

    • ListWC

      public ListWC(com.codeborne.selenide.ElementsCollection sourceElements, Class<T> componentsClass)
      Constructs a `ListWC` with the provided source elements and component class type.
      Parameters:
      sourceElements - the ElementsCollection representing the source elements in the list
      componentsClass - the class type of the list components

    • ListWC

      public ListWC(org.openqa.selenium.By listItemLocator, Class<T> componentsClass)
      Constructs a `ListWC` using a Selenium By locator to identify list items and the component class type.
      Parameters:
      listItemLocator - the By locator for the list items
      componentsClass - the class type of the list components

    • ListWC

      public ListWC(String selenideSelector, Class<T> componentsClass)
      Constructs a `ListWC` using a Selenide selector string to identify list items and the component class type.
      Parameters:
      selenideSelector - the Selenide selector string for the list items
      componentsClass - the class type of the list components

    • ListWC

      public ListWC(org.openqa.selenium.By listItemLocator)
      Constructs a `ListWC` using a Selenium By locator without specifying the component class type.
      Parameters:
      listItemLocator - the By locator for the list items

  • Method Details

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getMetaKeys

      public StringBuffer getMetaKeys()
      Description copied from interface: WebElementMeta
      Gets the metadata keys associated with the UI element.
      Specified by:
      getMetaKeys in interface WebElementMeta
      Returns:
      a StringBuffer containing the metadata keys

    • logDump

      public void logDump()

    • wrappedName

      public String wrappedName()
      Wraps the list's name with the highlighter prefixes and suffixes.
      Returns:
      the wrapped name of the list

    • getComponents

      public List<T> getComponents()
      Retrieves the list of components after refreshing the source elements.
      Returns:
      the list of components of type T

    • refresh

      public ListWC<T> refresh()
      Refreshes the list by clearing the existing components and rebuilding them based on the current state of the source elements.

      If the generic type name is not properly set, throws a ListComponentTypeException. Also invokes utility methods to enrich the components with metadata.

      Returns:
      the current instance of ListWC for method chaining

    • getStrictly

      @Deprecated public T getStrictly(String id)
      Deprecated.

    • getExact

      public T getExact(String id)

    • getPrecise

      public T getPrecise(String id)
      Retrieves an element from the list by its exact ID, retrying if not immediately found.

      The method uses a strict comparison to locate an element with a matching id. It refreshes the list and retries for a configurable number of attempts. If the element is still not found, it logs a failed step in Allure and throws an assertion error.

      'getPrecise(String id)' is recommended to use when 'get(String id)' can't fulfill specific requirements

      Key Features:

      • Performs strict comparison using equals to find the element.
      • Retries a configurable number of times before failing.
      • Logs detailed information about the failure in Allure for debugging.
      Parameters:
      id - the exact ID of the element to retrieve
      Returns:
      the matching element of type T if found
      Throws:
      AssertionError - if the element is not found after all retry attempts

    • get

      public T get(String id)
      Retrieves an element from the list by a partial match of its ID, retrying if not immediately found.

      The method performs a non-strict comparison, looking for an element whose id contains the specified substring. It refreshes the list and retries for a configurable number of attempts. If the element is still not found, it logs a failed step in Allure and throws an assertion error.

      'get(String id)' is recommended to use in most cases.

      Key Features:

      • Performs a partial comparison using contains to find the element.
      • Retries a configurable number of times before failing.
      • Logs detailed information about the failure in Allure for debugging.
      Parameters:
      id - the partial ID of the element to retrieve
      Returns:
      the matching element of type T if found
      Throws:
      AssertionError - if the element is not found after all retry attempts

    • getVisible

      public T getVisible(String id)
      Retrieves a visible element from the list by a partial match of its ID, retrying if not immediately found.

      The method filters for visible elements whose id contains the specified substring. It refreshes the list and retries for a configurable number of attempts. If the element is still not found, it logs a failed step in Allure and throws an assertion error.

      Key Features:

      • Filters elements to find those that are both visible and match the given partial id.
      • Retries fetching the element a configurable number of times.
      • Logs detailed information about the failure in Allure for debugging.
      Parameters:
      id - the partial ID of the visible element to retrieve
      Returns:
      the matching visible element of type T if found
      Throws:
      AssertionError - if the element is not found after all retry attempts

    • getPreciseVisible

      public T getPreciseVisible(String id)
      Retrieves a visible element from the list by its exact ID, retrying if not immediately found.

      The method ensures the element is visible and matches the exact id provided. It refreshes the list and retries for a configurable number of attempts. If the element is still not found, it logs a failed step in Allure and throws an assertion error.

      Key Features:

      • Filters elements by exact match of their id.
      • Ensures that the element is visible (`isDisplayed()`).
      • Retries fetching the element a configurable number of times.
      • Logs failure details in Allure and throws an error for debugging purposes.
      Parameters:
      id - the exact ID of the visible element to retrieve
      Returns:
      the matching visible element of type T if found
      Throws:
      AssertionError - if the element is not found after all retry attempts

    • getNullable

      public Optional<T> getNullable(String id)
      Attempts to retrieve an element from the list that matches the given ID, returning an Optional.

      The method searches for the first element whose id contains the specified value. If no such element is found, it retries for a configurable number of attempts before returning an empty Optional.

      Key Features:

      • Searches for a partial match of the id.
      • Returns an Optional to handle cases where no element is found.
      • Retries the search a configurable number of times.
      Parameters:
      id - the partial ID to search for
      Returns:
      an Optional containing the first matching element, or an empty Optional if not found

    • getMultiple

      public List<T> getMultiple(String id)
      Retrieves all elements from the list whose id contains the specified value.

      The method searches for all matching elements in the list and retries if no matches are initially found. It continues refreshing and searching until the configured retry limit is reached.

      Key Features:

      • Searches for a partial match of the id.
      • Returns a list of matching elements.
      • Retries the search a configurable number of times if no matches are found initially.
      Parameters:
      id - the partial ID to search for
      Returns:
      a List of matching elements, or an empty list if no matches are found

    • getPreciseMultiple

      public List<T> getPreciseMultiple(String id)
      Retrieves all elements from the list whose id exactly matches the specified value.

      The method searches for all elements that have an exact match for the provided id. If no matches are found initially, it retries the search until the retry limit is reached.

      Key Features:

      • Searches for an exact match of the id.
      • Returns a list of matching elements.
      • Retries the search a configurable number of times if no matches are found initially.
      Parameters:
      id - the exact ID to search for
      Returns:
      a List of elements with the exact matching ID, or an empty list if no matches are found

    • get

      public T get(Integer index)
      Retrieves the element at the specified index in the list.

      The method ensures that the list has enough elements before attempting to access the specified index. It refreshes the list and retrieves the element at the given index.

      Key Features:

      • Ensures that the list contains at least the number of elements specified by the index.
      • Refreshes the list to ensure the latest state before retrieving the element.
      Parameters:
      index - the zero-based index of the element to retrieve
      Returns:
      the element at the specified index
      Throws:
      IndexOutOfBoundsException - if the index is greater than or equal to the list size

    • first

      public T first()
      Retrieves the first element in the list.

      The method ensures that the list contains at least one element before attempting to access the first element. It refreshes the list to ensure the latest state and then retrieves the first element.

      Key Features:

      • Ensures that the list contains at least one element.
      • Refreshes the list to ensure the latest state before retrieving the element.
      Returns:
      the first element in the list
      Throws:
      IndexOutOfBoundsException - if the list is empty

    • last

      public T last()
      Retrieves the last element in the list.

      The method ensures that the list contains at least one element before attempting to access the last element. It refreshes the list to ensure the latest state and then retrieves the last element.

      Key Features:

      • Ensures that the list contains at least one element.
      • Refreshes the list to ensure the latest state before retrieving the element.
      Returns:
      the last element in the list
      Throws:
      IndexOutOfBoundsException - if the list is empty

    • getAll

      public List<T> getAll()

    • should

      public void should(com.codeborne.selenide.WebElementsCondition... conditions)
      Asserts that the list satisfies the specified collection conditions.

      The method allows for applying one or more conditions from Selenide's CollectionCondition class to the underlying elements in the list. If the conditions are not met, an assertion failure is thrown, and the result is logged to Allure with the status of the operation.

      Key Features:

      • Supports multiple CollectionCondition checks in a single invocation.
      • Automatically refreshes the list to ensure it reflects the current state of the elements.
      • Integrates with Allure for detailed reporting, showing the status of the operation in the test report.

      Behavior:

      • Clears the current list of components.
      • Applies each condition to the list's source elements.
      • Rebuilds the list components after the conditions are applied.
      • Logs the operation status (PASSED or FAILED) to Allure.

      Usage Example:

      
 // Example: Assert that the list contains exactly 5 visible elements.
 myList.should(CollectionCondition.size(5));

 // Example: Assert that the list is not empty and all elements are visible.
 myList.should(CollectionCondition.sizeGreaterThan(0), CollectionCondition.allMatch("visible", SelenideElement::isDisplayed));
      Parameters:
      conditions - one or more CollectionCondition to apply to the list
      Throws:
      AssertionError - if any of the conditions are not met

    • filter

      public ListWC<T> filter(com.codeborne.selenide.WebElementCondition condition)
      Filters the current ListWC instance and returns a new instance containing only the elements that satisfy the specified condition.

      Behavior:

      • Refreshes this list to ensure the underlying elements are up-to-date.
      • Applies the given Condition to the sourceElements.
      • Creates a new ListWC instance with the same genericTypeName, parent, and description as this instance.
      • Sets the new list's uiElementName to include the original name plus the condition's textual representation.
      • Invokes refresh() on the new list to build its components.
      Parameters:
      condition - the Condition to apply
      Returns:
      a new ListWC instance containing only the elements that match the specified condition

    • filter

      public ListWC<T> filter(com.codeborne.selenide.WebElementCondition... conditions)
      Filters the current ListWC instance and returns a new instance containing only the elements that satisfy all of the specified conditions.

      Behavior:

      • Refreshes this list to ensure the underlying elements are up-to-date.
      • Sequentially applies each provided Condition to the sourceElements.
      • Creates a new ListWC instance with the same genericTypeName, parent, and description as this instance.
      • Sets the new list's uiElementName to include the original name plus the textual representations of all conditions.
      • Invokes refresh() on the new list to build its components.
      Parameters:
      conditions - one or more Condition objects to apply; elements must pass all of them to remain in the filtered list
      Returns:
      a new ListWC instance containing only the elements that match all specified conditions

    • isDisplayed

      public boolean isDisplayed()
      Checks if any element in the list is currently visible on the page.

      This method iterates through the source elements to determine if any are displayed. If at least one element is visible, the method returns true; otherwise, false.

      Behavior:

      • Uses SelenideElement.isDisplayed() to check visibility.
      • Returns true if at least one element is visible.
      • Returns false if no elements are visible or if the list is empty.

      Usage Example:

      
 // Check if any elements in the list are visible
 boolean isVisible = myList.isDisplayed();
      Returns:
      true if at least one element is visible; false otherwise

    • size

      public int size()
      Returns the total number of components in the list.

      This method refreshes the list to ensure the count is accurate and up-to-date.

      Behavior:

      • Calls refresh() to ensure the list components reflect the latest state.
      • Returns the size of the components list.
      Returns:
      the number of components in the list

    • hasItem

      public boolean hasItem(String id)
      Checks whether the list contains an element with the exact specified ID.

      This method iterates through the components to find an element that:

      • Is currently visible on the page.
      • Has an ID that matches the specified id exactly.

      Behavior:

      • Calls refresh() to ensure the list is up-to-date.
      • Filters components based on visibility and exact ID match.
      • Returns true if such an element is found; otherwise, false.

      Exception Handling:

      • Catches ElementNotFound exceptions and logs the message.

      Usage Example:

      
 // Check if the list contains an element with a specific ID
 boolean hasElement = myList.hasItem("element-id-123");
      Parameters:
      id - the exact ID of the element/widget to search for
      Returns:
      true if the list contains an element with the exact ID; false otherwise

    • hasItemWithText

      public boolean hasItemWithText(String text)
      Checks whether the list contains an element with the specified text.

      This method iterates through the components to find an element that:

      • Is currently visible on the page.
      • Contains the specified text in its visible content.

      Behavior:

      • Calls refresh() to ensure the list is up-to-date.
      • Filters components based on visibility and text match.
      • Returns true if such an element is found; otherwise, false.

      Usage Example:

      
 // Check if the list contains an element with specific text
 boolean hasElementWithText = myList.hasItemWithText("Sample Text");
      Parameters:
      text - the text to search for in the list elements
      Returns:
      true if the list contains an element with the specified text; false otherwise

    • assertSize

      public void assertSize(Integer size)
      Assertion: Verifies that the list size matches the provided expected value. If the list size does not match, the method will retry until the configured retry attempts are exhausted. == Step: Processed by Aspect ==
      Parameters:
      size - the expected size of the list
      Throws:
      IllegalArgumentException - if the expected size is negative

    • assertVisibleSize

      public void assertVisibleSize(int expectedSize)
      Assertion: Verifies that there is a specific number of visible components in the list. Retries until the expected size is met or the retry limit is exhausted.
      Parameters:
      expectedSize - the expected number of visible components

    • assertSizeGreaterThan

      public void assertSizeGreaterThan(int size)
      Assertion: Verifies that the list size is greater than the specified value. Retries until the condition is met or the retry limit is exhausted.
      Parameters:
      size - the value that the list size should be greater than

    • assertSizeLessThan

      public void assertSizeLessThan(int size)
      Assertion: Verifies that the list size is less than the specified value. Retries until the condition is met or the retry limit is exhausted.
      Parameters:
      size - the maximum size the list should have

    • assertEmpty

      public void assertEmpty()
      Asserts that the list is empty (i.e., contains no components). Retries until the condition is met or the retry limit is exhausted.

    • assertVisible

      public void assertVisible()
      Asserts that all items in the list are visible.

      This method ensures that at least one element in the list is visible by checking each component's visibility. If no elements are visible, an assertion error is thrown.

    • assertNotVisible

      public void assertNotVisible()
      Asserts that no items in the list are visible.

      This method checks that none of the elements in the list are currently displayed on the page. If any element is found to be visible, an assertion error is thrown.

    • assertHasItemsWithText

      public void assertHasItemsWithText(String text)
      Asserts that the list contains at least one element with the specified text.
      Parameters:
      text - the text pattern to search for in the list elements

    • assertHasNoItemsWithText

      public void assertHasNoItemsWithText(String text)
      Asserts that the list does not contain any element with the specified text.
      Parameters:
      text - the text pattern to search for in the list elements

    • assertHasItem

      public void assertHasItem(String id)
      Asserts that the list contains an element with the specified ID.
      Parameters:
      id - the ID of the expected list item

    • assertHasNotItem

      public void assertHasNotItem(String id)
      Asserts that the list does not contain an element with the specified ID.
      Parameters:
      id - the ID of the list item to check for absence