askui 0.13.1 → 0.14.0

package/dist/cjs/execution/ui-control-client.d.ts

@@ -1,5 +1,5 @@
 import { CustomElementJson } from '../core/model/custom-element-json';
-import { Exec, Executable, FluentFilters, ApiCommands } from './dsl';
+import { Exec, Executable, FluentFilters, ApiCommands, PC_AND_MODIFIER_KEY } from './dsl';
 import { UiControllerClientConnectionState } from './ui-controller-client-connection-state';
 import { Annotation } from '../core/annotation/annotation';
 import { AnnotationRequest } from '../core/model/annotation-result/annotation-interface';
@@ -56,8 +56,8 @@ export declare class UiControlClient extends ApiCommands {
      * @return {FluentFilters}
      */
     typeIn(text: string, { isSecret, secretMask }?: {
-        isSecret?: boolean | undefined;
-        secretMask?: string | undefined;
+        isSecret?: boolean;
+        secretMask?: string;
     }): FluentFilters;
     /**
      * Types a text at the current position.
@@ -78,8 +78,8 @@ export declare class UiControlClient extends ApiCommands {
      * @return {Exec}
      */
     type(text: string, { isSecret, secretMask }?: {
-        isSecret?: boolean | undefined;
-        secretMask?: string | undefined;
+        isSecret?: boolean;
+        secretMask?: string;
     }): Exec;
     /**
      * Waits for `<delayInMs>` ms, e.g., 1000 ms. The exact delay may be a little longer
@@ -90,4 +90,85 @@ export declare class UiControlClient extends ApiCommands {
      * @return {Executable}
      */
     waitFor(delayInMs: number): Executable;
+    /**
+     * Press a key multiple times. At least two times.
+     *
+     * @param {PC_AND_MODIFIER_KEY} key
+     *
+     * @param {number} times
+     */
+    pressKeyNTimes(key: PC_AND_MODIFIER_KEY, times?: number): Promise<void>;
+    /**
+     * Press an array of keys one after another.
+     *
+     * For example press the following keys: right, left, enter.
+     *
+     * pressKeys(['right', 'left', 'enter'])
+     *
+     * @param {PC_AND_MODIFIER_KEY[]} keys
+     */
+    pressKeys(keys: PC_AND_MODIFIER_KEY[]): Promise<void>;
+    /**
+     * Searches for a text element and clicks it when found.
+     *
+     * @param {string} text - A text to be searched.
+     */
+    clickText(text: string): Promise<void>;
+    /**
+     * Searches for text elements and clicks them
+     * one after another when found.
+     *
+     * @param {string[]} texts - An array of texts to be searched.
+     */
+    clickTexts(texts: string[]): Promise<void>;
+    /**
+     * Searches for an element of type button
+     * with a label and clicks it when found.
+     *
+     * @param {string} label - The buttons label.
+     */
+    clickButton(label: string): Promise<void>;
+    /**
+     * Searches for an element of type textfield with a specific placeholder text.
+     * If found, clicks it.
+     *
+     * @param {string} placeholder - The textfields placeholder text.
+     */
+    clickTextfield(placeholder: string): Promise<void>;
+    /**
+     * Clicks an icon based on a description.
+     *
+     * @param {string} description
+     */
+    clickIcon(description: string): Promise<void>;
+    /**
+     * Drags element1 to element2.
+     *
+     * Both must be a `moveMouse()` or `moveMouseTo()`
+     * instruction as in the example below.
+     *
+     * Usage example:
+     * dragTo(
+     *   aui.moveMouseTo().text('AskUI'),
+     *   aui.moveMouseTo().text('UI Automation')
+     * )
+     *
+     * @param {Executable} element1
+     * @param {Executable} element2
+     */
+    dragTo(element1: Executable, element2: Executable): Promise<void>;
+    /**
+     * Wait until an AskUICommand does not fail.
+     *
+     * Use it to wait for an element to appear like this:
+     *
+     * await waitUntil(
+     *     aui.expect().text('Github').exists()
+     *   );
+     *
+     * @param {Executable} AskUICommand - For example: aui.moveMouse(0, 0)
+     * @param {number} maxTry - Number of maximum retries
+     * @param {number} waitTime - Time in milliseconds
+     */
+    waitUntil(AskUICommand: Executable, maxTry?: number, waitTime?: number): Promise<void>;
 }

package/dist/cjs/execution/ui-control-client.js

@@ -217,5 +217,146 @@ class UiControlClient extends dsl_1.ApiCommands {
             },
         };
     }
+    /**
+     * Press a key multiple times. At least two times.
+     *
+     * @param {PC_AND_MODIFIER_KEY} key
+     *
+     * @param {number} times
+     */
+    pressKeyNTimes(key, times = 2) {
+        return __awaiter(this, void 0, void 0, function* () {
+            /* eslint-disable no-await-in-loop */
+            for (let i = 0; i < times; i += 1) {
+                yield this.pressKey(key).exec();
+            }
+        });
+    }
+    /**
+     * Press an array of keys one after another.
+     *
+     * For example press the following keys: right, left, enter.
+     *
+     * pressKeys(['right', 'left', 'enter'])
+     *
+     * @param {PC_AND_MODIFIER_KEY[]} keys
+     */
+    pressKeys(keys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            /* eslint-disable no-await-in-loop */
+            for (let i = 0; i < keys.length; i += 1) {
+                yield this.pressKey(keys[i]).exec();
+            }
+        });
+    }
+    /**
+     * Searches for a text element and clicks it when found.
+     *
+     * @param {string} text - A text to be searched.
+     */
+    clickText(text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().text(text).exec();
+        });
+    }
+    /**
+     * Searches for text elements and clicks them
+     * one after another when found.
+     *
+     * @param {string[]} texts - An array of texts to be searched.
+     */
+    clickTexts(texts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            /* eslint-disable no-await-in-loop */
+            for (let i = 0; i < texts.length; i += 1) {
+                yield this.click().text(texts[i]).exec();
+            }
+        });
+    }
+    /**
+     * Searches for an element of type button
+     * with a label and clicks it when found.
+     *
+     * @param {string} label - The buttons label.
+     */
+    clickButton(label) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().button().withText(label).exec();
+        });
+    }
+    /**
+     * Searches for an element of type textfield with a specific placeholder text.
+     * If found, clicks it.
+     *
+     * @param {string} placeholder - The textfields placeholder text.
+     */
+    clickTextfield(placeholder) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().textfield().contains().text()
+                .withText(placeholder)
+                .exec();
+        });
+    }
+    /**
+     * Clicks an icon based on a description.
+     *
+     * @param {string} description
+     */
+    clickIcon(description) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().icon().matching(description).exec();
+        });
+    }
+    /**
+     * Drags element1 to element2.
+     *
+     * Both must be a `moveMouse()` or `moveMouseTo()`
+     * instruction as in the example below.
+     *
+     * Usage example:
+     * dragTo(
+     *   aui.moveMouseTo().text('AskUI'),
+     *   aui.moveMouseTo().text('UI Automation')
+     * )
+     *
+     * @param {Executable} element1
+     * @param {Executable} element2
+     */
+    dragTo(element1, element2) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield element1.exec();
+            yield this.mouseLeftClick().exec();
+            yield this.mouseToggleDown().exec();
+            yield element2.exec();
+            yield this.mouseToggleUp().exec();
+        });
+    }
+    /**
+     * Wait until an AskUICommand does not fail.
+     *
+     * Use it to wait for an element to appear like this:
+     *
+     * await waitUntil(
+     *     aui.expect().text('Github').exists()
+     *   );
+     *
+     * @param {Executable} AskUICommand - For example: aui.moveMouse(0, 0)
+     * @param {number} maxTry - Number of maximum retries
+     * @param {number} waitTime - Time in milliseconds
+     */
+    waitUntil(AskUICommand, maxTry = 5, waitTime = 2000) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield AskUICommand.exec();
+            }
+            catch (error) {
+                if (maxTry === 0) {
+                    throw error;
+                }
+                yield this.waitFor(waitTime).exec();
+                yield this.waitUntil(AskUICommand, maxTry - 1);
+            }
+        });
+    }
 }
 exports.UiControlClient = UiControlClient;

package/dist/cjs/lib/interactive_cli/create-example-project.d.ts

@@ -17,7 +17,7 @@ export declare class CreateExampleProject {
     private createAskUIHelperFromTemplate;
     private setupTestFrameWork;
     private installTestFrameworkPackages;
-    private addUserCredentails;
+    private addUserCredentials;
     private copyESLintConfigFiles;
     private copyTsConfigFile;
     private installProxy;

package/dist/cjs/lib/interactive_cli/create-example-project.js

@@ -185,10 +185,10 @@ class CreateExampleProject {
             yield runCommand(frameworkDepencies[this.cliOptions.testFramework]);
         });
     }
-    addUserCredentails() {
+    addUserCredentials() {
         return __awaiter(this, void 0, void 0, function* () {
             return [{
-                    title: 'Add user credentails',
+                    title: 'Add user credentials',
                     task: () => __awaiter(this, void 0, void 0, function* () {
                         return new listr_1.default([
                             {
@@ -272,7 +272,7 @@ class CreateExampleProject {
                 ...yield this.setupTestFrameWork(),
                 ...yield this.copyESLintConfigFiles(),
                 ...yield this.copyTsConfigFile(),
-                ...yield this.addUserCredentails(),
+                ...yield this.addUserCredentials(),
                 ...yield this.createAskUIHelperFromTemplate(),
                 ...yield this.installProxy(),
             ]);

package/dist/esm/execution/ui-control-client.d.ts

@@ -1,5 +1,5 @@
 import { CustomElementJson } from '../core/model/custom-element-json';
-import { Exec, Executable, FluentFilters, ApiCommands } from './dsl';
+import { Exec, Executable, FluentFilters, ApiCommands, PC_AND_MODIFIER_KEY } from './dsl';
 import { UiControllerClientConnectionState } from './ui-controller-client-connection-state';
 import { Annotation } from '../core/annotation/annotation';
 import { AnnotationRequest } from '../core/model/annotation-result/annotation-interface';
@@ -56,8 +56,8 @@ export declare class UiControlClient extends ApiCommands {
      * @return {FluentFilters}
      */
     typeIn(text: string, { isSecret, secretMask }?: {
-        isSecret?: boolean | undefined;
-        secretMask?: string | undefined;
+        isSecret?: boolean;
+        secretMask?: string;
     }): FluentFilters;
     /**
      * Types a text at the current position.
@@ -78,8 +78,8 @@ export declare class UiControlClient extends ApiCommands {
      * @return {Exec}
      */
     type(text: string, { isSecret, secretMask }?: {
-        isSecret?: boolean | undefined;
-        secretMask?: string | undefined;
+        isSecret?: boolean;
+        secretMask?: string;
     }): Exec;
     /**
      * Waits for `<delayInMs>` ms, e.g., 1000 ms. The exact delay may be a little longer
@@ -90,4 +90,85 @@ export declare class UiControlClient extends ApiCommands {
      * @return {Executable}
      */
     waitFor(delayInMs: number): Executable;
+    /**
+     * Press a key multiple times. At least two times.
+     *
+     * @param {PC_AND_MODIFIER_KEY} key
+     *
+     * @param {number} times
+     */
+    pressKeyNTimes(key: PC_AND_MODIFIER_KEY, times?: number): Promise<void>;
+    /**
+     * Press an array of keys one after another.
+     *
+     * For example press the following keys: right, left, enter.
+     *
+     * pressKeys(['right', 'left', 'enter'])
+     *
+     * @param {PC_AND_MODIFIER_KEY[]} keys
+     */
+    pressKeys(keys: PC_AND_MODIFIER_KEY[]): Promise<void>;
+    /**
+     * Searches for a text element and clicks it when found.
+     *
+     * @param {string} text - A text to be searched.
+     */
+    clickText(text: string): Promise<void>;
+    /**
+     * Searches for text elements and clicks them
+     * one after another when found.
+     *
+     * @param {string[]} texts - An array of texts to be searched.
+     */
+    clickTexts(texts: string[]): Promise<void>;
+    /**
+     * Searches for an element of type button
+     * with a label and clicks it when found.
+     *
+     * @param {string} label - The buttons label.
+     */
+    clickButton(label: string): Promise<void>;
+    /**
+     * Searches for an element of type textfield with a specific placeholder text.
+     * If found, clicks it.
+     *
+     * @param {string} placeholder - The textfields placeholder text.
+     */
+    clickTextfield(placeholder: string): Promise<void>;
+    /**
+     * Clicks an icon based on a description.
+     *
+     * @param {string} description
+     */
+    clickIcon(description: string): Promise<void>;
+    /**
+     * Drags element1 to element2.
+     *
+     * Both must be a `moveMouse()` or `moveMouseTo()`
+     * instruction as in the example below.
+     *
+     * Usage example:
+     * dragTo(
+     *   aui.moveMouseTo().text('AskUI'),
+     *   aui.moveMouseTo().text('UI Automation')
+     * )
+     *
+     * @param {Executable} element1
+     * @param {Executable} element2
+     */
+    dragTo(element1: Executable, element2: Executable): Promise<void>;
+    /**
+     * Wait until an AskUICommand does not fail.
+     *
+     * Use it to wait for an element to appear like this:
+     *
+     * await waitUntil(
+     *     aui.expect().text('Github').exists()
+     *   );
+     *
+     * @param {Executable} AskUICommand - For example: aui.moveMouse(0, 0)
+     * @param {number} maxTry - Number of maximum retries
+     * @param {number} waitTime - Time in milliseconds
+     */
+    waitUntil(AskUICommand: Executable, maxTry?: number, waitTime?: number): Promise<void>;
 }

package/dist/esm/execution/ui-control-client.js

@@ -214,4 +214,145 @@ export class UiControlClient extends ApiCommands {
             },
         };
     }
+    /**
+     * Press a key multiple times. At least two times.
+     *
+     * @param {PC_AND_MODIFIER_KEY} key
+     *
+     * @param {number} times
+     */
+    pressKeyNTimes(key, times = 2) {
+        return __awaiter(this, void 0, void 0, function* () {
+            /* eslint-disable no-await-in-loop */
+            for (let i = 0; i < times; i += 1) {
+                yield this.pressKey(key).exec();
+            }
+        });
+    }
+    /**
+     * Press an array of keys one after another.
+     *
+     * For example press the following keys: right, left, enter.
+     *
+     * pressKeys(['right', 'left', 'enter'])
+     *
+     * @param {PC_AND_MODIFIER_KEY[]} keys
+     */
+    pressKeys(keys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            /* eslint-disable no-await-in-loop */
+            for (let i = 0; i < keys.length; i += 1) {
+                yield this.pressKey(keys[i]).exec();
+            }
+        });
+    }
+    /**
+     * Searches for a text element and clicks it when found.
+     *
+     * @param {string} text - A text to be searched.
+     */
+    clickText(text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().text(text).exec();
+        });
+    }
+    /**
+     * Searches for text elements and clicks them
+     * one after another when found.
+     *
+     * @param {string[]} texts - An array of texts to be searched.
+     */
+    clickTexts(texts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            /* eslint-disable no-await-in-loop */
+            for (let i = 0; i < texts.length; i += 1) {
+                yield this.click().text(texts[i]).exec();
+            }
+        });
+    }
+    /**
+     * Searches for an element of type button
+     * with a label and clicks it when found.
+     *
+     * @param {string} label - The buttons label.
+     */
+    clickButton(label) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().button().withText(label).exec();
+        });
+    }
+    /**
+     * Searches for an element of type textfield with a specific placeholder text.
+     * If found, clicks it.
+     *
+     * @param {string} placeholder - The textfields placeholder text.
+     */
+    clickTextfield(placeholder) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().textfield().contains().text()
+                .withText(placeholder)
+                .exec();
+        });
+    }
+    /**
+     * Clicks an icon based on a description.
+     *
+     * @param {string} description
+     */
+    clickIcon(description) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.click().icon().matching(description).exec();
+        });
+    }
+    /**
+     * Drags element1 to element2.
+     *
+     * Both must be a `moveMouse()` or `moveMouseTo()`
+     * instruction as in the example below.
+     *
+     * Usage example:
+     * dragTo(
+     *   aui.moveMouseTo().text('AskUI'),
+     *   aui.moveMouseTo().text('UI Automation')
+     * )
+     *
+     * @param {Executable} element1
+     * @param {Executable} element2
+     */
+    dragTo(element1, element2) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield element1.exec();
+            yield this.mouseLeftClick().exec();
+            yield this.mouseToggleDown().exec();
+            yield element2.exec();
+            yield this.mouseToggleUp().exec();
+        });
+    }
+    /**
+     * Wait until an AskUICommand does not fail.
+     *
+     * Use it to wait for an element to appear like this:
+     *
+     * await waitUntil(
+     *     aui.expect().text('Github').exists()
+     *   );
+     *
+     * @param {Executable} AskUICommand - For example: aui.moveMouse(0, 0)
+     * @param {number} maxTry - Number of maximum retries
+     * @param {number} waitTime - Time in milliseconds
+     */
+    waitUntil(AskUICommand, maxTry = 5, waitTime = 2000) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield AskUICommand.exec();
+            }
+            catch (error) {
+                if (maxTry === 0) {
+                    throw error;
+                }
+                yield this.waitFor(waitTime).exec();
+                yield this.waitUntil(AskUICommand, maxTry - 1);
+            }
+        });
+    }
 }

package/dist/esm/lib/interactive_cli/create-example-project.d.ts

@@ -17,7 +17,7 @@ export declare class CreateExampleProject {
     private createAskUIHelperFromTemplate;
     private setupTestFrameWork;
     private installTestFrameworkPackages;
-    private addUserCredentails;
+    private addUserCredentials;
     private copyESLintConfigFiles;
     private copyTsConfigFile;
     private installProxy;

package/dist/esm/lib/interactive_cli/create-example-project.js

@@ -179,10 +179,10 @@ export class CreateExampleProject {
             yield runCommand(frameworkDepencies[this.cliOptions.testFramework]);
         });
     }
-    addUserCredentails() {
+    addUserCredentials() {
         return __awaiter(this, void 0, void 0, function* () {
             return [{
-                    title: 'Add user credentails',
+                    title: 'Add user credentials',
                     task: () => __awaiter(this, void 0, void 0, function* () {
                         return new Listr([
                             {
@@ -266,7 +266,7 @@ export class CreateExampleProject {
                 ...yield this.setupTestFrameWork(),
                 ...yield this.copyESLintConfigFiles(),
                 ...yield this.copyTsConfigFile(),
-                ...yield this.addUserCredentails(),
+                ...yield this.addUserCredentials(),
                 ...yield this.createAskUIHelperFromTemplate(),
                 ...yield this.installProxy(),
             ]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "askui",
-    "version": "0.13.1",
+    "version": "0.14.0",
     "license": "MIT",
     "author": "askui GmbH <info@askui.com> (http://www.askui.com/)",
     "description": "Reliable, automated end-to-end-testing that depends on what is shown on your screen instead of the technology you are running on",
@@ -62,10 +62,10 @@
         "nunjucks": "^3.2.4",
         "pino": "7.8.1",
         "pino-pretty": "7.5.3",
-        "tough-cookie": "4.1.2",
+        "tough-cookie": "^4.1.3",
         "url-join": "4.0.1",
         "wait-port": "0.2.9",
-        "ws": "7.4.4",
+        "ws": "^7.5.9",
         "yup": "0.32.11"
     },
     "devDependencies": {
@@ -84,7 +84,7 @@
         "jest": "28.1.1",
         "jest-extended": "^4.0.1",
         "proxy": "^1.0.2",
-        "proxy-agent": "^5.0.0",
+        "proxy-agent": "^6.3.1",
         "shx": "0.3.4",
         "ts-jest": "28.0.4",
         "typescript": "4.5.4"

package/dist/cjs/core/model/test-case-dto/custom-element-json.d.ts

@@ -1,75 +0,0 @@
-/**
- * Defines a 'custom element'. This 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).
- *
- * **Important:** The `CustomElementJson` needs to capture as accurately as possible
- * what the custom element looks like during test execution as otherwise
- * our machine learning models cannot find it, even with the additional data
- * provided. This is especially true for the resolution used while cropping
- * the `CustomElementJson.customImage` which should match the resolution during
- * test execution.
- *
- * Rotated custom elements can be filtered for using
- * `CustomElementJson.rotationDegreePerStep`.
- */
-export interface CustomElementJson {
-    /**
-     * An cropped image in form of a base64 string or file path,
-     * e.g., "./custom.png".
-     */
-    customImage: string;
-    /**
-     * A unique name which can be used for filtering for the custom element,
-     * e.g.,
-     * ```typescript
-     * ...customElement({
-     *   name: 'unique-name',
-     *   // ... (rest of the custom element)
-     * }).withText('unique-name')
-     * ```
-     *
-     * If not set, the text inside the custom element is
-     * detected via
-     * [OCR](https://en.wikipedia.org/wiki/Optical_character_recognition).
-     * It can also be used for filtering for the custom element.
-     */
-    name?: string | undefined;
-    /**
-     * A threshold for how similar UI elements shown during test execution
-     * need to be to the custom element as defined by the other fields in
-     * `CustomElementJson` to be recognized as such. 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 defined by `CustomElementJson` which is unlikely to be achieved
-     * as even minor differences count). Defaults to `0.9`.
-     */
-    threshold?: number | undefined;
-    /**
-     * A step size in rotation degree. Rotates the custom image by
-     * `rotationDegreePerStep` until 360° is exceeded. Range is between
-     * 0° - 360°. Defaults to 0°.
-     *
-     * **Important**: This increases the prediction time quite a bit. So only use
-     * it when absolutely necessary.
-     */
-    rotationDegreePerStep?: number | undefined;
-    /**
-     * A color compare style. Allows matching a custom element by color, e.g.,
-     * instead of filtering for all icons (blue and green ones),
-     * only the green ones captured by `customImage` are filtered for using 'RGB'.
-     * Defaults to 'grayscale'.
-     *
-     * **Important**: This increases the prediction time quite a bit. So only use
-     * it when absolutely necessary.
-     */
-    imageCompareFormat?: 'RGB' | 'grayscale' | undefined;
-    /** A polygon to match only a certain area of the custom element. */
-    mask?: ({
-        x: number;
-        y: number;
-    })[] | undefined;
-}

package/dist/cjs/core/model/test-case-dto/custom-element-json.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });