askui 0.18.0 → 0.18.1

package/dist/cjs/execution/dsl.js

@@ -147,9 +147,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 +211,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 +248,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 +260,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 +272,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 +287,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.
@@ -301,10 +316,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 +344,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 +356,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 +377,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 +412,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 +444,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,12 +484,13 @@ 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:**
@@ -611,14 +654,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 +686,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 +718,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 +755,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 +939,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 +1003,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 +1040,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 +1052,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 +1064,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 +1079,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.
@@ -1024,10 +1108,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 +1136,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 +1148,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 +1169,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 +1204,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 +1236,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,12 +1276,13 @@ 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:**
@@ -1334,14 +1446,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 +1478,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 +1510,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 +1547,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 +1649,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 +1677,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 +1712,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 +1730,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 +1750,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 +1798,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 +1879,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 +1902,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 +1936,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 +1963,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 +2086,8 @@ class FluentCommand extends FluentBase {
      * await aui.mouseDoubleLeftClick().exec();
      * ```
      *
+     * ![](https://docs.askui.com/img/gif/mousedoubleleftclick.gif)
+     *
      * @return {Exec}
      */
     mouseDoubleLeftClick() {
@@ -1980,11 +2138,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 +2159,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 +2182,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 +2231,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 +2270,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 +2295,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 +2412,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 +2476,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 +2513,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 +2525,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 +2537,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 +2552,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.
@@ -2370,10 +2581,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 +2609,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 +2621,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 +2642,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 +2677,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 +2709,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,12 +2749,13 @@ 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:**
@@ -2680,14 +2919,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 +2951,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 +2983,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 +3020,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,7 +3133,7 @@ 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);
      * ```
      * ```text