askui 0.18.0 → 0.19.0

package/dist/cjs/execution/dsl.js

@@ -31,7 +31,11 @@ class FluentBase {
         if (this instanceof FluentCommand) {
             const fluentCommand = this;
             const customElements = newParamsList.has('customElement') ? newParamsList.get('customElement') : [];
-            return fluentCommand.fluentCommandExecutor(newCurrentInstruction.trim(), customElements);
+            const aiElementNames = newParamsList.has('aiElementName') ? newParamsList.get('aiElementName') : [];
+            return fluentCommand.fluentCommandExecutor(newCurrentInstruction.trim(), {
+                customElementsJson: customElements,
+                aiElementNames,
+            });
         }
         if (!this.prev) {
             throw new Error('Prev element not defined');
@@ -44,7 +48,11 @@ class FluentBase {
         if (this instanceof Getter) {
             const getter = this;
             const customElements = newParamsList.has('customElement') ? newParamsList.get('customElement') : [];
-            return getter.getterExecutor(newCurrentInstruction.trim(), customElements);
+            const aiElementNames = newParamsList.has('aiElementName') ? newParamsList.get('aiElementName') : [];
+            return getter.getterExecutor(newCurrentInstruction.trim(), {
+                customElementsJson: customElements,
+                aiElementNames,
+            });
         }
         if (!this.prev) {
             throw new Error('Prev element not defined');
@@ -147,9 +155,11 @@ class FluentFilters extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.moveMouseTo().button().exec()
+     * await aui.click().button().contains().text().withText('Google Search').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/button.gif)
+     *
      * @return {FluentFiltersOrRelations}
      */
     button() {
@@ -209,13 +219,20 @@ class FluentFilters extends FluentBase {
     /**
      * Filters for an UI element 'text'.
      *
-     * Often combined with the filter `withText()` as shown in the below examples.
+     * Takes an optional parameter to filter for a specific text.
+     * See the examples below.
+     *
      * See also the filters `withTextRegex()` and `withExactText()`
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().text().withText('Password').exec();
+     * await aui.click().text().exec();
+     * await aui.click().text('Username').exec();
+     *
+     * // Matching with an exact text
      * await aui.click().text().withExactText('Username').exec();
+     *
+     * // Matching with a regex
      * await aui.click().text().withTextRegex('\b[Ss]\w+').exec();
      * ```
      *
@@ -239,6 +256,8 @@ class FluentFilters extends FluentBase {
      * icon().withText('plus')
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/icon.gif)
+     *
      * **Note:** This is an alpha feature. The prediction of the icon name is sometimes unstable. Use custom elements as an alternative.
      *
      * @return {FluentFiltersOrRelations}
@@ -249,7 +268,9 @@ class FluentFilters extends FluentBase {
         return new FluentFiltersOrRelations(this);
     }
     /**
-     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element that is not recognized by our machine learning models by default. It can also be used for pixel assertions of elements using classical [template matching](https://en.wikipedia.org/wiki/Template_matching).
+     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element based on an image instead of using text or element descriptions like `button().withText('Submit')` in `await aui.click().button().withText('Submit').exec()`.
+     *
+     * See the tutorial - [Custom Element](https://docs.askui.com/docs/general/Tutorials/custom-element) for more detail.
      *
      * **Example**
      * ```typescript
@@ -259,6 +280,7 @@ class FluentFilters extends FluentBase {
      *         customImage: './logo.png', // required
      *         name: 'myLogo', // optional
      *         threshold: 0.9, // optional, defaults to 0.9
+     *         stopThreshold: 0.9, // optional, defaults to 0.9
      *         rotationDegreePerStep: 0, // optional, defaults to 0
      *         imageCompareFormat: 'grayscale', // optional, defaults to 'grayscale'
      *         // mask:{x:0, y:0}[] // optional, a polygon to match only a certain area of the custom element
@@ -273,12 +295,13 @@ class FluentFilters extends FluentBase {
      * - **name** (*`string`, optional*):
      *     - A unique name that can be used for filtering for the custom element. If not given, any text inside the custom image will be detected via OCR.
      * - **threshold** (*`number`, optional*):
-     *     - A threshold for how much a UI element needs to be similar to the custom element as defined. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     *     - A threshold for how much a UI element needs to be similar to the custom element as defined by the image. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     * - **stopThreshold** (*`number`, optional*):
+     *     - A threshold for when to stop searching for UI elements similar to the custom element. As soon as UI elements have been found that are at least as similar as the `stopThreshold`, the search is going to stop. After that elements are filtered using the `threshold`. Because of that the `stopThreshold` should be greater than or equal to `threshold`. It is primarily to be used as a speed improvement (by lowering the value). Takes values between `0.0` and `1.0`. Defaults to `0.9`.
      * - **rotationDegreePerStep** (*`number`, optional*):
      *     - Step size in rotation degree. Rotates the custom image by this step size until 360° is exceeded. The range is from `0` to `360`. Defaults to `0`.
-     * - **imageCompareFormat** (*`'RGB' | 'grayscale'`, optional*):
-     *     - The color compare style. 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three color. Defaults to 'grayscale'.
-     * of the given custom image.
+     * - **imageCompareFormat** (*`'RGB' | 'grayscale' | 'edges'`, optional*):
+     *     - The color compare style. 'edges' compares only edges, 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three colors (red, green, blue). Defaults to 'grayscale'.
      *
      *
      * @param {CustomElementJson} customElement - The custom element to filter for.
@@ -292,6 +315,23 @@ class FluentFilters extends FluentBase {
         this._params.set('customElement', customElement);
         return new FluentFiltersOrRelations(this);
     }
+    /**
+     * Detects an AI Element created with the workflow creator.
+     *
+     * @param {string} aiElementName - Name of the AI Element.
+     *
+     * @return {FluentFiltersOrRelations}
+     */
+    aiElement(aiElementName) {
+        this._textStr = '';
+        this._textStr += 'ai';
+        this._textStr += ' element';
+        this._textStr += ' with';
+        this._textStr += ' name';
+        this._textStr += ` ${Separators.STRING}${aiElementName}${Separators.STRING}`;
+        this._params.set('aiElementName', aiElementName);
+        return new FluentFiltersOrRelations(this);
+    }
     /**
      * Filters for a UI element 'image'.
      *
@@ -301,10 +341,14 @@ class FluentFilters extends FluentBase {
      * await aui.click().image().exec();
      *
      * // Works if you have an image with
-     * // a caption text below
-     * await aui.click().image().above().text().withText('The caption').exec();
+     * // a text below
+     * await aui.click().image().above().text().withText('Automating WebGL').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/image.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelations}
      */
     image() {
@@ -325,6 +369,10 @@ class FluentFilters extends FluentBase {
      * await aui.typeIn('Oh yeah').textfield().below().text().withText('E-Mail Address').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/textfield.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelations}
      */
     textfield() {
@@ -333,7 +381,13 @@ class FluentFilters extends FluentBase {
         return new FluentFiltersOrRelations(this);
     }
     /**
-     * Filters for similar (doesn't need to be a 100% equal) text.
+     * Filters for similar -- meaning >70% similar -- text.
+     *
+     * Takes an optional parameter to specify the similarity. Usually you need the optional parameter for long texts you want to match precisely.
+     *
+     * _We use [RapidFuzz](https://maxbachmann.github.io/RapidFuzz/Usage/fuzz.html#ratio) which calculates the similarity like this:_
+     *
+     * `1 - (distance / (lengthString1 + lengthString2))`
      *
      * **Examples:**
      * ```typescript
@@ -348,6 +402,11 @@ class FluentFilters extends FluentBase {
      * // usually false
      * 'atebxtc' === withText('text') => false
      * 'other' === withText('text') => false
+     *
+     * // optional parameter: similarity_score
+     * '978-0-201-00650-6' == withText('978-0-201-00') => true with 82.76 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => false with 82.76 < 90 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => true with 93.75 < 90 similarity
      * ```
      * ![](https://docs.askui.com/img/gif/withText.gif)
      *
@@ -378,6 +437,10 @@ class FluentFilters extends FluentBase {
      * await aui.get().text().withTextRegex('\b[Ss]\w+').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withtextregex.gif)
+     *
+     *
+     *
      * @param {string} regex_pattern - A regex pattern
      *
      * @return {FluentFiltersOrRelations}
@@ -406,6 +469,10 @@ class FluentFilters extends FluentBase {
      * await aui.moveMouseTo().text().withExactText('Password').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withexacttext.gif)
+     *
+     *
+     *
      * @param {string} text - A text to be matched.
      *
      * @return {FluentFiltersOrRelations}
@@ -442,17 +509,28 @@ class FluentFilters extends FluentBase {
     /**
      * Filters elements based on a textual description.
      *
-     * ## What Should I Write as Matching Text
+     * **What Should I Write as Matching Text**
+     *
      * The text description inside the `matching()` should describe the element visually.
      * It understands color, some famous company/product names, general descriptions.
      *
-     * It sometimes requires a bit of playing to find a matching description:
-     * E.g. `puzzle piece` can fail here while `an icon showing a puzzle piece` might work.
+     * It sometimes requires a bit of playing around to find a matching description:
+     * E.g. `puzzle piece` can fail while `an icon showing a puzzle piece` might work.
      * Generally the more detail the better.
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().matching('a mask on purple background and a firefox logo').exec()
+     * // Select the black sneaker from a bunch of sneakers
+     * await aui.click().element().matching('a black sneaker shoe').exec();
+     *
+     * // Select an image that has text in it
+     * await aui.click().element().matching('has Burger King in it').exec();
+     * await aui.click().element().matching('has adidas in it').exec();
+     *
+     * // Target a logo/image by describing it
+     * await aui.click().element().matching('a mask on purple background and a firefox logo').exec();
+     * await aui.click().element().matching('logo looking like an apple with one bite bitten off').exec();
+     * await aui.click().element().matching('logo looking like a seashell').exec();
      * ```
      *
      * @param {string} text - A description of the target element.
@@ -611,14 +689,19 @@ class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element right of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl    |  |  rightEl0  |  |  rightEl1  |
+     * --------------  --------------  --------------
      *
-     * // Returns rightEl because rightEl is right of leftEl
+     * // Returns rightEl0 because rightEl0 is the first element right of leftEl
      * ...rightEl().rightOf().leftEl()
+     * ...rightEl().rightOf(0).leftEl()
+     * // Returns rightEl1 because rightEl1 is the second element right of leftEl
+     * ...rightEl().rightOf(1).leftEl()
      * // Returns no element because leftEl is left of rightEl
      * ...leftEl().rightOf().rightEl()
      * ```
@@ -638,14 +721,19 @@ class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element left of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl1   |  |  leftEl0   |  |  rightEl   |
+     * --------------  --------------  --------------
      *
-     * // Returns leftEl because leftEl is left of rightEl
+     * // Returns leftEl0 because leftEl0 is the first element left of rightEl
      * ...leftEl().leftOf().rightEl()
+     * ...leftEl().leftOf(0).rightEl()
+     * // Returns leftEl1 because leftEl1 is the second element left of rightEl
+     * ...leftEl().leftOf(1).rightEl()
      * // Returns no element because rightEl is left of leftEl
      * ...rightEl().leftOf().leftEl()
      * ```
@@ -665,17 +753,25 @@ class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element below another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
      * |    text    |
      * --------------
      * --------------
-     * |   button   |
+     * |   button0  |
+     * --------------
+     * --------------
+     * |   button1  |
      * --------------
      *
-     * // Returns button because button is below text
+     * // Returns button0 because button0 is the first button below text
      * ...button().below().text()
+     * ...button().below(0).text()
+     * // Returns button1 because button1  is the second button below text
+     * ...button().below(1).text()
      * // Returns no element because text is above button
      * ...text().below().button()
      * ```
@@ -694,17 +790,25 @@ class FluentFiltersOrRelations extends FluentFilters {
     /**
      * Filters for an element above another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
-     * |    text    |
+     * |   text1    |
+     * --------------
+     * --------------
+     * |   text0    |
      * --------------
      * --------------
      * |   button   |
      * --------------
      *
-     * // Returns text because text is above button
+     * // Returns text0 because text0 is the first element above button
      * ...text().above().button()
+     * ...text().above(0).button()
+     * // Returns text1 because text1 is the second element above button
+     * ...text().above(1).button()
      * // Returns no element because button is below text
      * ...button().above().text()
      * ```
@@ -870,9 +974,11 @@ class FluentFiltersCondition extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.moveMouseTo().button().exec()
+     * await aui.click().button().contains().text().withText('Google Search').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/button.gif)
+     *
      * @return {FluentFiltersOrRelationsCondition}
      */
     button() {
@@ -932,13 +1038,20 @@ class FluentFiltersCondition extends FluentBase {
     /**
      * Filters for an UI element 'text'.
      *
-     * Often combined with the filter `withText()` as shown in the below examples.
+     * Takes an optional parameter to filter for a specific text.
+     * See the examples below.
+     *
      * See also the filters `withTextRegex()` and `withExactText()`
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().text().withText('Password').exec();
+     * await aui.click().text().exec();
+     * await aui.click().text('Username').exec();
+     *
+     * // Matching with an exact text
      * await aui.click().text().withExactText('Username').exec();
+     *
+     * // Matching with a regex
      * await aui.click().text().withTextRegex('\b[Ss]\w+').exec();
      * ```
      *
@@ -962,6 +1075,8 @@ class FluentFiltersCondition extends FluentBase {
      * icon().withText('plus')
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/icon.gif)
+     *
      * **Note:** This is an alpha feature. The prediction of the icon name is sometimes unstable. Use custom elements as an alternative.
      *
      * @return {FluentFiltersOrRelationsCondition}
@@ -972,7 +1087,9 @@ class FluentFiltersCondition extends FluentBase {
         return new FluentFiltersOrRelationsCondition(this);
     }
     /**
-     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element that is not recognized by our machine learning models by default. It can also be used for pixel assertions of elements using classical [template matching](https://en.wikipedia.org/wiki/Template_matching).
+     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element based on an image instead of using text or element descriptions like `button().withText('Submit')` in `await aui.click().button().withText('Submit').exec()`.
+     *
+     * See the tutorial - [Custom Element](https://docs.askui.com/docs/general/Tutorials/custom-element) for more detail.
      *
      * **Example**
      * ```typescript
@@ -982,6 +1099,7 @@ class FluentFiltersCondition extends FluentBase {
      *         customImage: './logo.png', // required
      *         name: 'myLogo', // optional
      *         threshold: 0.9, // optional, defaults to 0.9
+     *         stopThreshold: 0.9, // optional, defaults to 0.9
      *         rotationDegreePerStep: 0, // optional, defaults to 0
      *         imageCompareFormat: 'grayscale', // optional, defaults to 'grayscale'
      *         // mask:{x:0, y:0}[] // optional, a polygon to match only a certain area of the custom element
@@ -996,12 +1114,13 @@ class FluentFiltersCondition extends FluentBase {
      * - **name** (*`string`, optional*):
      *     - A unique name that can be used for filtering for the custom element. If not given, any text inside the custom image will be detected via OCR.
      * - **threshold** (*`number`, optional*):
-     *     - A threshold for how much a UI element needs to be similar to the custom element as defined. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     *     - A threshold for how much a UI element needs to be similar to the custom element as defined by the image. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     * - **stopThreshold** (*`number`, optional*):
+     *     - A threshold for when to stop searching for UI elements similar to the custom element. As soon as UI elements have been found that are at least as similar as the `stopThreshold`, the search is going to stop. After that elements are filtered using the `threshold`. Because of that the `stopThreshold` should be greater than or equal to `threshold`. It is primarily to be used as a speed improvement (by lowering the value). Takes values between `0.0` and `1.0`. Defaults to `0.9`.
      * - **rotationDegreePerStep** (*`number`, optional*):
      *     - Step size in rotation degree. Rotates the custom image by this step size until 360° is exceeded. The range is from `0` to `360`. Defaults to `0`.
-     * - **imageCompareFormat** (*`'RGB' | 'grayscale'`, optional*):
-     *     - The color compare style. 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three color. Defaults to 'grayscale'.
-     * of the given custom image.
+     * - **imageCompareFormat** (*`'RGB' | 'grayscale' | 'edges'`, optional*):
+     *     - The color compare style. 'edges' compares only edges, 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three colors (red, green, blue). Defaults to 'grayscale'.
      *
      *
      * @param {CustomElementJson} customElement - The custom element to filter for.
@@ -1015,6 +1134,23 @@ class FluentFiltersCondition extends FluentBase {
         this._params.set('customElement', customElement);
         return new FluentFiltersOrRelationsCondition(this);
     }
+    /**
+     * Detects an AI Element created with the workflow creator.
+     *
+     * @param {string} aiElementName - Name of the AI Element.
+     *
+     * @return {FluentFiltersOrRelationsCondition}
+     */
+    aiElement(aiElementName) {
+        this._textStr = '';
+        this._textStr += 'ai';
+        this._textStr += ' element';
+        this._textStr += ' with';
+        this._textStr += ' name';
+        this._textStr += ` ${Separators.STRING}${aiElementName}${Separators.STRING}`;
+        this._params.set('aiElementName', aiElementName);
+        return new FluentFiltersOrRelationsCondition(this);
+    }
     /**
      * Filters for a UI element 'image'.
      *
@@ -1024,10 +1160,14 @@ class FluentFiltersCondition extends FluentBase {
      * await aui.click().image().exec();
      *
      * // Works if you have an image with
-     * // a caption text below
-     * await aui.click().image().above().text().withText('The caption').exec();
+     * // a text below
+     * await aui.click().image().above().text().withText('Automating WebGL').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/image.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsCondition}
      */
     image() {
@@ -1048,6 +1188,10 @@ class FluentFiltersCondition extends FluentBase {
      * await aui.typeIn('Oh yeah').textfield().below().text().withText('E-Mail Address').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/textfield.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsCondition}
      */
     textfield() {
@@ -1056,7 +1200,13 @@ class FluentFiltersCondition extends FluentBase {
         return new FluentFiltersOrRelationsCondition(this);
     }
     /**
-     * Filters for similar (doesn't need to be a 100% equal) text.
+     * Filters for similar -- meaning >70% similar -- text.
+     *
+     * Takes an optional parameter to specify the similarity. Usually you need the optional parameter for long texts you want to match precisely.
+     *
+     * _We use [RapidFuzz](https://maxbachmann.github.io/RapidFuzz/Usage/fuzz.html#ratio) which calculates the similarity like this:_
+     *
+     * `1 - (distance / (lengthString1 + lengthString2))`
      *
      * **Examples:**
      * ```typescript
@@ -1071,6 +1221,11 @@ class FluentFiltersCondition extends FluentBase {
      * // usually false
      * 'atebxtc' === withText('text') => false
      * 'other' === withText('text') => false
+     *
+     * // optional parameter: similarity_score
+     * '978-0-201-00650-6' == withText('978-0-201-00') => true with 82.76 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => false with 82.76 < 90 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => true with 93.75 < 90 similarity
      * ```
      * ![](https://docs.askui.com/img/gif/withText.gif)
      *
@@ -1101,6 +1256,10 @@ class FluentFiltersCondition extends FluentBase {
      * await aui.get().text().withTextRegex('\b[Ss]\w+').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withtextregex.gif)
+     *
+     *
+     *
      * @param {string} regex_pattern - A regex pattern
      *
      * @return {FluentFiltersOrRelationsCondition}
@@ -1129,6 +1288,10 @@ class FluentFiltersCondition extends FluentBase {
      * await aui.moveMouseTo().text().withExactText('Password').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withexacttext.gif)
+     *
+     *
+     *
      * @param {string} text - A text to be matched.
      *
      * @return {FluentFiltersOrRelationsCondition}
@@ -1165,17 +1328,28 @@ class FluentFiltersCondition extends FluentBase {
     /**
      * Filters elements based on a textual description.
      *
-     * ## What Should I Write as Matching Text
+     * **What Should I Write as Matching Text**
+     *
      * The text description inside the `matching()` should describe the element visually.
      * It understands color, some famous company/product names, general descriptions.
      *
-     * It sometimes requires a bit of playing to find a matching description:
-     * E.g. `puzzle piece` can fail here while `an icon showing a puzzle piece` might work.
+     * It sometimes requires a bit of playing around to find a matching description:
+     * E.g. `puzzle piece` can fail while `an icon showing a puzzle piece` might work.
      * Generally the more detail the better.
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().matching('a mask on purple background and a firefox logo').exec()
+     * // Select the black sneaker from a bunch of sneakers
+     * await aui.click().element().matching('a black sneaker shoe').exec();
+     *
+     * // Select an image that has text in it
+     * await aui.click().element().matching('has Burger King in it').exec();
+     * await aui.click().element().matching('has adidas in it').exec();
+     *
+     * // Target a logo/image by describing it
+     * await aui.click().element().matching('a mask on purple background and a firefox logo').exec();
+     * await aui.click().element().matching('logo looking like an apple with one bite bitten off').exec();
+     * await aui.click().element().matching('logo looking like a seashell').exec();
      * ```
      *
      * @param {string} text - A description of the target element.
@@ -1334,14 +1508,19 @@ class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element right of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl    |  |  rightEl0  |  |  rightEl1  |
+     * --------------  --------------  --------------
      *
-     * // Returns rightEl because rightEl is right of leftEl
+     * // Returns rightEl0 because rightEl0 is the first element right of leftEl
      * ...rightEl().rightOf().leftEl()
+     * ...rightEl().rightOf(0).leftEl()
+     * // Returns rightEl1 because rightEl1 is the second element right of leftEl
+     * ...rightEl().rightOf(1).leftEl()
      * // Returns no element because leftEl is left of rightEl
      * ...leftEl().rightOf().rightEl()
      * ```
@@ -1361,14 +1540,19 @@ class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element left of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl1   |  |  leftEl0   |  |  rightEl   |
+     * --------------  --------------  --------------
      *
-     * // Returns leftEl because leftEl is left of rightEl
+     * // Returns leftEl0 because leftEl0 is the first element left of rightEl
      * ...leftEl().leftOf().rightEl()
+     * ...leftEl().leftOf(0).rightEl()
+     * // Returns leftEl1 because leftEl1 is the second element left of rightEl
+     * ...leftEl().leftOf(1).rightEl()
      * // Returns no element because rightEl is left of leftEl
      * ...rightEl().leftOf().leftEl()
      * ```
@@ -1388,17 +1572,25 @@ class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element below another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
      * |    text    |
      * --------------
      * --------------
-     * |   button   |
+     * |   button0  |
+     * --------------
+     * --------------
+     * |   button1  |
      * --------------
      *
-     * // Returns button because button is below text
+     * // Returns button0 because button0 is the first button below text
      * ...button().below().text()
+     * ...button().below(0).text()
+     * // Returns button1 because button1  is the second button below text
+     * ...button().below(1).text()
      * // Returns no element because text is above button
      * ...text().below().button()
      * ```
@@ -1417,17 +1609,25 @@ class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
     /**
      * Filters for an element above another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
-     * |    text    |
+     * |   text1    |
+     * --------------
+     * --------------
+     * |   text0    |
      * --------------
      * --------------
      * |   button   |
      * --------------
      *
-     * // Returns text because text is above button
+     * // Returns text0 because text0 is the first element above button
      * ...text().above().button()
+     * ...text().above(0).button()
+     * // Returns text1 because text1 is the second element above button
+     * ...text().above(1).button()
      * // Returns no element because button is below text
      * ...button().above().text()
      * ```
@@ -1511,12 +1711,12 @@ class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
      * **Examples:**
      * ```typescript
      * // Stops execution at this point when the element does not exist.
-     * await aui.expect().text().withText('Login').exists().exec()
+     * await aui.expect().text('Login').exists().exec()
      *
      * // This will catch the error and log a message
      * // But the execution will continue afterwards
      * try {
-     *     await aui.expect().text().withText('Login').exists().exec()
+     *     await aui.expect().text('Login').exists().exec()
      * } catch (error) {
      *     console.log('Too bad we could not find the element!');
      * }
@@ -1539,12 +1739,12 @@ class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
      * **Examples:**
      * ```typescript
      * // Stops execution at this point when the element does exist.
-     * await aui.expect().text().withText('Login').notExists().exec()
+     * await aui.expect().text('Login').notExists().exec()
      *
      * // This will catch the error and log a message
      * // But the execution will continue afterwards
      * try {
-     *     await aui.expect().text().withText('Login').notExists().exec()
+     *     await aui.expect().text('Login').notExists().exec()
      * } catch (error) {
      *     console.log('Too bad we could find the element!');
      * }
@@ -1574,8 +1774,8 @@ class FluentCommand extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.expect().text().withText('Login').exists().exec()
-     * await aui.expect().text().withText('Login').notExists().exec()
+     * await aui.expect().text('Login').exists().exec()
+     * await aui.expect().text('Login').notExists().exec()
      * ```
      *
      * @return {FluentFiltersCondition}
@@ -1592,9 +1792,13 @@ class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.click().button().withText('Submit').exec()
+     * await aui.click().button().withText('Google Search').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/click.gif)
+     *
+     *
+     *
      * @return {FluentFilters}
      */
     click() {
@@ -1608,9 +1812,13 @@ class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.moveMouseTo().button().withText('Submit').exec()
+     * await aui.moveMouseTo().text().withText('Grinning_Face').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/movemouseto.gif)
+     *
+     *
+     *
      * @return {FluentFilters}
      */
     moveMouseTo() {
@@ -1652,9 +1860,11 @@ class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.scroll(0, 10).textarea().exec()
+     * await aui.scrollInside(0,-500).text().withText('Bottom sheet').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/scrollinside.gif)
+     *
      * @param {number} x_offset - A (positive/negative) x direction.
      * @param {number} y_offset - A (positive/negative) y direction.
      *
@@ -1731,12 +1941,14 @@ class FluentCommand extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.type('Type some text').exec()
+     * await aui.type('askui@askui.com').exec()
      *
      * // mask the text so it is not send to the askui-inference server
      * await aui.type('Type some text', { isSecret: true, secretMask: '**' }).exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/type.gif)
+     *
      * @param {string} text - A text to type
      *
      * @return {Exec}
@@ -1752,9 +1964,11 @@ class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * await aui.moveMouseRelatively(20, 20).exec();
+     * await aui.moveMouseRelatively(0, 50).exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/movemouserelatively.gif)
+     *
      * @param {number} x_offset - A (positive/negative) x direction.
      * @param {number} y_offset - A (positive/negative) y direction.
      *
@@ -1784,6 +1998,8 @@ class FluentCommand extends FluentBase {
      * await aui.moveMouse(500, 500).exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/moveMouse.gif)
+     *
      * @param {number} x_coordinate - A (positive/negative) x coordinate.
      * @param {number} y_coordinate - A (positive/negative) y coordinate.
      *
@@ -1809,10 +2025,12 @@ class FluentCommand extends FluentBase {
      *
      * **Example:**
      * ```typescript
-     * // Scroll 10 up in y direction
-     * await aui.scroll(0, 10).exec()
+     * // Scroll 500 pixels down in y direction
+     * await aui.scroll(0, -500).exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/scroll.gif)
+     *
      * @param {number} x_offset - A (positive/negative) x direction.
      * @param {number} y_offset - A (positive/negative) y direction.
      *
@@ -1930,6 +2148,8 @@ class FluentCommand extends FluentBase {
      * await aui.mouseDoubleLeftClick().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mousedoubleleftclick.gif)
+     *
      * @return {Exec}
      */
     mouseDoubleLeftClick() {
@@ -1980,11 +2200,17 @@ class FluentCommand extends FluentBase {
     /**
      * Toggles mouse down (Left mouse key/tap).
      *
+     *  This is the equivalent to **mouse-left-press-and-hold**. It holds the mouse button until the `mouseToogleUp()` is called. Often combined with `mouseToggleUP` to automate **drag-and-drop**.
+     *
      * **Example:**
      * ```typescript
      * await aui.mouseToggleDown().exec();
+     * await aui.moveMouseRelatively(-400,0).exec();
+     * await aui.mouseToggleUp().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mouseToggleDownUp.gif)
+     *
      * @return {Exec}
      */
     mouseToggleDown() {
@@ -1995,11 +2221,17 @@ class FluentCommand extends FluentBase {
     /**
      * Toggles mouse up (Left mouse key/tap).
      *
+     * This is the equivalent to releasing the pressing mouse left button. Often combined with `mouseToggleDown()` to automate **drag-and-drop**.
+     *
      * **Example:**
      * ```typescript
+     * await aui.mouseToggleDown().exec();
+     * await aui.moveMouseRelatively(-400,0).exec();
      * await aui.mouseToggleUp().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mouseToggleDownUp.gif)
+     *
      * @return {Exec}
      */
     mouseToggleUp() {
@@ -2012,8 +2244,13 @@ class FluentCommand extends FluentBase {
      *
      * **Operating system specific mappings:**
      * 1. Windows: `command`-key maps to `windows`-key
-     * ---
      *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressThreeKeys('control', 'command' 'space').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressThreeKeys.gif)
      *
      * @param {MODIFIER_KEY} first_key - A modifier key
      * @param {MODIFIER_KEY} second_key - A modifier key
@@ -2056,8 +2293,13 @@ class FluentCommand extends FluentBase {
      *
      * **Operating system specific mappings:**
      * 1. Windows: `command`-key maps to `windows`-key
-     * ---
      *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressKey('tab').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressKey.gif)
      *
      * @param {PC_AND_MODIFIER_KEY} key - A key
      *
@@ -2090,7 +2332,15 @@ class FluentCommand extends FluentBase {
         return new Exec(this);
     }
     /**
-     * Press two Android keys like `ALT+F4`
+     * Press two Android keys like `volume_down+power`
+     * See [API docs](https://docs.askui.com/docs/api/Actions/pressandroidtwokey) for available keys.
+     *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressAndroidTwoKey('volume_down', 'power').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressAndroidTwoKey.gif)
      *
      * @param {ANDROID_KEY} first_key - A Android key
      * @param {ANDROID_KEY} second_key - A Android key
@@ -2107,7 +2357,15 @@ class FluentCommand extends FluentBase {
         return new Exec(this);
     }
     /**
-     * Press one Android key like `DEL`
+     * Press one Android key like `del`
+     * See [API docs](https://docs.askui.com/docs/api/Actions/pressandroidtwokey) for available keys.
+     *
+     * **Examples:**
+     * ```typescript
+     * await aui.pressAndroidKey('notification').exec();
+     * ```
+     *
+     * ![](https://docs.askui.com/img/gif/pressAndroidKey.gif)
      *
      * @param {ANDROID_KEY} key - A Android key
      *
@@ -2216,9 +2474,11 @@ class FluentFiltersGetter extends FluentBase {
      *
      * **Examples:**
      * ```typescript
-     * await aui.moveMouseTo().button().exec()
+     * await aui.click().button().contains().text().withText('Google Search').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/button.gif)
+     *
      * @return {FluentFiltersOrRelationsGetter}
      */
     button() {
@@ -2278,13 +2538,20 @@ class FluentFiltersGetter extends FluentBase {
     /**
      * Filters for an UI element 'text'.
      *
-     * Often combined with the filter `withText()` as shown in the below examples.
+     * Takes an optional parameter to filter for a specific text.
+     * See the examples below.
+     *
      * See also the filters `withTextRegex()` and `withExactText()`
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().text().withText('Password').exec();
+     * await aui.click().text().exec();
+     * await aui.click().text('Username').exec();
+     *
+     * // Matching with an exact text
      * await aui.click().text().withExactText('Username').exec();
+     *
+     * // Matching with a regex
      * await aui.click().text().withTextRegex('\b[Ss]\w+').exec();
      * ```
      *
@@ -2308,6 +2575,8 @@ class FluentFiltersGetter extends FluentBase {
      * icon().withText('plus')
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/icon.gif)
+     *
      * **Note:** This is an alpha feature. The prediction of the icon name is sometimes unstable. Use custom elements as an alternative.
      *
      * @return {FluentFiltersOrRelationsGetter}
@@ -2318,7 +2587,9 @@ class FluentFiltersGetter extends FluentBase {
         return new FluentFiltersOrRelationsGetter(this);
     }
     /**
-     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element that is not recognized by our machine learning models by default. It can also be used for pixel assertions of elements using classical [template matching](https://en.wikipedia.org/wiki/Template_matching).
+     * Filters for a 'custom element', that is a UI element which is defined by providing an image and other parameters such as degree of rotation. It allows filtering for a UI element based on an image instead of using text or element descriptions like `button().withText('Submit')` in `await aui.click().button().withText('Submit').exec()`.
+     *
+     * See the tutorial - [Custom Element](https://docs.askui.com/docs/general/Tutorials/custom-element) for more detail.
      *
      * **Example**
      * ```typescript
@@ -2328,6 +2599,7 @@ class FluentFiltersGetter extends FluentBase {
      *         customImage: './logo.png', // required
      *         name: 'myLogo', // optional
      *         threshold: 0.9, // optional, defaults to 0.9
+     *         stopThreshold: 0.9, // optional, defaults to 0.9
      *         rotationDegreePerStep: 0, // optional, defaults to 0
      *         imageCompareFormat: 'grayscale', // optional, defaults to 'grayscale'
      *         // mask:{x:0, y:0}[] // optional, a polygon to match only a certain area of the custom element
@@ -2342,12 +2614,13 @@ class FluentFiltersGetter extends FluentBase {
      * - **name** (*`string`, optional*):
      *     - A unique name that can be used for filtering for the custom element. If not given, any text inside the custom image will be detected via OCR.
      * - **threshold** (*`number`, optional*):
-     *     - A threshold for how much a UI element needs to be similar to the custom element as defined. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     *     - A threshold for how much a UI element needs to be similar to the custom element as defined by the image. Takes values between `0.0` (== all elements are recognized as the custom element which is probably not what you want) and `1.0` (== elements need to look exactly like the `customImage` which is unlikely to be achieved as even minor differences count). Defaults to `0.9`.
+     * - **stopThreshold** (*`number`, optional*):
+     *     - A threshold for when to stop searching for UI elements similar to the custom element. As soon as UI elements have been found that are at least as similar as the `stopThreshold`, the search is going to stop. After that elements are filtered using the `threshold`. Because of that the `stopThreshold` should be greater than or equal to `threshold`. It is primarily to be used as a speed improvement (by lowering the value). Takes values between `0.0` and `1.0`. Defaults to `0.9`.
      * - **rotationDegreePerStep** (*`number`, optional*):
      *     - Step size in rotation degree. Rotates the custom image by this step size until 360° is exceeded. The range is from `0` to `360`. Defaults to `0`.
-     * - **imageCompareFormat** (*`'RGB' | 'grayscale'`, optional*):
-     *     - The color compare style. 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three color. Defaults to 'grayscale'.
-     * of the given custom image.
+     * - **imageCompareFormat** (*`'RGB' | 'grayscale' | 'edges'`, optional*):
+     *     - The color compare style. 'edges' compares only edges, 'greyscale' compares the brightness of each pixel whereas 'RGB' compares all three colors (red, green, blue). Defaults to 'grayscale'.
      *
      *
      * @param {CustomElementJson} customElement - The custom element to filter for.
@@ -2361,6 +2634,23 @@ class FluentFiltersGetter extends FluentBase {
         this._params.set('customElement', customElement);
         return new FluentFiltersOrRelationsGetter(this);
     }
+    /**
+     * Detects an AI Element created with the workflow creator.
+     *
+     * @param {string} aiElementName - Name of the AI Element.
+     *
+     * @return {FluentFiltersOrRelationsGetter}
+     */
+    aiElement(aiElementName) {
+        this._textStr = '';
+        this._textStr += 'ai';
+        this._textStr += ' element';
+        this._textStr += ' with';
+        this._textStr += ' name';
+        this._textStr += ` ${Separators.STRING}${aiElementName}${Separators.STRING}`;
+        this._params.set('aiElementName', aiElementName);
+        return new FluentFiltersOrRelationsGetter(this);
+    }
     /**
      * Filters for a UI element 'image'.
      *
@@ -2370,10 +2660,14 @@ class FluentFiltersGetter extends FluentBase {
      * await aui.click().image().exec();
      *
      * // Works if you have an image with
-     * // a caption text below
-     * await aui.click().image().above().text().withText('The caption').exec();
+     * // a text below
+     * await aui.click().image().above().text().withText('Automating WebGL').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/image.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsGetter}
      */
     image() {
@@ -2394,6 +2688,10 @@ class FluentFiltersGetter extends FluentBase {
      * await aui.typeIn('Oh yeah').textfield().below().text().withText('E-Mail Address').exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/textfield.gif)
+     *
+     *
+     *
      * @return {FluentFiltersOrRelationsGetter}
      */
     textfield() {
@@ -2402,7 +2700,13 @@ class FluentFiltersGetter extends FluentBase {
         return new FluentFiltersOrRelationsGetter(this);
     }
     /**
-     * Filters for similar (doesn't need to be a 100% equal) text.
+     * Filters for similar -- meaning >70% similar -- text.
+     *
+     * Takes an optional parameter to specify the similarity. Usually you need the optional parameter for long texts you want to match precisely.
+     *
+     * _We use [RapidFuzz](https://maxbachmann.github.io/RapidFuzz/Usage/fuzz.html#ratio) which calculates the similarity like this:_
+     *
+     * `1 - (distance / (lengthString1 + lengthString2))`
      *
      * **Examples:**
      * ```typescript
@@ -2417,6 +2721,11 @@ class FluentFiltersGetter extends FluentBase {
      * // usually false
      * 'atebxtc' === withText('text') => false
      * 'other' === withText('text') => false
+     *
+     * // optional parameter: similarity_score
+     * '978-0-201-00650-6' == withText('978-0-201-00') => true with 82.76 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => false with 82.76 < 90 similarity
+     * '978-0-201-00650-6' == withText('978-0-201-00', 90) => true with 93.75 < 90 similarity
      * ```
      * ![](https://docs.askui.com/img/gif/withText.gif)
      *
@@ -2447,6 +2756,10 @@ class FluentFiltersGetter extends FluentBase {
      * await aui.get().text().withTextRegex('\b[Ss]\w+').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withtextregex.gif)
+     *
+     *
+     *
      * @param {string} regex_pattern - A regex pattern
      *
      * @return {FluentFiltersOrRelationsGetter}
@@ -2475,6 +2788,10 @@ class FluentFiltersGetter extends FluentBase {
      * await aui.moveMouseTo().text().withExactText('Password').exec()
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/withexacttext.gif)
+     *
+     *
+     *
      * @param {string} text - A text to be matched.
      *
      * @return {FluentFiltersOrRelationsGetter}
@@ -2511,17 +2828,28 @@ class FluentFiltersGetter extends FluentBase {
     /**
      * Filters elements based on a textual description.
      *
-     * ## What Should I Write as Matching Text
+     * **What Should I Write as Matching Text**
+     *
      * The text description inside the `matching()` should describe the element visually.
      * It understands color, some famous company/product names, general descriptions.
      *
-     * It sometimes requires a bit of playing to find a matching description:
-     * E.g. `puzzle piece` can fail here while `an icon showing a puzzle piece` might work.
+     * It sometimes requires a bit of playing around to find a matching description:
+     * E.g. `puzzle piece` can fail while `an icon showing a puzzle piece` might work.
      * Generally the more detail the better.
      *
      * **Examples:**
      * ```typescript
-     * await aui.click().matching('a mask on purple background and a firefox logo').exec()
+     * // Select the black sneaker from a bunch of sneakers
+     * await aui.click().element().matching('a black sneaker shoe').exec();
+     *
+     * // Select an image that has text in it
+     * await aui.click().element().matching('has Burger King in it').exec();
+     * await aui.click().element().matching('has adidas in it').exec();
+     *
+     * // Target a logo/image by describing it
+     * await aui.click().element().matching('a mask on purple background and a firefox logo').exec();
+     * await aui.click().element().matching('logo looking like an apple with one bite bitten off').exec();
+     * await aui.click().element().matching('logo looking like a seashell').exec();
      * ```
      *
      * @param {string} text - A description of the target element.
@@ -2680,14 +3008,19 @@ class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element right of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl    |  |  rightEl0  |  |  rightEl1  |
+     * --------------  --------------  --------------
      *
-     * // Returns rightEl because rightEl is right of leftEl
+     * // Returns rightEl0 because rightEl0 is the first element right of leftEl
      * ...rightEl().rightOf().leftEl()
+     * ...rightEl().rightOf(0).leftEl()
+     * // Returns rightEl1 because rightEl1 is the second element right of leftEl
+     * ...rightEl().rightOf(1).leftEl()
      * // Returns no element because leftEl is left of rightEl
      * ...leftEl().rightOf().rightEl()
      * ```
@@ -2707,14 +3040,19 @@ class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element left of another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
-     * --------------  --------------
-     * |  leftEl    |  |  rightEl   |
-     * --------------  --------------
+     * --------------  --------------  --------------
+     * |  leftEl1   |  |  leftEl0   |  |  rightEl   |
+     * --------------  --------------  --------------
      *
-     * // Returns leftEl because leftEl is left of rightEl
+     * // Returns leftEl0 because leftEl0 is the first element left of rightEl
      * ...leftEl().leftOf().rightEl()
+     * ...leftEl().leftOf(0).rightEl()
+     * // Returns leftEl1 because leftEl1 is the second element left of rightEl
+     * ...leftEl().leftOf(1).rightEl()
      * // Returns no element because rightEl is left of leftEl
      * ...rightEl().leftOf().leftEl()
      * ```
@@ -2734,17 +3072,25 @@ class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element below another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
      * |    text    |
      * --------------
      * --------------
-     * |   button   |
+     * |   button0  |
+     * --------------
+     * --------------
+     * |   button1  |
      * --------------
      *
-     * // Returns button because button is below text
+     * // Returns button0 because button0 is the first button below text
      * ...button().below().text()
+     * ...button().below(0).text()
+     * // Returns button1 because button1  is the second button below text
+     * ...button().below(1).text()
      * // Returns no element because text is above button
      * ...text().below().button()
      * ```
@@ -2763,17 +3109,25 @@ class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
     /**
      * Filters for an element above another element.
      *
+     * Takes an optional parameter `index` to select the `nth` element (starting with 0)
+     *
      * **Examples:**
      * ```typescript
      * --------------
-     * |    text    |
+     * |   text1    |
+     * --------------
+     * --------------
+     * |   text0    |
      * --------------
      * --------------
      * |   button   |
      * --------------
      *
-     * // Returns text because text is above button
+     * // Returns text0 because text0 is the first element above button
      * ...text().above().button()
+     * ...text().above(0).button()
+     * // Returns text1 because text1 is the second element above button
+     * ...text().above(1).button()
      * // Returns no element because button is below text
      * ...button().above().text()
      * ```
@@ -2868,22 +3222,74 @@ class Getter extends FluentCommand {
      *
      * **Examples:**
      * ```typescript
-     * const text = await aui.get().text().withText('Sign').exec();
+     * const text = await aui.get().text('Sign').exec();
      * console.log(text);
+     *
+     * // Console output
+     * [
+     *   DetectedElement {
+     *     name: 'TEXT',
+     *     text: 'Sign In',
+     *     bndbox: BoundingBox {
+     *       xmin: 1128.2720982142857,
+     *       ymin: 160.21332310267857,
+     *       xmax: 1178.8204241071428,
+     *       ymax: 180.83512834821428
+     *     }
+     *   }
+     * ]
      * ```
-     * ```text
-     *  console output: [
+     *
+     * // *************************************************** //
+     * // Examples on how to work with the returned elements  //
+     * // *************************************************** //
+     * const texts = await aui.get().text().below().textfield().exec();
+     *
+     * // We can get a lot of elements this way
+     * console.log(texts);
+     *
+     * // Console output
+     * [
      *   DetectedElement {
-     *      name: 'TEXT',
-     *      text: 'Sign In',
-     *      bndbox: BoundingBox {
-     *         xmin: 1128.2720982142857,
-     *         ymin: 160.21332310267857,
-     *         xmax: 1178.8204241071428,
-     *         ymax: 180.83512834821428
-     *      }
-     *    }
-     *  ]
+     *     name: 'TEXT',
+     *     text: 'Sign In',
+     *     bndbox: BoundingBox {
+     *       xmin: 1128.2720982142857,
+     *       ymin: 160.21332310267857,
+     *       xmax: 1178.8204241071428,
+     *       ymax: 180.83512834821428
+     *     },
+     *   },
+     *   DetectedElement {
+     *     name: 'TEXT',
+     *     text: 'Login',
+     *     bndbox: BoundingBox {
+     *       xmin: 250.8204241071428,
+     *       ymin: 300.21332310267857,
+     *       xmax: 450.6304241071428,
+     *       ymax: 950.47812834821428
+     *     },
+     *   },
+     *   ... 10 more items
+     * ]
+     *
+     * // Extract the FIRST element
+     * // Arrays start with index 0!
+     * const firstTextElement = texts[0];
+     * const textOfFirstElement = firstElement.text;
+     *
+     * console.log(textOfFirstElement);
+     *
+     * // Console output
+     * Sign In
+     *
+     * // Log the text of the SECOND element
+     * // with shorter code
+     * const texts = await aui.get().text().below().textfield().exec();
+     * console.log(texts[1].text)
+     *
+     * // Console output
+     * Login
      * ```
      *
      * @return {FluentFiltersGetter}