Merge remote-tracking branch 'wdi5/main' into feat/basic-auth-extension

.github/workflows/publish-btp.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
           cache: "npm"
           cache-dependency-path: "**/package-lock.json"
           registry-url: https://registry.npmjs.org/
@@ -29,18 +29,21 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: mtar
-          path: |
-            examples/ui5-ts-app/mta_archives/ui5-approuter_1.0.0.mtar
+          path: examples/ui5-ts-app/mta_archives/ui5-approuter_1.0.0.mtar
 
   publish-sample-ts-app-to-btp:
     needs: build-sample-ts-app
     runs-on: ubuntu-latest
-    container: ppiper/cf-cli
     steps:
       - name: get mtar
         uses: actions/download-artifact@v3
         with:
           name: mtar
-      - run: |
-          cf login -a https://api.cf.eu20.hana.ondemand.com -u ${{secrets.BTP_LOGIN}} -p ${{secrets.BTP_PASSWORD}} -o "${{secrets.BTP_ORG}}" -s ${{secrets.BTP_SPACE}}
-          cf deploy examples/ui5-ts-app/mta_archives/ui5-approuter_1.0.0.mtar -f
+      - uses: elliottpope/cloudfoundry-cli-action
+        with:
+          CF_API: https://api.cf.eu20.hana.ondemand.com
+          USERNAME: ${{ secrets.BTP_LOGIN }}
+          PASSWORD: ${{ secrets.BTP_PASSWORD }}
+          ORG: ${{secrets.BTP_ORG}}
+          SPACE: ${{secrets.BTP_SPACE}}
+          COMMAND: deploy examples/ui5-ts-app/mta_archives/ui5-approuter_1.0.0.mtar -f

.github/workflows/wdi5-tests_js-app.yml

@@ -61,6 +61,10 @@ jobs:
       - name: build
         run: npm run build
 
-      # run wdi5 tests within app(s)
-      - name: test js-app
+      # run wdi5 tests within CJS app/env
+      - name: test cjs js-app
         run: npm run test-h:js-app
+
+      # run wdi5 tests within ESM app/env
+      - name: test esm js-app
+        run: npm run test-h:js-app:esm

.vscode/settings.json

@@ -4,5 +4,6 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
   "javascript.preferences.importModuleSpecifierEnding": "js",
-  "typescript.preferences.importModuleSpecifierEnding": "js"
+  "typescript.preferences.importModuleSpecifierEnding": "js",
+  "search.useIgnoreFiles": true
 }

client-side-js/fireEvent.cjs

@@ -17,7 +17,7 @@ async function clientSide_fireEvent(webElement, eventName, oOptions, browserInst
                             }
                             oControl.fireEvent(eventName, oOptions)
                             // convert to boolean
-                            done({ status: 0, resuklt: true })
+                            done({ status: 0, result: true })
                         } catch (e) {
                             window.wdi5.errorHandling.bind(this, done)
                         }

docs/migration.md

@@ -0,0 +1,119 @@
+# Migrate from a previous version
+
+## from `^1` to `^2`
+
+Version >= 2 of `wdi5` is WebdriverIO v8 compatible. This entails a move to ESM as primary module, with CJS compatibility ensured.
+
+### no more explicit browser driver needed!
+
+WebdriverIO now automates downloading and starting the appropriate driver corresponding to the `browser` specified in the `capabilites` section of the config file (see also https://webdriver.io/blog/2023/07/31/driver-management):
+
+```diff
+- services: ["chromedriver", "ui5"],
++ services: ["ui5"],
+ //...
+ capabilities: [{
+    browserName: "chrome"
+ }]
+```
+
+Setting `browserName: "chrome"` is enough to tell `wdi5`/`wdio` to run the tests with the stable version of Chrome - no more `"chromedriver"` needed in the `services`!  
+To switch to Safari on macOS, following the above example is as easy as changing the `browserName`:
+
+```js
+// wdio.conf.js
+  services: ["ui5"],
+  //...
+  capabilities: [{
+     browserName: "safari"
+  }]
+```
+
+?> this is an _optional_ change - `wdi5` will continue to work also with explicitly denoting the browser driver in `services`!
+
+### check file system location reference of spec files in wdio.config.(j|t)s
+
+directory references start from the directory the config file is in now, not from `cwd` or project root:
+
+**Example**: `wdi5` config file is located adjacent to `webapp`:
+
+```console
+.
+├── e2e-test-config
+│   └── wdi5.conf.js
+# ...
+└── webapp
+    ├── test
+    │   └── e2e
+    │       ├── aggregation.test.js
+    │       ├── allControls.test.js
+    │       ├── allControlsForce.test.js
+    │       ├── basic.test.js
+# ...
+```
+
+Config file change:
+
+```diff
+const config = {
+- specs: [join("webapp", "test", "e2e", "ui5-late.test.js")],
++ specs: [join("..", "webapp", "test", "e2e", "ui5-late.test.js")],
+  // ...
+}
+```
+
+**Example**: `wdi5` config file is located in the same directory as the tests:
+
+```console
+.
+├── regular-journey.test.ts
+├── testlib-journey.test.ts
+└── wdio.conf.ts
+```
+
+Config file change:
+
+```diff
+export const config: wdi5Config = {
+- specs: ["./test/e2e/workzone/*.test.ts"],
++ specs: ["./*.test.ts"],
+  // ...
+}
+```
+
+### usage of devtools automation protocol
+
+Now requires using the `devtools` package (which is now a dependency of `wdi5`) and explicit configuration in the `*.conf.(j|t)s`-file:
+
+```diff
+ export const config: wdi5Config = {
+     baseUrl: "https://your-app",
+     services: ["ui5"],
+     specs: [resolve("test/e2e/Protocol.test.ts")],
++    automationProtocol: "devtools",
+     capabilities: [
+      {
+        //...
+      }
+     ]
+ }
+```
+
+### use `wdi5` as ESM module
+
+With `wdi5` v2, it is possible to write tests in an ESM module environment (see [/examples/ui5-js-app-esm](https://github.com/ui5-community/wdi5/blob/main/examples/ui5-js-app-esm)). The `describe` and `it` syntax remains the same as in an CJS environment. The major difference is in the way `wdi5` and third party modules are imported in ESM-style JavaScript files.
+
+Sample excerpt:
+
+```js
+// file: basic.test.js
+import { wdi5 } from "wdio-ui5-service" // <--
+
+describe("...", () => {
+    it("...", () => {
+        await browser.asControl(selector).someMethod()
+        wdi5.getLogger("esm!").log("Hello ESM World!")
+    })
+})
+
+```

examples/ui5-js-app-esm/jsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "types": [
+      "node",
+      "@openui5/types",
+      "@wdio/globals/types",
+      "@wdio/mocha-framework",
+      "wdio-ui5-service/esm",
+      "expect-webdriverio"
+    ]
+  }
+}

examples/ui5-js-app-esm/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "ui5-app-esm",
+  "version": "0.8.15-notimportant",
+  "private": true,
+  "description": "sample ESM ui5 app for testing wdi5",
+  "license": "UNLICENSED",
+  "author": "j&s-soft GmbH",
+  "main": "webapp/index.html",
+  "type": "module",
+  "scripts": {
+    "start": "ui5 serve -p 8082",
+    "wdi5": "wdio ./webapp/test/e2e/wdio.conf.js"
+  },
+  "devDependencies": {
+    "@ui5/cli": "^3",
+    "@types/sinon": "^10.0.16",
+    "sinon": "^15.2.0",
+    "@wdio/cli": "^8",
+    "@wdio/local-runner": "^8",
+    "@wdio/mocha-framework": "^8",
+    "@wdio/spec-reporter": "^8",
+    "ui5-middleware-simpleproxy": "latest",
+    "wdio-ui5-service": "*"
+  },
+  "dependencies": {
+    "@wdio/sauce-service": "^8"
+  }
+}

examples/ui5-js-app-esm/ui5.yaml

@@ -0,0 +1,12 @@
+specVersion: "2.0"
+metadata:
+  name: ui5-app
+type: application
+server:
+  customMiddleware:
+    - name: ui5-middleware-simpleproxy
+      afterMiddleware: compression
+      mountPath: /V2
+      configuration:
+        baseUri: "https://services.odata.org/V2"
+        strictSSL: false

examples/ui5-js-app-esm/webapp/Component.js

@@ -0,0 +1,33 @@
+sap.ui.define(
+    [
+        "sap/ui/core/UIComponent",
+        "sap/ui/Device",
+        "test/Sample/model/models",
+        "sap/ui/core/ComponentSupport" // make sure to include the ComponentSupport in the bundle
+    ],
+    function (UIComponent, Device, models) {
+        "use strict"
+
+        return UIComponent.extend("test.Sample.Component", {
+            metadata: {
+                manifest: "json"
+            },
+
+            /**
+             * The component is initialized by UI5 automatically during the startup of the app and calls the init method once.
+             * @public
+             * @override
+             */
+            init: function () {
+                // call the base component's init function
+                UIComponent.prototype.init.apply(this, arguments)
+
+                // enable routing
+                this.getRouter().initialize()
+
+                // set the device model
+                this.setModel(models.createDeviceModel(), "device")
+            }
+        })
+    }
+)

examples/ui5-js-app-esm/webapp/controller/App.controller.js

@@ -0,0 +1,5 @@
+sap.ui.define(["test/Sample/controller/BaseController"], function (Controller) {
+    return Controller.extend("test.Sample.controller.App", {
+        onInit: function () {}
+    })
+})

examples/ui5-js-app-esm/webapp/controller/BaseController.js

@@ -0,0 +1,63 @@
+sap.ui.define(
+    ["sap/ui/core/mvc/Controller", "sap/ui/core/routing/History"],
+    /**
+     * @param {typeof sap.ui.core.mvc.Controller} Controller
+     * @param {typeof sap.ui.core.routing.History} History
+     * @yields {typeof sap.ui.core.mvc.Controller}
+     */
+    function (Controller, History) {
+        "use strict"
+
+        return Controller.extend("test.Sample.controller.BaseController", {
+            /**
+             * inits on controller instantiation
+             */
+            onInit: function () {},
+
+            /**
+             * Convenience method for accessing the router in every controller of the application.
+             * @public
+             * @returns {sap.ui.core.routing.Router} the router for this component
+             */
+            getRouter: function () {
+                return this.getOwnerComponent().getRouter()
+            },
+
+            /**
+             * Convenience method for getting the view model by name in every controller of the application.
+             * @public
+             * @param {string} sName the model name
+             * @returns {sap.ui.model.Model} the model instance
+             */
+            getModel: function (sName) {
+                return this.getView().getModel(sName)
+            },
+
+            /**
+             * Convenience method for getting the resource bundle.
+             * @public
+             * @returns {sap.ui.model.resource.ResourceModel} the resourceModel of the component
+             */
+            getResourceBundle: function () {
+                return this.getOwnerComponent().getModel("i18n").getResourceBundle()
+            },
+
+            /**
+             * Event handler for navigating back.
+             * It there is a history entry we go one step back in the browser history
+             * If not, it will replace the current entry of the browser history with the master route.
+             * @public
+             */
+            onNavBack: function () {
+                const sPreviousHash = History.getInstance().getPreviousHash()
+
+                if (sPreviousHash !== undefined) {
+                    // eslint-disable-next-line
+                    history.go(-1)
+                } else {
+                    this.getRouter().navTo("RouteMain", {}, true)
+                }
+            }
+        })
+    }
+)