feat: support cap basic auth

intended for local dev!
closes #502

Author: ChristophMarotzke

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "examples/cap-bookshop-wdi5"]
+	path = examples/cap-bookshop-wdi5
+	url = [email protected]:SAP-samples/cap-bookshop-wdi5.git
+	branch = wdi5-tests

client-side-js/injectUI5.cjs

@@ -251,7 +251,7 @@ async function clientSide_injectUI5(config, waitForUI5Timeout, browserInstance)
                         } while ((currentObj = Object.getPrototypeOf(currentObj)))
 
                         // filter for:
-                        // @ts-ignore
+                        // @ts-expect-error - TS doesn't know that the keys are strings
                         let controlMethodsToProxy = [...properties.keys()].filter((item) => {
                             if (typeof control[item] === "function") {
                                 // function

docs/authentication.md

@@ -10,17 +10,17 @@
 
 Generally speaking, the authentication behavior mimicks that of a regular user session: first, the `baseUrl` (from the `wdio.conf.(j|t)s`-file) is opened in the configured browser. Then, the redirect to the Authentication provider is awaited and [the credentials](#credentials) are supplied.
 
-BTP-, IAS-, Office365- and custom IdP all supply credentials as a user would, meaning they're literally typed into the respective input fields on each login screen.  
+BTP-, IAS-, Office365- and custom IdP all supply credentials as a user would, meaning they're literally typed into the respective input fields on each login screen.
 Basic Authentication prepends username and password in encoded form to the URL, resulting in an `HTTP` `GET` in the form of `https://username:[email protected]`.
 
 !> Multi-Factor Authentication is not supported as it's nearly impossible to manage any media break (e.g. browser ↔ mobile) in authentication flows out of the box
 
-For you as users, authentication is done at design-time, meaning: **by configuration only, not programmatically**.  
+For you as users, authentication is done at design-time, meaning: **by configuration only, not programmatically**.
 This especially means that no changes in the test code are needed for using authentication in `wdi5` tests!
 
 ?> No [skipping of the UI5 injection](configuration#skipinjectui5onstart) is necessary, `wdi5` takes care of the correct order of operation (first authentication, then injecting UI5) itself.
 
-!> Credentials can only be supplied via environment variables, not in any configuration file.  
+!> Credentials can only be supplied via environment variables, not in any configuration file.
 More on the [how and why below](#credentials) :point_down:
 
 ## Configuration
@@ -127,8 +127,8 @@ The `BTP` authenticator will automatically detect whether the login process is a
 
 ?> only available in `wdi5` >= 2
 
-Using the 'Identity Authentication Service (IAS) Authenticator' in `wdi5` is a subset of the [above BTP Authentication](#sap-cloud-idp-default-btp-identity-provider).  
-It takes the same configuration options, plus `disableBiometricAuth` (default: `true`, which you want in almost all cases) and `idpDomain`. The latter is necessary to satisfy cookie conditions in the remote-controlled browser.  
+Using the 'Identity Authentication Service (IAS) Authenticator' in `wdi5` is a subset of the [above BTP Authentication](#sap-cloud-idp-default-btp-identity-provider).
+It takes the same configuration options, plus `disableBiometricAuth` (default: `true`, which you want in almost all cases) and `idpDomain`. The latter is necessary to satisfy cookie conditions in the remote-controlled browser.
 Set `idpDomain` to the _domain-only_ part of your IAS tenant URL, e.g. `weiruhg.accounts.ondemand.com`, _omitting_ the protocol prefix (`https://`).
 
 !> If `disableBiometricAuth` is set to `true`, `idpDomain` must be set as well!
@@ -310,7 +310,8 @@ baseUrl: "https://caution_your-deployed-ui5-with-basic-auth.app",
 capabilities: {
     // browserName: "..."
     "wdi5:authentication": {
-        provider: "BasicAuth" //> mandatory
+        provider: "BasicAuth", //> mandatory
+        basicAuthUrls: ["https://your-custom-basic-auth-endpoint"] //> optional: default is the configured `baseUrl`
     }
 }
 ```
@@ -325,7 +326,8 @@ capabilities: {
         capabilities: {
             // browserName: "..."
             "wdi5:authentication": {
-                provider: "BasicAuth" //> mandatory
+                provider: "BasicAuth", //> mandatory
+                basicAuthUrls: ["https://your-custom-basic-auth-endpoint"] //> optional: default is the configured `baseUrl`
             }
         }
     },
@@ -334,15 +336,31 @@ capabilities: {
         capabilities: {
             // browserName: "..."
             "wdi5:authentication": {
-                provider: "BasicAuth" //> mandatory
+                provider: "BasicAuth", //> mandatory
+                basicAuthUrls: ["https://your-custom-basic-auth-endpoint"] //> optional: default is the configured `baseUrl`
             }
         }
     }
 }
 ```
 
+#### CAP Authentication (only during development!)
+During development it is common to use basic authentication to mock users. In contrast to deployed applications we have to authenticate ourself directly to the exposed OData enpoints and not to the application itself. For that reason you have to configure the `basicAuthUrls` which should point to the OData `$metadata`.
+
+```js
+capabilities: {
+    // browserName: "..."
+    "wdi5:authentication": {
+        provider: "BasicAuth", //> mandatory
+        basicAuthUrls: ["http://localhost:4004/odata/v4/myEndpoint/$metadata", "http://localhost:4004/odata/v4/myOtherEndpoint/$metadata"]
+    }
+}
+```
+If you have multiple OData endpoints you have to declare every single OData endpoint in the `basicAuthUrls` array.
+
 <!-- tabs:end -->
 
+
 ## Credentials
 
 Exposing credentials in configuration files that were accidentally checked into version control is one of the most common causes of data leaks. That's why `wdi5` only allows providing credentials through environment variables at runtime.
@@ -351,7 +369,7 @@ Exposing credentials in configuration files that were accidentally checked into
 
 There are multiple ways to achieve that in Node.js, with [using the `dotenv`-module](https://www.npmjs.com/package/dotenv) being one of the most popular: `dotenv` automatically transfers all variables from a `.env`-file into the environment of the app at runtime.
 
-In single browser scenarios, `wdi5_username` and `wdi5_password` need to be provided.  
+In single browser scenarios, `wdi5_username` and `wdi5_password` need to be provided.
 In multiremote scenarios, credential keys in the environment adhere to `wdi5_$browserInstanceName_username` and `wdi5_$browserInstanceName_password`.
 
 <!-- tabs:start -->
@@ -381,5 +399,5 @@ wdi5_nix_password='dmac'
 
 ## Miscellaneous
 
-Why the `wdi5:...` prefix?  
+Why the `wdi5:...` prefix?
 Because the W3C standard for providing options in the WebDriver protocol asks for any vendor-specfic setting to have a unique prefix.

examples/cap-bookshop-wdi5

@@ -31,7 +31,7 @@ describe("Basic", async () => {
         const view = await (browser.asControl(selector) as unknown as Page).getParent()
         const controller: Controller = await (view as View).getController()
 
-        // @ts-ignore this async fn lives in an not properly typed controller
+        // @ts-expect-error this async fn lives in an not properly typed controller
         const number = await controller.asyncFn()
         expect(number).toEqual(10)
     })
@@ -49,7 +49,7 @@ describe("Basic", async () => {
         const view: unknown = await (browser.asControl(selector) as unknown as Page).getParent()
         const controller: Controller = await (view as View).getController()
 
-        // @ts-ignore this async fn lives in an not properly typed controller
+        // @ts-expect-error this async fn lives in an not properly typed controller
         await controller.asyncRejectFn()
         expect(
             (Logger.error as sinon.SinonSpy).calledWith('call of asyncRejectFn failed because of: "meh"')

examples/ui5-ts-app/test/e2e/Basic.test.ts

@@ -25,7 +25,7 @@ describe("Input", async () => {
     it("should retrieve the webcomponent's bound path via a managed object", async () => {
         const control = await browser.asControl(inputSelector)
         const bindingInfo = await control.getBindingInfo("value")
-        // @ts-ignore
+        // @ts-expect-error "parts" is not part of the type definition
         const parts = await bindingInfo.parts
         expect(parts[0].path).toEqual("/Customers('TRAIH')/ContactName")
     })

examples/ui5-ts-app/test/e2e/Input.test.ts

@@ -11,7 +11,7 @@ describe("MultiInput", async () => {
                 interaction: "root"
             }
         }
-        // @ts-ignore
+        // @ts-expect-error we'd need to properly type the multi input control
         await (browser.asControl(multiInputSelector) as unknown as MultiInput).enterText("123")
 
         const multiInput = await browser.asControl<MultiInput>(multiInputSelector)

examples/ui5-ts-app/test/e2e/MultiInput.test.ts

@@ -9,9 +9,9 @@ describe("Basic", async () => {
                 viewName: "test.Sample.tsapp.view.Main"
             }
         }
-        // @ts-ignore
+        // @ts-expect-error browser ref ("two") is not properly typed
         const allButtonsTwo = await browser.two.allControls<Button>(allButtonsSelector)
-        // @ts-ignore
+        // @ts-expect-error browser ref ("one") is not properly typed
         const allButtonsOne = await browser.one.allControls<Button>(allButtonsSelector)
         expect(allButtonsTwo.length).toEqual(1)
         expect(allButtonsOne.length).toEqual(1)

examples/ui5-ts-app/test/e2e/multiremote.test.ts

@@ -7,7 +7,8 @@ export const config: wdi5Config = {
     services: ["ui5"],
     specs: [resolve("test/e2e/protocol/*.test.ts")],
     wdi5: {
-        logLevel: "verbose"
+        logLevel: "verbose",
+        waitForUI5Timeout: 25000
     },
     automationProtocol: "devtools",
     capabilities: [

examples/ui5-ts-app/test/e2e/protocol/wdio-ui5-devtools.conf.ts

@@ -5,7 +5,8 @@ export const config: wdi5Config = {
     baseUrl: "https://wdi5-sample-app.cfapps.eu20.hana.ondemand.com/no-auth/",
     services: ["ui5"],
     wdi5: {
-        logLevel: "verbose"
+        logLevel: "verbose",
+        waitForUI5Timeout: 25000
     },
     specs: [resolve("test/e2e/protocol/*.test.ts")],
     capabilities: [

examples/ui5-ts-app/test/e2e/protocol/wdio-ui5-webdriver.conf.ts

@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html>
     <head>
         <meta http-equiv="Cache-control" content="no-cache, no-store, must-revalidate" />