@sap_oss/wdio-qmate-service 1.0.0 → 1.0.2

package/docs/gettingStarted/setup.md

@@ -4,5 +4,5 @@ Make sure [Node.js](https://nodejs.org/en/download/) is installed on your comput
 ## Installation
 To install the latest version of the service, simply execute the following command:
 ```bash
-npm install @wdio/qmate-service
-```
+npm install @sap_oss/wdio-qmate-service
+```

package/docs/index.md

@@ -1,4 +1,4 @@
-# Qmate Service
+# **Qmate** Service
 **Qmate Service** is a custom [WebdriverIO](https://webdriver.io/) service built in TypeScript for testing web applications and APIs.
 
 ## Main features

package/docs/sections/bestPractices/authentication.md

@@ -0,0 +1,151 @@
+# Best Practices - Authentication
+For the standard Fiori and Cloud login Pages, we provide some configuration parameters and reuse methods to enable you an easy way of system authentication.
+
+There are two different approaches to log into the system:
+
+- [Via reuse methods](#via-reuse-methods) (recommended)
+- [Via configuration file](#via-configuration-file)
+
+Which way to choose depends on your needs and preferences. If you are testing a scenario which goes through various systems (especially non UI5 systems) it is not recommended/possible to use a global authentication via the configuration file. If there is only one login during the script execution, it is up to you, to do the authentication via the configuration file. 
+!!! info
+        For consistency reasons we recommend to use the login via reuse methods only.
+
+
+## Via reuse methods
+The other way of system authentication, is to use the specific [reuse method](https://sap.github.io/wdio-qmate-service/doc/#ui5.session). 
+This is commonly recommended, especially if you are switching between multiple users or systems during the test execution. 
+With this approach, you handle the login within a step of your script/s. 
+The benefit of this approach is, to have more control over the login as an actual step inside your test process. 
+With that, you are able to use the login/logout multiple times during the test execution if you need to switch users or systems during runtime.
+
+You can use one of the following methods:
+
+=== "Generic Login"
+    There is a generic login function which can be used for both types of forms (fiori & sap-cloud) to authenticate. This function will automatically determine the right login form and call the proper function.
+
+    ```js
+    it("Step 01: login generic", async function () {
+        await ui5.session.login("JOHNDOE", "abc123");
+    });
+    ```
+
+=== "Fiori Login"
+    Use this configuration for the [Fiori Login Screen](#Fiori-Login-Screen).
+    Define the step (on top of your script) and pass at least a valid user to the method. 
+    If the password for this user differs from the default password *Welcome1!*, you can additionally pass the password as second argument.
+
+    ```js
+    it("Step 01: login fiori", async function () {
+        await ui5.session.loginFiori("JOHNDOE", "abc123");
+    });
+    ```
+
+=== "SAP Cloud Login"
+    Use this configuration for the [SAP Cloud Login Screen](#SAP-Cloud-Login-Screen).
+    Define the step (on top of your script) and pass at least a valid user to the method. 
+    If the password for this user differs from the default password *Welcome1!*, you can additionally pass the password as second argument.
+
+    ```js
+    it("Step 01: login sap cloud", async function () {
+        await ui5.session.loginSapCloud("JOHNDOE", "abc123");
+    });
+    ```
+
+=== "Custom Login"
+    If you want to define your own custom form, you can use the following method. 
+
+    Define the step (on top of your script) and pass the ```username```, ```password```, ```usernameFieldSelector```, ```passwordFieldSelector``` 
+    and ```logonButtonSelector```. Therefore, you need to define the CSS selectors of the corresponding elements.
+
+    ```js
+    it("Step 01: login Custom", async function () {
+        const username = "JOHNDOE";
+        const password = "Greetings1!";
+        const usernameSelector = "#USERNAME_BLOCK input";
+        const passwordSelector = "#PASSWORD_BLOCK input";
+        const loginButtonSelector = "#LOGIN_LINK";
+        await ui5.session.loginCustom(username, password, usernameSelector, passwordSelector, loginButtonSelector);
+    });
+    ```
+
+!!! tip
+        You can disable the login centrally without touching your specs by setting the `formType` to `"skip"` inside your configuration file.
+
+## Via configuration file
+Inside the *conf.js* file You can specify how the script will automatically log into the system. This will only be executed once before the first script gets executed. Hence, we recommend to use this only if you are not switching between multiple users or systems during the test execution.
+
+There are multiple options, based on the login screen to set the ```formType``` of the [Configuration](<todo-add-configuration-md>).
+
+=== "Fiori Login"
+    Use this configuration for the [Fiori Login Screen](#Fiori-Login-Screen).
+    You only need to specify the ```username``` and ```password```.
+    ```js
+    auth: {
+        formType: "fiori-form",
+        username: "JOHNDOE",
+        password: "Greetings1!"
+    },
+    ```
+
+=== "SAP Cloud Login"
+    Use this configuration for the [SAP Cloud Login Screen](#SAP-Cloud-Login-Screen).
+    You only need to specify the ```username``` and ```password```.
+    ```js
+    auth: {
+        formType: "sapcloud-form",
+        username: "JOHNDOE",
+        password: "Greetings1!"
+    },
+    ```
+
+=== "Others"
+    The following options for ```formType``` are also available. You need to specify the ```username``` and ```password``` for this configuration.
+
+    - ```XSA-form```
+    - ```POT-form```
+    - ```MIA-form```
+    - ```UI5-Form```
+
+=== "Custom Login"
+    If you want to define your own custom form, you can use the following configuration.
+    Additionally to the ```username``` and ```password```, you need to specify the ```usernameFieldSelector```, ```passwordFieldSelector``` and ```logonButtonSelector```. Therefore set the CSS selectors of the corresponding elements.
+
+    ```js
+    auth: {
+        formType: "custom-form",
+        username: "JOHNDOE",
+        password: "Greetings1!",
+        usernameFieldSelector: "#USERNAME_BLOCK input",
+        passwordFieldSelector: "#PASSWORD_BLOCK input",
+        logonButtonSelector: "#LOGIN_LINK"
+    },
+    ```
+
+=== "Skip Login"
+    Use this configuration to skip the login and logout inside the specs.
+    ```js
+    auth: {
+        formType: "skip"
+    },
+    ```
+
+## Logout
+To logout from a S/4 system, please use the following method.
+```js
+it("Step XX: logout", async function () {
+    await ui5.session.logout();
+});
+```
+
+!!! info
+        Please note, if `formType` is set to `"skip"`, the logout will be skipped as well.
+
+## Finding the right login form
+Please use the screenshots to find the proper login form.
+=== "Fiori Login Screen"
+    ![fiori-form](../../sources/images/fiori_form.PNG)
+
+=== "SAP Cloud Login Screen"
+    ![sapcloud-form](../../sources/images/sapCloud_form.PNG)
+
+

package/docs/sections/bestPractices/dataHandling.md

@@ -0,0 +1,61 @@
+# Best Practices - Data Handling
+> Related Topics: [Data Handling](../features/dataHandling.md) | [Advanced Data Handling](../features/advancedDataHandling.md)
+
+- Always decouple the data from the spec. The maintenance of data will become very handy also more transparent. 
+
+- Store your data files inside the *data* folder.
+
+- Create a separate *.json* file for every script. Unless specifically needed by the test scenario to use data from multiple files, it is recommended to keep things simple, and use only one import prefix (that maps to a JSON file) per script.
+
+- Name the file exactly like the script which the data belongs to.
+
+- Structure your data according to the related section of the UI.
+
+- To pass data between different specs, use the [*references.json*](../features/dataHandling.md#reference_data) file and [group](<todo-add-link-to-config-grouped-and-file>) the specs inside the config.
+
+- Use meaningful key names for import and export parameters, and use meaningful names for data folders, subfolders, and *JSON* files.
+  ```js title="config.js"
+  params: {
+  
+    import: {                         
+      purchaseOrder: "./data/purchaseOrder.json",
+      ordersFolder: "./data/orders"
+    },
+    export: {
+      supplierInvoice: "./data/export/supplierInvoice.json"
+    }
+  
+  },
+  ```
+
+- Structure your data.
+  ```json title="data.json"
+  {
+    "session": {
+      "username": "JOHNDOE",
+      "password": "abc123!!"
+    },
+    "userData": {
+      "firstName": "John",
+      "lastName":  "Doe",
+      "address": {
+        "street":   "Main Road",
+        "number":   "42",
+        "zipCode":  "12345",
+        "city":     "Metropolis"
+      }
+    }
+  }
+  ```
+
+- You can check if data has been imported correctly by using assertions before accessing it. 
+  ```js
+  const data = browser.config.params.import.yourPrefixSpecName;
+  // make an assertion to ensure data was loaded
+  await common.assertion.expectDefined(data);
+  await common.assertion.expectDefined(data.email);
+  ```
+
+(Only for data export)
+
+- Each script should write to different export files, unless the test scenario needs to do otherwise. If different scripts write to same export file, make sure to merge and not overwrite the export data.

package/docs/sections/bestPractices/selectors.md

@@ -0,0 +1,44 @@
+# Best Practices - Selectors
+> Related Topics: [Selectors](../features/selectors.md)
+
+- Try to avoid text dependencies in selectors. Texts are more likely to change on the UI and if you want to enable your specs for LAT (Language Acceptance Tests) it will break your test. 
+
+    !!! danger "avoid"
+        === "UI5"
+            ```js
+            const selector = {
+                "elementProperties": {
+                    "viewName": "sap.suite.ui.generic.template.ObjectPage.view.Details",
+                    "metadata": "sap.m.Button",
+                    "text": "Create"
+                }
+            };
+            ```
+
+        === "non UI5"
+            ```js
+            const saveButton = await nonUi5.element.getElementByCss("BUTTON[text='Save']");
+            ``` 
+
+- Avoid *xPath* in non_ui5 selectors: *xPath* is a complex construct which includes multiple nodes. Due to the intransparent dependencies of other elements it may brake your test in case of any change of the corresponding elements. 
+
+    !!! danger "avoid"
+        ```js
+        const elem1 = await nonUi5.element.getElementByXPath(".//*[@role='toolbar']/span[3]/span[2]/input");
+        ``` 
+
+- Avoid screen size specific and style dependent attributes of elements.  
+
+    !!! danger "avoid"
+        ```JavaScript
+        [@style='width:100%;']
+        ```
+
+- Refrain from building manual xPaths at all costs. Indexes can change very easy if the path changes etc. 
+
+    !!! danger "avoid"
+        ```JavaScript
+        const SupplierPartyId = childrenArray[5].getElementsByTagName("SPAN")[1].innerText;
+        ```
+
+- Always check for a stable IDs or for other unique properties/attributes. Even if spotlight doesn't offer it to you.

package/docs/sections/features/advancedDataHandling.md

@@ -0,0 +1,252 @@
+Data can be imported from *JSON* files and used in the tests. Data obtained during the test run can also be saved or exported to *JSON* files.
+
+## Importing Data
+
+### Test configuration for import
+Data to be imported may be in a specific *JSON* file, or in a directory, and sub-directories under that directory. In the *config* file, under ``params`` add ``import``, and within it specify the import data.
+```js title="config.js"
+params: {
+  
+  import: {                         
+    myFolder1: "./data/my/folder/data/<systemName>",
+    myFolder2: "data/another/folder/data/anotherFolder",
+    myFolder3: "C:/Users/C1234567/data/testFolder",
+    yourPrefixSpecName: "./data/my/folder/data/<systemName>/data.json",
+    uiUser: "./data/my/folder/data/<systemName>/webUser.json",
+  }
+
+},
+```
+
+!!! info
+    The folders or *JSON* files are specified as key-value pair. In this sample, ``yourPrefixSpecName`` is the key which points to a *JSON* file ``./data/my/folder/data/qs9/data.json``. Similarly, the key ``myFolder2`` points to a folder ``data/another/folder/data/anotherFolder``.
+
+
+!!! tip
+    File paths may be relative or absolute. If relative, they are resolved relative to the config file directory.
+
+
+
+### Data import from *JSON* file
+Data from a *JSON* file will be added under the specified key. Data from ``./data/my/folder/data/<systemName>/data.json`` will be available in ``browser.config.params.import.yourPrefixSpecName``. 
+
+Similarly data from ``./data/my/folder/data/<systemName>/webUser.json`` will be available in ``browser.config.params.import.uiUser``.
+
+```js title="config.js"
+params: {
+
+  import: {               
+    yourPrefixSpecName: "./data/my/folder/data/<systemName>/data.json",          
+    uiUser: "./data/my/folder/data/<systemName>/webUser.json",
+  }
+
+},
+```
+
+Let's assume the file *./data/my/folder/data/<systemName>/data.json* has the following data:
+```json title="data.json"
+{
+  "name": "Joe Doe",
+  "email": "joe.doe@example.com",
+  "telephone": "333-000-111-222",
+  "amount": 4.79,
+  "website": "http://www.userdataexport.test"
+}
+```
+Since ``yourPrefixSpecName`` is the key, to access the ``email`` value in the test spec, we use
+``browser.config.params.import.yourPrefixSpecName.email``.
+
+```js
+// load entire data from "./data/my/folder/data/<systemName>/data.json"
+const userData = browser.config.params.import.yourPrefixSpecName;
+
+// make an assertion to ensure data was loaded
+await common.assertion.expectDefined(userData);
+await common.assertion.expectDefined(userData.email);
+
+// enter data to input field
+await ui5.userInteraction.fill(emailSelector, userData.email);
+
+// define and enter specific data value
+const email = browser.config.params.import.yourPrefixSpecName.email;
+await ui5.userInteraction.fill(emailSelector, email);
+```
+
+### Data import from folders and subfolders
+```js title="config.js"
+params: {
+
+  import: {                         
+    myFolder1: "./data/my/folder/data/<systemName>",
+    myFolder2: "./data/another/folder/data/anotherFolder",
+  }
+
+},
+```
+Let us assume that the folders have the following files:
+```code
+./data/my/folder/data/<systemName>/data.json
+./data/my/folder/data/<systemName>/purchaseRequisition.json
+./data/another/folder/data/anotherFolder/purchaseRequisition_HI.json
+./data/another/folder/data/anotherFolder/purchaseOrders/ServicePurchaseOrder.json
+./data/another/folder/data/anotherFolder/purchaseOrders/LimitPurchaseOrder.json
+./data/another/folder/data/anotherFolder/my-po-set/Limit-Purchase-Order.json
+./data/another/folder/data/anotherFolder/my-po-set/ServicePurchaseOrder.2Items.json
+```
+
+- Data in *./data/my/folder/data/<systemName>/data.json* can be accessed using the folder key ``myFolder1``, and the file name prefix, which is ``data`` in this case.
+  ```js
+  const myData = browser.config.params.import.myFolder1.data;
+  ```
+
+- Data in *./data/my/folder/data/<systemName>/purchaseRequisition.json* can be accessed using the folder key ``myFolder1``, and
+the file name prefix ``purchaseRequisition``.
+  ```js
+  const prData = browser.config.params.import.myFolder1.purchaseRequisition;
+  ```
+
+- Similarly data in *data/another/folder/data/anotherFolder* can be accessed using the folder key ``myFolder2``, subfolder name and file prefix as keys.
+  ```js title="data/another/folder/data/anotherFolder/purchaseRequisition_HI.json"
+  const prDataHI = browser.config.params.import.myFolder2.purchaseRequisition_HI;
+  ```
+  ```js title="data/another/folder/data/anotherFolder/purchaseOrders/ServicePurchaseOrder.json"
+  const servicePO = browser.config.params.import.myFolder2.purchaseOrders.ServicePurchaseOrder;
+  ```
+  ```js title="data/another/folder/data/anotherFolder/purchaseOrders/LimitPurchaseOrder.json"
+  const limitPO = browser.config.params.import.myFolder2.purchaseOrders.LimitPurchaseOrder;
+  ```
+
+!!! tip
+    It is recommended that the subfolder names and *JSON* file names used to import data do not have special characters. 
+
+If there are special characters in the file name or subfolder name, then the dot notation can't be used. In that case, you can use the following syntax:
+```js title="data/another/folder/data/anotherFolder/my-po-set/Limit-Purchase-Order.json"
+const limitPO = browser.config.params.import.myFolder2["my-po-set"]["Limit-Purchase-Order"];
+```
+```js title="data/another/folder/data/anotherFolder/my-po-set/ServicePurchaseOrder.2Items.json"
+const servicePO = browser.config.params.import.myFolder2["my-po-set"]["ServicePurchaseOrder.2Items"];
+```
+
+!!! warning
+    Qmate will not fail if import files and folders are missing, not readable, or have an invalid *JSON*. In such cases, warnings are logged on the console, and the data corresponding to those files and folders will remain undefined.
+
+
+## Exporting Data
+
+### Test configuration for export
+Data can be exported persistently to one or more files. In the sample configuration file under ``params``, add ``export`` with a list of file names as shown below. 
+```js title="config.js"
+params: {
+
+  export: {          
+    exportData: "./data/my/folder/path/in/exportFile.json",
+    exportMoreData: "./data/my/folder/path/in/moreDataFile.json",
+    exportArrayData: "./data/my/folder/path/in/arrayDataFile.json"
+  }
+
+},
+```
+
+### Exporting data to *JSON* file
+The data in ``browser.config.params.export`` is written to output files at the end of the test run. The export file is created or overwritten if already present. Any intermediate folders are also created if necessary.
+```js
+it("Step 01: export data to 'exportData' file", async function () {
+  // exportData: "./data/my/folder/path/in/exportFile.json",
+  browser.config.params.export.exportData = { 
+    name: "joe", 
+    description: "exported into exportFile.json" 
+  };
+});
+
+it("Step 02: export data to 'exportMoreData' file", async function () {
+  // exportMoreData: "./data/my/folder/path/in/moreDataFile.json",
+  browser.config.params.export.exportMoreData = { 
+    name: "jack", 
+    description: "exported into moreDataFile.json" 
+  };
+});
+
+it("Step 03: export array data to 'exportArrayData' file", async function () {
+  // exportArrayData: "./data/my/folder/path/in/arrayDataFile.json",
+  browser.config.params.export.exportArrayData = [
+    {
+      itemNo: "1",
+      description: "exported into arrayDataFile.json",
+      type: "material"
+    },
+    {
+      itemNo: "2",
+      description: "Service item",
+      type: "service"
+    }
+  ];
+  await common.assertion.expectEqual(Array.isArray(browser.config.params.export.exportArrayData), true);
+
+  // file "./data/my/folder/path/in/arrayDataFile.json" will have the array data
+  // check manually after test run is complete
+});
+
+```
+At the end of the test run, the file *./data/my/folder/path/in/exportFile.json* will look like: 
+```json
+{ 
+  name: "joe",
+  description: "exported into exportFile.json"
+}
+```
+
+File *./data/my/folder/path/in/moreDataFile.json* will look like: 
+```json
+{ 
+  name: "jack", 
+  description: "exported into moreDataFile.json" 
+}
+```
+
+File *./data/my/folder/path/in/moreDataFile.json* will look like: 
+```json
+[
+  {
+    itemNo: "1",
+    description: "exported into arrayDataFile.json",
+    type: "material"
+  },
+  {
+    itemNo: "2",
+    description: "Service item",
+    type: "service"
+  }
+]
+```
+
+!!! warning
+    If you are adding export data to the same export key, make sure you don't overwrite previous data.
+
+    ```js
+    // browser.config.params.export.exportData has data assigned to it from previous steps
+    browser.config.params.export.exportData["name"] = "joe";
+
+    // or if browser.config.params.export.exportData is an Array
+    if(Array.isArray(browser.config.params.export.exportData)) {
+        // add an element to an array
+        browser.config.params.export.exportData.push({name: "Joe"});
+    }
+    ```
+
+!!! info
+    If there is no data assigned to an export key, then the export file corresponding to that key will be empty. Doing any of the following things will create an empty *JSON* file.
+
+    ```js
+    // "./data/my/folder/path/in/exportFile.json" will be a blank file at end of test run
+    browser.config.params.export.exportData = null;
+    // or
+    browser.config.params.export.exportData = {};
+    // or
+    browser.config.params.export.exportData = [];
+    ```
+
+### Parallel test runs and exporting data
+If tests are running in parallel, there will be multiple browser instances and each test run will have it's own browser instance. If these parallel instances write to the same export file, then the export data from parallel test instances is merged together and written out to the file.
+
+!!! warning
+    This module does not fail if export files are not writable or if the export folder is inaccessible. In such cases, warnings are logged on the console, and export data will not get written out.