Add option to find element right now only instead of retrying all the time (#240)

* feat(element): add option to find element right now instead of always waiting for retry

* feat: add keyword 'Find One Element'

It runs immediately and never retries.
It is useful with 'Wait Until Keyword Succeeds`.

* Revert "feat(element): add option to find element right now instead of always waiting for retry"

This reverts commit b4a0822.

* docs: improve CHANGELOG how-to

* style: fix robocop trailing whitespace

* fix: remove library String to avoid name clash

Library String was added in the current PR.
Using keyword 'Evaluate' instead.

[ WARN ] Keyword 'Format String' found both
from a custom library 'StringFormat' and
a standard library 'String'

* style: run keen.bat tidy-fix

Author: alainsiroishw

CHANGELOG.md

@@ -7,6 +7,21 @@ This document follows the conventions laid out in [Keep a CHANGELOG][].
 
 ## [Unreleased][]
 
+## [Release][4.0.4] [4.0.4][4.0.3-4.0.4] - 2025-11-25
+
+### Added
+
+- New keyword
+  - Find One Element
+
+Keyword 'Find One Element' runs immediately and does not retry after the timeout.
+
+### Changed
+
+- Add a note that keyword 'Find All Elements' does not retry after the timeout
+- Add a section in README.md to run a single test in folder `atests`
+- Add a section in README.md when someone wants to release a new version
+
 ## [Release][4.0.3] [4.0.3][4.0.2-4.0.3] - 2025-11-17
 
 ### Added
@@ -749,6 +764,10 @@ General bugfixing from keywords and improvements from artifact building and test
 
 [unreleased]: https://github.com/GDATASoftwareAG/robotframework-flaui/compare/4.0.2...main
 
+[4.0.4]: https://github.com/GDATASoftwareAG/robotframework-flaui/releases/tag/4.0.4
+
+[4.0.3-4.0.4]: https://github.com/GDATASoftwareAG/robotframework-flaui/compare/4.0.3...4.0.4
+
 [4.0.3]: https://github.com/GDATASoftwareAG/robotframework-flaui/releases/tag/4.0.3
 
 [4.0.2-4.0.3]: https://github.com/GDATASoftwareAG/robotframework-flaui/compare/4.0.2...4.0.3

README.md

@@ -142,6 +142,16 @@ Two test projects were used for the UI automation:
 * FlaUI WPF Test App 'Standard application that contains all common UI elements'
 * Notifier Test App 'Application which closes automatically after a time'
 
+### Testing locally TLDR
+
+```powershell
+python -m venv .venv
+.venv/Scripts/pip install -r requirements-dev.txt
+
+cd ./atests
+../.venv/Scripts/robot -v UIA:UIA3 -d ../result -P ../src -t "Element Should Be Offscreen" Element.robot
+```
+
 ### Building and testing locally
 
 Use the provided 'Commander Keen' file:
@@ -169,6 +179,17 @@ Following arguments are supported:
   * pylint - Static code analysis for python code
   * robocop - Static code analysis for robotframework code
   * tidy - Formatter for robotframework code
+  
+### Releasing a new version - Frequent tasks
+
+- add or update keywords in folders
+  - `src/FlaUILibrary/flaui/module`
+  - `src/FlaUILibrary/keywords`
+- add or update tests in folder `atests`
+- update version in `src/FlaUILibrary/version.py`
+- update `CHANGELOG.md`
+  - add a release near the top
+  - add the links at the bottom in section `### Added`
 
 ## Acknowledgements
 

atests/Element.robot

@@ -176,6 +176,38 @@ Find All Elements If Xpath Is Wrong
     ${elements}    Find All Elements    /NOT_A_XPATH
     Length Should Be    ${elements}    0
 
+Find One Element
+    ${element}    Find One Element    ${XPATH_ENABLE_ELEMENT}
+
+    ${window_xpath}    Evaluate    '${element.Xpath}'.split("/Tab")[0]
+
+    Should Be Equal    ${element.AutomationId}    ${window_xpath}/Tab/TabItem[1]/Button[@AutomationId="EnableButton"]
+    Should Be Equal    ${element.ClassName}    ${window_xpath}/Tab/TabItem[1]/Button[@ClassName="Button"]
+    Should Be Equal    ${element.Name}    ${window_xpath}/Tab/TabItem[1]/Button[@Name="Enable Button"]
+    Should Be Equal    ${element.Xpath}    ${window_xpath}/Tab/TabItem[1]/Button[6]
+
+Find One Element Not Supported Exception Should Return Empty String
+    ${element}    Find One Element    ${XPATH_ELEMENT}
+
+    ${window_xpath}    Evaluate    '${element.Xpath}'.split("/Tab")[0]
+
+    Should Be Empty    ${element.AutomationId}
+    Should Be Equal    ${element.ClassName}    ${window_xpath}/Tab/TabItem[1]/Text[@ClassName="Text"]
+    Should Be Equal    ${element.Name}    ${window_xpath}/Tab/TabItem[1]/Text[@Name="Test Label"]
+    Should Be Equal    ${element.Xpath}    ${window_xpath}/Tab/TabItem[1]/Text[2]
+
+Find One Element Xpath Usage Can Be Used To Any Keyword
+    ${element}    Find One Element    ${XPATH_ENABLE_ELEMENT}
+    Element Should Exist    ${element}
+
+Find One Element If Xpath Is Wrong
+    TRY
+        Find One Element    /NOT_A_XPATH
+        Fail    'Find One Element' was supposed to fail because the xpath does NOT exist
+    EXCEPT    FlaUiError: Element from XPath '/NOT_A_XPATH' could not be found
+        Log    'Find One Element' failed as expected
+    END
+
 Is Element Offscreen
     ${IS_OFFSCREEN}    Is Element Offscreen    ${XPATH_ELEMENT}
     Should Be Equal    ${IS_OFFSCREEN}    ${False}

src/FlaUILibrary/flaui/module/element.py

@@ -37,6 +37,7 @@ class Action(Enum):
         GET_ELEMENT_BY_XPATH = "GET_ELEMENT_BY_XPATH"
         GET_ELEMENT_RECTANGLE_BOUNDING = "GET_ELEMENT_RECTANGLE_BOUNDING"
         FOCUS_ELEMENT = "FOCUS_ELEMENT"
+        FIND_ONE_ELEMENT = "FIND_ONE_ELEMENT"
         FIND_ALL_ELEMENTS = "FIND_ALL_ELEMENTS"
         IS_ELEMENT_ENABLED = "IS_ELEMENT_ENABLED"
         IS_ELEMENT_OFFSCREEN = "IS_ELEMENT_OFFSCREEN"
@@ -126,6 +127,8 @@ def execute_action(self, action: Action, values: Container):
                 lambda: self._wait_until_element_is_offscreen(values["xpath"], values["retries"]),
             self.Action.WAIT_UNTIL_ELEMENT_IS_ENABLED:
                 lambda: self._wait_until_element_is_enabled(values["xpath"], values["retries"]),
+            self.Action.FIND_ONE_ELEMENT:
+                lambda: self._find_one_element(values["xpath"]),
             self.Action.FIND_ALL_ELEMENTS:
                 lambda: self._find_all_elements(values["xpath"]),
             self.Action.WAIT_UNTIL_ELEMENT_EXIST:
@@ -228,6 +231,28 @@ def _get_element_by_xpath(self, xpath: str):
         except CSharpException:
             return None
 
+    def _find_one_element(self, xpath: str):
+        """
+        Try to find one element from xpath by desktop.
+
+        Args:
+            xpath (string): XPath identifier from element.
+
+        Raises:
+            FlaUiError: If node could not be found by xpath.
+        """
+        element = self._get_element_by_xpath(xpath)
+
+        if element:
+            return AutomationElement(
+                self._try_get_automation_id_property(element),
+                self._try_get_name_property(element),
+                self._try_get_classname_property(element),
+                FlaUIDebug.GetXPathToElement(element)
+            )
+
+        raise FlaUiError(FlaUiError.XPathNotFound.format(xpath))
+
     def _find_all_elements(self, xpath: str):
         """
         Try to find all elements from xpath by desktop.

src/FlaUILibrary/keywords/element.py

@@ -455,10 +455,46 @@ def wait_until_element_is_enabled(self, identifier, retries=10, msg=None):
                       Element.create_value_container(xpath=identifier, retries=retries),
                       msg)
 
+    @keyword
+    def find_one_element(self, identifier, msg=None):
+        """
+        Find one element from given xpath.
+        Runs immediately and without retrying later.
+        Returns an AutomationElement which contains properties to Xpath.
+        If AutomationId, ClassName or Name is set. Xpath can be used by these values and will be returned.
+
+        | Example usage AutomationElement                                        |
+        | Xpath        --> /Window[1]/Tab/TabItem[1]                             |
+        | AutomationId --> /Window[1]/Tab/TabItem[@AutomationId="SimpleControl"] |
+        | Name         --> /Window[1]/Tab/TabItem[@Name="Simple Controls"]       |
+        | ClassName    --> /Window[1]/Tab/TabItem[@ClassName="TabItem"]          |
+
+        If any property is not set empty string value will be returned.
+
+        XPath syntax is explained in `XPath locator`.
+
+        Arguments:
+        | Argument   | Type   | Description                                                           |
+        | identifier | string | XPath identifier from element                                         |
+        | msg        | string | Custom error message                                                  |
+
+        Example:
+        | ${element}    Find One Element    <XPATH> |
+        | Click    ${element} |
+        | Wait Until Keyword Succeeds    10s    1ms    Find One Element    /xpath/text/update/successful |
+        | Click    /xpath/button/continue |
+        """
+        module = self._container.create_or_get_module()
+        return module.action(Element.Action.FIND_ONE_ELEMENT,
+                             Element.create_value_container(xpath=identifier),
+                             msg)
+
     @keyword
     def find_all_elements(self, identifier, msg=None):
         """
-        Find all elements from given xpath, Returns an AutomationElement list which contains properties to Xpath.
+        Find all elements from given xpath.
+        Runs immediately and without retrying later.
+        Returns an AutomationElement list which contains properties to Xpath.
         If AutomationId, ClassName or Name is set. Xpath can be used by these values and will be returned.
 
         | Example usage AutomationElement                                        |

src/FlaUILibrary/version.py

@@ -1 +1 @@
-VERSION = "4.0.3"
+VERSION = "4.0.4"