askui 0.13.0 → 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

@@ -129,7 +129,9 @@ class CreateExampleProject {
                                     nunjucks_1.default.configure(askuiHelperTemplateFilePath, { autoescape: false });
                                     const result = nunjucks_1.default.render(templateFileName, this.helperTemplateConfig);
                                     const filePath = path_1.default.join(this.distexampleFolderPath, 'helpers', 'askui-helper.ts');
-                                    yield fs_extra_1.default.mkdir(path_1.default.join(this.distexampleFolderPath, 'helpers'));
+                                    if (!fs_extra_1.default.existsSync(path_1.default.join(this.distexampleFolderPath, 'helpers'))) {
+                                        yield fs_extra_1.default.mkdir(path_1.default.join(this.distexampleFolderPath, 'helpers'));
+                                    }
                                     yield fs_extra_1.default.writeFile(filePath, result, 'utf8');
                                 }),
                             },
@@ -183,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([
                             {
@@ -270,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

@@ -123,7 +123,9 @@ export class CreateExampleProject {
                                     nunjucks.configure(askuiHelperTemplateFilePath, { autoescape: false });
                                     const result = nunjucks.render(templateFileName, this.helperTemplateConfig);
                                     const filePath = path.join(this.distexampleFolderPath, 'helpers', 'askui-helper.ts');
-                                    yield fs.mkdir(path.join(this.distexampleFolderPath, 'helpers'));
+                                    if (!fs.existsSync(path.join(this.distexampleFolderPath, 'helpers'))) {
+                                        yield fs.mkdir(path.join(this.distexampleFolderPath, 'helpers'));
+                                    }
                                     yield fs.writeFile(filePath, result, 'utf8');
                                 }),
                             },
@@ -177,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([
                             {
@@ -264,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.0",
+    "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"