askui 0.4.0 → 0.6.0

package/dist/cjs/lib/ui-controller-facade.js

@@ -24,6 +24,7 @@ const download_binaries_1 = require("./download-binaries");
 const logger_1 = require("./logger");
 const timeout_error_1 = require("./timeout-error");
 const unkown_error_1 = require("./unkown-error");
+const proxy_builder_1 = require("../utils/proxy/proxy-builder");
 class UiControllerFacade {
     constructor() {
         this.binaryPath = (0, download_binaries_1.getBinaryPath)('latest');
@@ -35,7 +36,7 @@ class UiControllerFacade {
             const argsWithDefaults = (0, ui_controller_args_1.createArgsWithDefaults)(args);
             const argsWithLogPath = this.serverLogFilePath(argsWithDefaults);
             this.binaryPath = (0, download_binaries_1.getBinaryPath)(argsWithLogPath.binaryVersion);
-            yield this.getBinary(argsWithLogPath.binaryVersion, argsWithLogPath.overWriteBinary);
+            yield this.getBinary(argsWithLogPath.binaryVersion, argsWithLogPath.overWriteBinary, argsWithLogPath.proxyAgents || (yield (0, proxy_builder_1.buildProxyAgentArgsFromEnvironment)()));
             this.makeBinaryExecutable();
             logger_1.logger.debug(`UI Controller log path "${this.serverLogFile}"`);
             yield this.startWithDefaults(argsWithLogPath, maxWaitingForStartingInSeconds);
@@ -109,11 +110,11 @@ class UiControllerFacade {
         const binarysizeInMB = fs_extra_1.default.statSync(this.binaryPath).size / (1024 * 1024);
         return binarysizeInMB > sizeThresholdInMB;
     }
-    getBinary(binaryVersion, overWriteBinary = false) {
+    getBinary(binaryVersion, overWriteBinary = false, proxyAgent) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!fs_extra_1.default.existsSync(this.binaryPath) || overWriteBinary || !this.isBinaryValid()) {
                 logger_1.logger.debug(`Currently, no binary of the UI Controller is available at "${this.binaryPath}"`);
-                yield (0, download_binaries_1.downloadServerBinaries)(binaryVersion);
+                yield (0, download_binaries_1.downloadServerBinaries)(binaryVersion, proxyAgent);
             }
             else {
                 logger_1.logger.debug(`Binary of UI Controller is already present at "${this.binaryPath}".`);

package/dist/cjs/shared/proxy-agent-args.d.ts

@@ -0,0 +1,35 @@
+/// <reference types="node" />
+import http from 'http';
+import https from 'https';
+/**
+ * Proxy agent configuration for HTTP(S) requests
+ *
+ * All modules which implement the `http.Agent`'s or `https.Agent`'s
+ * interface, respectively, can be used.
+ * We recommend to use [hpagent](https://github.com/delvedore/hpagent).
+ *
+ * Installation:
+ * ```shell
+ * npm install --save hpagent
+ * ```
+ *
+ * Configuration:
+ * ```typescript
+ *  const httpProxyUrl = "http://your-proxy:3128";
+ *  const httpsProxyUrl = "https://your-proxy:3129";
+ *
+ *  const aui = await UiControlClient.build({
+ *    proxyAgents: {
+ *      http: new HttpProxyAgent({ proxy: httpProxyUrl }),
+ *      https: new HttpsProxyAgent({ proxy: httpsProxyUrl }),
+ *    },
+ *  });
+ * ```
+ *
+ * @param {http.Agent} http - Agent for http requests
+ * @param {https.Agent} https - Agent for https requests
+ ** */
+export interface ProxyAgentArgs {
+    http: http.Agent;
+    https: https.Agent;
+}

package/dist/cjs/shared/proxy-agent-args.js

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

package/dist/cjs/utils/http/http-client-got.d.ts

@@ -1,10 +1,20 @@
 import { OptionsOfJSONResponseBody } from 'got';
+import http from 'http';
+import https from 'https';
 export declare class HttpClientGot {
     readonly token?: string | undefined;
     readonly customHeaders?: Record<string, string> | undefined;
     private readonly cookies;
+    readonly proxyAgents?: {
+        http: http.Agent;
+        https: https.Agent;
+    } | undefined;
     private headers;
-    constructor(token?: string | undefined, customHeaders?: Record<string, string> | undefined, cookies?: Record<string, string>);
+    private askuiGot;
+    constructor(token?: string | undefined, customHeaders?: Record<string, string> | undefined, cookies?: Record<string, string>, proxyAgents?: {
+        http: http.Agent;
+        https: https.Agent;
+    } | undefined);
     private initHeaders;
     private injectHeadersAndCookies;
     post<T>(url: string, data: Record<string | number | symbol, unknown>): Promise<T>;

package/dist/cjs/utils/http/http-client-got.js

@@ -19,12 +19,14 @@ const lib_1 = require("../../lib");
 const credentials_1 = require("./credentials");
 const custom_errors_1 = require("./custom-errors");
 class HttpClientGot {
-    constructor(token, customHeaders, cookies = {}) {
+    constructor(token, customHeaders, cookies = {}, proxyAgents) {
         this.token = token;
         this.customHeaders = customHeaders;
         this.cookies = cookies;
+        this.proxyAgents = proxyAgents;
         this.headers = {};
         this.initHeaders(token, customHeaders);
+        this.askuiGot = got_1.default.extend(proxyAgents ? { agent: proxyAgents } : {});
     }
     initHeaders(token, customHeaders = {}) {
         const credentials = token ? new credentials_1.Credentials(token) : undefined;
@@ -40,7 +42,7 @@ class HttpClientGot {
     post(url, data) {
         return __awaiter(this, void 0, void 0, function* () {
             const options = this.injectHeadersAndCookies(url, { json: data, responseType: 'json', throwHttpErrors: false });
-            const { body, statusCode, headers } = yield got_1.default.post(url, options);
+            const { body, statusCode, headers } = yield this.askuiGot.post(url, options);
             if (headers['deprecation'] !== undefined) {
                 lib_1.logger.warn(headers['deprecation']);
             }
@@ -52,7 +54,7 @@ class HttpClientGot {
     }
     get(url, options = { responseType: 'json' }) {
         return __awaiter(this, void 0, void 0, function* () {
-            const response = yield got_1.default.get(url, this.injectHeadersAndCookies(url, options));
+            const response = yield this.askuiGot.get(url, this.injectHeadersAndCookies(url, options));
             return response.body;
         });
     }

package/dist/cjs/utils/proxy/proxy-builder.d.ts

@@ -0,0 +1,4 @@
+import { ProxyAgentArgs } from '../../shared/proxy-agent-args';
+export declare class ProxyImportError extends Error {
+}
+export declare function buildProxyAgentArgsFromEnvironment(): Promise<ProxyAgentArgs | undefined>;

package/dist/cjs/utils/proxy/proxy-builder.js

@@ -0,0 +1,67 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProxyAgentArgsFromEnvironment = exports.ProxyImportError = void 0;
+const logger_1 = require("../../lib/logger");
+class ProxyImportError extends Error {
+}
+exports.ProxyImportError = ProxyImportError;
+function dynmicImportHpagent() {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // eslint-disable-next-line import/no-extraneous-dependencies
+            return yield Promise.resolve().then(() => __importStar(require('hpagent')));
+        }
+        catch (err) {
+            throw new ProxyImportError('Can\'t find "hpagent" module to configure proxy! Please, install hpagent for proxy support with "npm install --save-dev hpagent".');
+        }
+    });
+}
+function buildProxyAgentArgsFromEnvironment() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const httpProxyUrl = process.env['HTTP_PROXY'];
+        const httpsProxyUrl = process.env['HTTPS_PROXY'];
+        if (httpProxyUrl === undefined && httpsProxyUrl === undefined) {
+            logger_1.logger.debug('No proxy defined. "HTTPS_PROXY" and "HTTP_PROXY" environment variables are empty.');
+            return undefined;
+        }
+        const hpagent = yield dynmicImportHpagent();
+        logger_1.logger.info('Using proxy! One of following environment variables are defined: "HTTPS_PROXY", "https_proxy", "HTTP_PROXY" and "http_proxy"');
+        return {
+            http: new hpagent.HttpProxyAgent({
+                proxy: (httpProxyUrl || httpsProxyUrl),
+            }),
+            https: new hpagent.HttpsProxyAgent({
+                proxy: (httpsProxyUrl || httpProxyUrl),
+            }),
+        };
+    });
+}
+exports.buildProxyAgentArgsFromEnvironment = buildProxyAgentArgsFromEnvironment;

package/dist/esm/execution/config-error.d.ts

@@ -0,0 +1,2 @@
+export declare class ConfigurationError extends Error {
+}

package/dist/esm/execution/config-error.js

@@ -0,0 +1,2 @@
+export class ConfigurationError extends Error {
+}

package/dist/esm/execution/dsl.d.ts

@@ -535,6 +535,114 @@ export declare class FluentFilters extends FluentBase {
     colored(color: COLOR): FluentFiltersOrRelations;
 }
 export declare class FluentFiltersOrRelations extends FluentFilters {
+    /**
+     * Logic or operator
+     *
+     * **Examples:**
+     * ```text
+     * scene 1
+     * --------------  ---------------
+     * |  button    |  |  icon       |
+     * --------------  ---------------
+     *
+     * scene 2
+     * --------------  ---------------
+     * |  button    |  |  text       |
+     * --------------  ---------------
+     *
+     * ```
+     * In case, that your reference element can have multiple values, in the following example, the element right of the button can be either icon or text.
+     * You can use **the `or()` relation**, so your teststep is valid for both scenes
+     * ```typescript
+     * const button = await aui.get().button().rightOf().icon().or().text().exec();
+     * console.log(button);
+     * ```
+     * Returns the same button for both cases
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'BUTTON',
+     *      text: 'button',
+     *      colors: [ 'red', 'black', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     *
+     * @return {FluentFilters}
+     */
+    or(): FluentFilters;
+    /**
+     * Logic and operator
+     *
+     * **Examples:**
+     * ```text
+     * example scene:
+     *  --------------------------   --------------------------
+     *  |  icon user colored black | |  icon  user colored red |
+     *  --------------------------   --------------------------
+     * ```
+     * ```typescript
+     * const icons = await aui.get().icon().withText('user').exec();
+     * console.log(icons);
+     * ```
+     * Using only the filter withText, the get command will return both icons because they share the same text
+     * ```text
+     * console output: [
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'black', 'black', 'black' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 1000,
+     *         ymin: 1010,
+     *         xmax: 1020,
+     *         ymax: 1030
+     *      }
+     *   },
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'red', 'red', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     * You can combine filters with **the `and()` relation** and specify exactly which icon you want
+     * ```typescript
+     * const icons = await aui.get().icon().withText('user').and().colored('red').exec()
+     * console.log(icons)
+     * ```
+     * The get command returns only the red icon although both icons have the same text
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'red', 'red', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     *
+     * @return {FluentFilters}
+     */
+    and(): FluentFilters;
     /**
      * Filters for an element inside another element.
      *
@@ -1194,6 +1302,114 @@ export declare class FluentFiltersCondition extends FluentBase {
     colored(color: COLOR): FluentFiltersOrRelationsCondition;
 }
 export declare class FluentFiltersOrRelationsCondition extends FluentFiltersCondition {
+    /**
+     * Logic or operator
+     *
+     * **Examples:**
+     * ```text
+     * scene 1
+     * --------------  ---------------
+     * |  button    |  |  icon       |
+     * --------------  ---------------
+     *
+     * scene 2
+     * --------------  ---------------
+     * |  button    |  |  text       |
+     * --------------  ---------------
+     *
+     * ```
+     * In case, that your reference element can have multiple values, in the following example, the element right of the button can be either icon or text.
+     * You can use **the `or()` relation**, so your teststep is valid for both scenes
+     * ```typescript
+     * const button = await aui.get().button().rightOf().icon().or().text().exec();
+     * console.log(button);
+     * ```
+     * Returns the same button for both cases
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'BUTTON',
+     *      text: 'button',
+     *      colors: [ 'red', 'black', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     *
+     * @return {FluentFiltersCondition}
+     */
+    or(): FluentFiltersCondition;
+    /**
+     * Logic and operator
+     *
+     * **Examples:**
+     * ```text
+     * example scene:
+     *  --------------------------   --------------------------
+     *  |  icon user colored black | |  icon  user colored red |
+     *  --------------------------   --------------------------
+     * ```
+     * ```typescript
+     * const icons = await aui.get().icon().withText('user').exec();
+     * console.log(icons);
+     * ```
+     * Using only the filter withText, the get command will return both icons because they share the same text
+     * ```text
+     * console output: [
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'black', 'black', 'black' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 1000,
+     *         ymin: 1010,
+     *         xmax: 1020,
+     *         ymax: 1030
+     *      }
+     *   },
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'red', 'red', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     * You can combine filters with **the `and()` relation** and specify exactly which icon you want
+     * ```typescript
+     * const icons = await aui.get().icon().withText('user').and().colored('red').exec()
+     * console.log(icons)
+     * ```
+     * The get command returns only the red icon although both icons have the same text
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'red', 'red', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     *
+     * @return {FluentFiltersCondition}
+     */
+    and(): FluentFiltersCondition;
     /**
      * Filters for an element inside another element.
      *
@@ -2078,6 +2294,114 @@ export declare class FluentFiltersGetter extends FluentBase {
     colored(color: COLOR): FluentFiltersOrRelationsGetter;
 }
 export declare class FluentFiltersOrRelationsGetter extends FluentFiltersGetter {
+    /**
+     * Logic or operator
+     *
+     * **Examples:**
+     * ```text
+     * scene 1
+     * --------------  ---------------
+     * |  button    |  |  icon       |
+     * --------------  ---------------
+     *
+     * scene 2
+     * --------------  ---------------
+     * |  button    |  |  text       |
+     * --------------  ---------------
+     *
+     * ```
+     * In case, that your reference element can have multiple values, in the following example, the element right of the button can be either icon or text.
+     * You can use **the `or()` relation**, so your teststep is valid for both scenes
+     * ```typescript
+     * const button = await aui.get().button().rightOf().icon().or().text().exec();
+     * console.log(button);
+     * ```
+     * Returns the same button for both cases
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'BUTTON',
+     *      text: 'button',
+     *      colors: [ 'red', 'black', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     *
+     * @return {FluentFiltersGetter}
+     */
+    or(): FluentFiltersGetter;
+    /**
+     * Logic and operator
+     *
+     * **Examples:**
+     * ```text
+     * example scene:
+     *  --------------------------   --------------------------
+     *  |  icon user colored black | |  icon  user colored red |
+     *  --------------------------   --------------------------
+     * ```
+     * ```typescript
+     * const icons = await aui.get().icon().withText('user').exec();
+     * console.log(icons);
+     * ```
+     * Using only the filter withText, the get command will return both icons because they share the same text
+     * ```text
+     * console output: [
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'black', 'black', 'black' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 1000,
+     *         ymin: 1010,
+     *         xmax: 1020,
+     *         ymax: 1030
+     *      }
+     *   },
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'red', 'red', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     * You can combine filters with **the `and()` relation** and specify exactly which icon you want
+     * ```typescript
+     * const icons = await aui.get().icon().withText('user').and().colored('red').exec()
+     * console.log(icons)
+     * ```
+     * The get command returns only the red icon although both icons have the same text
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'user',
+     *      colors: [ 'red', 'red', 'red' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 900,
+     *         ymin: 910,
+     *         xmax: 920,
+     *         ymax: 930
+     *      }
+     *   }
+     *  ]
+     * ```
+     *
+     * @return {FluentFiltersGetter}
+     */
+    and(): FluentFiltersGetter;
     /**
      * Filters for an element inside another element.
      *
@@ -2234,13 +2558,74 @@ export declare class FluentFiltersOrRelationsGetter extends FluentFiltersGetter
 }
 export declare abstract class Getter extends FluentCommand {
     /**
-     * Returns the filtered element
+     * Returns an array with all filtered elements.
+     * A detected element has the following properties:
+     * - `name` of the element
+     * - `text` content of element
+     * - `colors` of element
+     * - `bndbox`: location of element described with coordinates of a bounding box
+     * **Examples:**
+     * ```typescript
+     * const text = await aui.get().text().withText('Sign').exec();
+     * console.log(text);
+     * ```
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'TEXT',
+     *      text: 'Sign In',
+     *      colors: [ 'black', 'gray', 'gray' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 1128.2720982142857,
+     *         ymin: 160.21332310267857,
+     *         xmax: 1178.8204241071428,
+     *         ymax: 180.83512834821428
+     *      }
+     *  }
+     *  ]
+     * ```
      *
      * @return {FluentFiltersGetter}
      */
     get(): FluentFiltersGetter;
     /**
-     * Returns all detected elements
+     * Returns an array with all detected elements.
+     * A detected element has the following properties:
+     * - `name` of the element
+     * - `text` content of element
+     * - `colors` of element
+     * - `bndbox`: location of element described with coordinates of a bounding box
+     * **Examples:**
+     * ```typescript
+     * const detectedElements = await aui.getAll().exec();
+     * console.log(detectedElements);
+     * ```
+     * ```text
+     *  console output: [
+     *   DetectedElement {
+     *      name: 'TEXT',
+     *      text: 'Sign In',
+     *      colors: [ 'black', 'gray', 'gray' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 1128.2720982142857,
+     *         ymin: 160.21332310267857,
+     *         xmax: 1178.8204241071428,
+     *         ymax: 180.83512834821428
+     *      },
+     *   DetectedElement {
+     *      name: 'ICON',
+     *      text: 'search',
+     *      colors: [ 'black', 'red', 'gray' ],
+     *      bndbox: BoundingBox {
+     *         xmin: 250.8204241071428,
+     *         ymin: 300.21332310267857,
+     *         xmax: 450.6304241071428,
+     *         ymax: 950.47812834821428
+     *      },
+     *      ... 381 more items
+     *  }
+     *  ]
+     * ```
      *
      * @return {ExecGetter}
      */