@sap_oss/wdio-qmate-service 2.13.1 → 2.14.0

package/.eslintignore

@@ -1,3 +1,4 @@
 node_modules/
 results/
-lib/
+lib/
+packages/

package/docs/sections/features/selectors.md

@@ -2,7 +2,7 @@
 To perform any action on an element (e.g. clicking a button), you need to specify the element at which the action is being executed. This differs from the web technology you are using. Read the following instructions, depending on the UI technology of the application to be tested. 
 
 !!! info
-		Selectors are typically created using our Qmate Suite, but it is important to note that this tool is currently **only available for internal use at SAP**. For further information as **internal**, please refer to our official Qmate documentation.
+	Selectors are typically created using our Qmate Suite, but it is important to note that this tool is currently **only available for internal use at SAP**. For further information as **internal**, please refer to our official Qmate documentation.
 
 ## UI5
 
@@ -62,7 +62,7 @@ You have to define at least one property in ```elementProperties```. This could
 	}
 ```
 !!! tip
-		For most of the cases it will be sufficient to provide only the elementProperties. Qmate Suite will generate the minimal unique selector for you.
+	For most of the cases it will be sufficient to provide only the elementProperties. Qmate Suite will generate the minimal unique selector for you.
 
 
 ### Overview
@@ -81,10 +81,10 @@ The following properties apply to all selector types (elementProperties, ancesto
 | ``domProperties`` | the properties of the DOM | ``"domProperties": {"nodeName": "div", "class": "buttonNU* class2*", "id": "my*Id*"}`` | string: ``"property": "value"``, numeric: ``"property": 123``, boolean: ``"property": true`` | can be used if the UI5 Virtual DOM is not sufficient |
 
 !!! info
-		Wildcards are supported for all properties, aggregation and associations 
-		```js
-		"text": "my*text*"
-		```
+	Wildcards are supported for all properties, aggregation and associations 
+	```js
+	"text": "my*text*"
+	```
 
 ### Nested Properties
 In case you need to specify the element based on its surrounding, you can define nested properties. 
@@ -103,7 +103,7 @@ In case you need to specify the element based on its surrounding, you can define
 };
 ```
 !!! info
-		Nesting is enabled infinitely for *ancestorProperties*, *siblingProperties* and *descendantProperties*. Be cautious, the more level of nesting you add the slower your script will be.
+	Nesting is enabled infinitely for *ancestorProperties*, *siblingProperties* and *descendantProperties*. Be cautious, the more level of nesting you add the slower your script will be.
 
 ### Usage of Selectors
 For almost every UI5 action we provide, you can pass the selector directly to the function like:
@@ -155,7 +155,7 @@ clearly.
 $$("[<attr>='<attrValue>']");
 ```
 !!! warning
-		If there are more than one elements found, try to find another attribute or add some more attributes until you will find a single element (you can still pass an index to the reuse function if you are not able to find a unique selector).
+	If there are more than one elements found, try to find another attribute or add some more attributes until you will find a single element (you can still pass an index to the reuse function if you are not able to find a unique selector).
 
 
 ### Usage

package/lib/reuse/helper/elementResolving.d.ts

@@ -1,2 +1,3 @@
 import { Element } from "../../../@types/wdio";
 export declare function resolveCssSelectorOrElement(elementOrSelector: Element | string): Promise<Element>;
+export declare function resolveMobileSelectorOrElement(elementOrSelector: Element | string): Promise<Element>;

package/lib/reuse/helper/elementResolving.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCssSelectorOrElement = resolveCssSelectorOrElement;
+exports.resolveMobileSelectorOrElement = resolveMobileSelectorOrElement;
 async function resolveCssSelectorOrElement(elementOrSelector) {
     if (!elementOrSelector) {
         throw new Error("Please provide an element or a CSS selector as first argument.");
@@ -12,4 +13,15 @@ async function resolveCssSelectorOrElement(elementOrSelector) {
         return elementOrSelector;
     }
 }
+async function resolveMobileSelectorOrElement(elementOrSelector) {
+    if (!elementOrSelector) {
+        throw new Error("Please provide an element or a selector as first argument.");
+    }
+    if (typeof elementOrSelector === "string") {
+        return await $(elementOrSelector);
+    }
+    else {
+        return elementOrSelector;
+    }
+}
 //# sourceMappingURL=elementResolving.js.map

package/lib/reuse/helper/elementResolving.js.map

@@ -1 +1 @@
-{"version":3,"file":"elementResolving.js","sourceRoot":"","sources":["../../../src/reuse/helper/elementResolving.ts"],"names":[],"mappings":";;AAEA,kEAUC;AAVM,KAAK,UAAU,2BAA2B,CAAC,iBAAmC;IACnF,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,OAAO,iBAAiB,CAAC;IAC3B,CAAC;AACH,CAAC"}
+{"version":3,"file":"elementResolving.js","sourceRoot":"","sources":["../../../src/reuse/helper/elementResolving.ts"],"names":[],"mappings":";;AAEA,kEAUC;AAED,wEAUC;AAtBM,KAAK,UAAU,2BAA2B,CAAC,iBAAmC;IACnF,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,OAAO,iBAAiB,CAAC;IAC3B,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,8BAA8B,CAAC,iBAAmC;IACtF,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACpC,CAAC;SAAM,CAAC;QACN,OAAO,iBAAiB,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/lib/reuse/modules/mobile/device.d.ts

@@ -1,3 +1,10 @@
+type hideKeyboardStrategy = "pressKey" | "tapOutside" | "swipeDown" | "";
+declare const ORIENTATION: {
+    readonly LANDSCAPE: "LANDSCAPE";
+    readonly PORTRAIT: "PORTRAIT";
+    readonly UNKNOWN: "UNKNOWN";
+};
+type Orientation = (typeof ORIENTATION)[keyof typeof ORIENTATION];
 /**
  * @class device
  * @memberof mobile
@@ -5,25 +12,174 @@
 export declare class Device {
     private vlf;
     private ErrorHandler;
+    /**
+     * @function isValidPlatform
+     * @memberof mobile.device
+     * @description Check the mobile platform from the session's capabilities.
+     * @returns {boolean} Returns 'true' if the platform in the session's capabilities is either Android or iOS.
+     */
+    private isValidPlatform;
+    /**
+     * @function executionPlatform
+     * @memberof mobile.device
+     * @description Check the mobile platform from the session's capabilities.
+     * @returns {string} Return current execution platform in the session's capabilities.
+     */
+    private executionPlatform;
     /**
      * @function isAppInstalled
      * @memberof mobile.device
      * @description Check wether given package/bundle app is installed or not in the device.
-     * @param {string} packageIdOrBundleId - Android package Id, or iOS bundle Id.
-     * @returns {boolean} Returns true if specified app package/bundled installed in the device, or false.
-     * @example await mobile.device.isAppInstalled("com.google.android.apps.maps");
+     * @param {string} appPackageOrBundleId - Android package Id, or iOS bundle Id.
+     * @returns {boolean} Returns 'true' if specified app package/bundled installed in the device, or 'false'.
+     * @example
+     * await mobile.device.isAppInstalled("com.google.android.apps.maps");
+     * await mobile.device.isAppInstalled("com.apple.AppStore")
      */
-    isAppInstalled(packageIdOrBundleId: string): Promise<boolean>;
+    isAppInstalled(appPackageOrBundleId: string): Promise<boolean>;
     /**
      * @function installApp
      * @memberof mobile.device
      * @description Install the appropriate app based on the platform the test is being executed on.
      * @param {string} appPath - Path of the app(.apk, .ipa)
+     * @returns {Promise<void>}
      * @example
      * await mobile.device.installApp("/path/to/your/app.apk");
      * await mobile.device.installApp("/path/to/your/app.ipa");
      */
     installApp(appPath: string): Promise<void>;
+    /**
+     * @function switchToContext
+     * @memberof mobile.device
+     * @description Switch to the specified( WEBVIEW | NATIVE_APP ) context if available.
+     * @param {string} [targetContext='WEBVIEW'] The name of the target context.
+     * @param {number} [timeout=5000] Maximum time to wait for the web context to appear, milliseconds.
+     * @returns {Promise<boolean>} Returns 'true' if the context is successfully switched, otherwise 'false'.
+     * @example
+     * await mobile.device.switchToContext();
+     * await mobile.device.switchToContext("NATIVE_APP", 1000);
+     */
+    switchToContext(targetContext?: string, timeout?: number): Promise<boolean>;
+    /**
+     * @function getTargetContextIfAvailable
+     * @memberof mobile.device
+     * @description
+     * Returns the specified target context if available within a given timeout.
+     *
+     * This method retrieves the list of available contexts and determines if a context
+     * that matches the `targetContext` string is present. If the target context is found,
+     * it returns the context name; otherwise, it returns `null`.
+     *
+     * @param {string} [targetContext="WEBVIEW"] - The name of the target context to check for.
+     *   Common examples are "WEBVIEW" or "NATIVE_APP".
+     * @param {number} [timeout=5000] - The maximum time, in milliseconds, to wait for the target
+     *   context to become available.
+     * @returns {Promise<string | null>} - The name of the target context if found, or `null` if
+     *   the context is not available within the timeout.
+     * @example
+     * const context = await getTargetContextIfAvailable("WEBVIEW", 10000);
+     * const context = await getTargetContextIfAvailable("NATIVE_APP", 10000);
+     */
+    getTargetContextIfAvailable(targetContext?: string, timeout?: number): Promise<string | null>;
+    /**
+     * @function closeApplication
+     * @memberof mobile.device
+     * @description Close the currently active mobile application.
+     * @returns {Promise<void>}
+     * @example
+     * await mobile.device.closeApplication();
+     */
+    closeApplication(): Promise<void>;
+    /**
+     * @function queryAppState
+     * @memberof mobile.device
+     * @description Queries the state of the application (e.g., running, background, not installed) on the mobile device(Android or iOS).
+     * @param {string} appPackageOrBundleId - Package name (Android) or bundle ID (iOS) of the application.
+     * @returns {Promise<number>} - The app state:
+     *  0 - Not running,
+     *  1 - Not installed,
+     *  2 - Running in the background (not suspended),
+     *  3 - Running in the background (suspended),
+     *  4 - Running in the foreground.
+     * @example
+     * await mobile.device.queryAppState("com.google.android.apps.maps");
+     * await mobile.device.queryAppState("com.apple.AppStore");
+     */
+    queryAppState(appPackageOrBundleId: string): Promise<number>;
+    /**
+     * @function launchApp
+     * @memberof mobile.device
+     * @description Launches the app for both iOS and Android with a parameterized app identifier.
+     * @param {string} appPackageOrBundleId - The Android package name or iOS bundle ID of the application.
+     * @returns {Promise<void>} Resolves when the app is successfully launched.
+     * @example
+     * await mobile.device.launchApp("com.google.android.apps.maps");
+     * await mobile.device.launchApp("com.apple.AppStore");
+     */
+    launchApp(appPackageOrBundleId: string): Promise<void>;
+    /**
+     * @function switchToLandscapeOrientation
+     * @memberof mobile.device
+     * @description Switches the device orientation to landscape mode.
+     * @returns {Promise<void>} Resolves when the orientation is successfully switched.
+     * @example
+     * await mobile.device.switchToLandscapeOrientation();
+     */
+    switchToLandscapeOrientation(): Promise<void>;
+    /**
+     * @function switchToPortraitOrientation
+     * @memberof mobile.device
+     * @description Switches the device orientation to portrait mode.
+     * @returns {Promise<void>} Resolves when the orientation is successfully switched.
+     * @example
+     * await mobile.device.switchToPortraitOrientation();
+     */
+    switchToPortraitOrientation(): Promise<void>;
+    /**
+     * @function getCurrentOrientation
+     * @memberof mobile.device
+     * @description Returns the device current orientation (PORTRAIT or LANDSCAPE)
+     * @returns {Promise<Orientation>} The current device orientation.
+     * @example
+     * await mobile.device.getCurrentOrientation();
+     */
+    getCurrentOrientation(): Promise<Orientation>;
+    /**
+     * @function hideKeyboard
+     * @memberof mobile.device
+     * @description Hides the keyboard on both Android and iOS using specific strategies with timeout.
+     * @param {string} strategy - Strategy to use for hiding the keyboard ('pressKey', 'tapOutside', 'swipeDown').
+     * @param {string} key - Key to press if using the 'pressKey' strategy (e.g., 'Done', 'Enter').
+     * @param {number} keyCode - Key code for Android (optional).
+     * @param {number} [timeout=5000] - Timeout in milliseconds for retrying to hide the keyboard.
+     * @returns {Promise<void>}
+     * @example
+     * await mobile.device.hideKeyboard();
+     * await mobile.device.hideKeyboard('tapOutside');
+     * await mobile.device.hideKeyboard('swipeDown');
+     * //Android only, Sends a specific key code, like 66 for "Enter."
+     * await mobile.device.hideKeyboard('pressKey', undefined, 66);
+     * await mobile.device.hideKeyboard('pressKey', 'Done');
+     */
+    hideKeyboard(strategy?: hideKeyboardStrategy, key?: string, keyCode?: number, timeout?: number): Promise<void>;
+    /**
+     * @function isKeyboardVisible
+     * @memberof mobile.device
+     * @description Checks if the keyboard is visible or not on the mobile device.
+     * @returns {Promise<boolean>} Returns 'true' if the keyboard is visible on the mobile view.
+     * @example
+     * await mobile.device.isKeyboardVisible();
+     */
+    isKeyboardVisible(): Promise<boolean>;
+    /**
+     * @function isPlatformSupported
+     * @memberof mobile.device
+     * @description Determine if the current platform is supported, if the current device platform is either Android or iOS.
+     * @returns {Promise<boolean>} If neither Android nor iOS is detected (e.g., Windows, Linux, or web), the condition evaluates to false
+     * @example
+     * await mobile.device.isPlatformSupported();
+     */
+    isPlatformSupported(): Promise<boolean>;
 }
 declare const _default: Device;
 export default _default;