web/add webdriverIO testing layer

This commit adds WebdriverIO as an end-to-end solution to unit testing.  WebdriverIO can be run both
locally and remotely, supports strong integration with web components, and is generally robust for
use in pipelines.  I'll confess to working through a tutorial on how to do this for web components,
and this is just chapter 2 (I think there are 5 or so chapters...).

There's a makefile, with help!  If you just run `make` it tells you:

```
Specify a command. The choices are:

  help                 Show this help
  node_modules         Runs `npm install` to prepare this feature
  precommit            Run the precommit: spell check all comments, eslint with sonarJS, prettier-write
  test-good-login      Test that we can log into the server. Requires a running instance of the server.
  test-bad-login       Test that bad usernames and passwords create appropriate error messages
```

... because Makefiles are documentation, and documentation belongs in Makefiles.

I've chosen to go with a PageObject-oriented low-level DSL; what that means is that for each major
components (a page, a form, a wizard), there's a class that provides human-readable names for
human-interactable and human-viewable objects on the page.  The LoginPage object, for example, has
selectors for the username, password, submit button, and the failure alert; accessing those allows
us to test for items as expected., and to write a DSL for "a good login" that's as straightforward
as:

```
        await LoginPage.open();
        await LoginPage.login("ken@goauthentik.io", "eat10bugs");
        await expect(UserLibraryPage.pageHeader).toHaveText("My applications");
```

There was a *lot* of messing around with the LoginPage to get the username and password into the
system.  For example, I had to do this with all the `waitForClickable` and `waitForEnable` because
we both keep the buttons inaccessible until the form has something and we "black out" the page (put
a darkening filter over it) while accessing the flow, meaning there was a race condition such that
the test would attempt to interact with the username or password field before it was accessible.
But this works now, which is very nice.

``` JavaScript
    get inputUsername() {
        return $('>>>input[name="uidField"]');
    }

    get btnSubmit() {
        return $('>>>button[type="submit"]');
    }

    async username(username: string) {
        await this.inputUsername.waitForClickable();
        await this.inputUsername.setValue(username);
        await this.btnSubmit.waitForEnabled();
        await this.btnSubmit.click();
    }
```

The bells & whistles of *Prettier*, *Eslint*, and *Codespell* have also been enabled. I do like my
guardrails.

tests/wdio/.eslintignore

@@ -0,0 +1,8 @@
+# don't ever lint node_modules
+node_modules
+# don't lint build output (make sure it's set to your correct build folder name)
+dist
+# don't lint nyc coverage output
+coverage
+src/locale-codes.ts
+storybook-static/

tests/wdio/.eslintrc.json

@@ -0,0 +1,20 @@
+{
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": 12,
+        "sourceType": "module"
+    },
+    "plugins": ["@typescript-eslint"],
+    "rules": {
+        "indent": "off",
+        "linebreak-style": ["error", "unix"],
+        "quotes": ["error", "double", { "avoidEscape": true }],
+        "semi": ["error", "always"],
+        "@typescript-eslint/ban-ts-comment": "off"
+    }
+}

tests/wdio/.eslintrc.precommit.json

@@ -0,0 +1,26 @@
+{
+    "env": {
+        "browser": true,
+        "es2021": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended",
+        "plugin:sonarjs/recommended"
+    ],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": 12,
+        "sourceType": "module"
+    },
+    "plugins": ["@typescript-eslint", "sonarjs"],
+    "rules": {
+        "indent": "off",
+        "linebreak-style": ["error", "unix"],
+        "quotes": ["error", "double", { "avoidEscape": true }],
+        "semi": ["error", "always"],
+        "@typescript-eslint/ban-ts-comment": "off",
+        "sonarjs/cognitive-complexity": ["error", 9],
+        "sonarjs/no-nested-template-literals": "off"
+    }
+}

tests/wdio/.gitignore

@@ -0,0 +1,109 @@
+
+# Created by https://www.gitignore.io/api/node
+# Edit at https://www.gitignore.io/?templates=node
+
+### Node ###
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+dist
+
+# Uncomment the public line if your project uses Gatsby
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# https://create-react-app.dev/docs/using-the-public-folder/#docsNav
+# public
+
+# Storybook build outputs
+.out
+.storybook-out
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Temporary folders
+tmp/
+temp/
+
+# End of https://www.gitignore.io/api/node

tests/wdio/.prettierignore

@@ -0,0 +1,11 @@
+# don't ever lint node_modules
+node_modules
+# don't lint build output (make sure it's set to your correct build folder name)
+dist
+# don't lint nyc coverage output
+coverage
+# Import order matters
+poly.ts
+src/locale-codes.ts
+src/locales/
+storybook-static/

tests/wdio/.prettierrc.json

@@ -0,0 +1,22 @@
+{
+    "arrowParens": "always",
+    "bracketSpacing": true,
+    "embeddedLanguageFormatting": "auto",
+    "htmlWhitespaceSensitivity": "css",
+    "insertPragma": false,
+    "jsxSingleQuote": false,
+    "printWidth": 100,
+    "proseWrap": "preserve",
+    "quoteProps": "consistent",
+    "requirePragma": false,
+    "semi": true,
+    "singleQuote": false,
+    "tabWidth": 4,
+    "trailingComma": "all",
+    "useTabs": false,
+    "vueIndentScriptAndStyle": false,
+    "plugins": ["@trivago/prettier-plugin-sort-imports"],
+    "importOrderSeparation": true,
+    "importOrderSortSpecifiers": true,
+    "importOrderParserPlugins": ["typescript", "classProperties", "decorators-legacy"]
+}

tests/wdio/Makefile

@@ -0,0 +1,26 @@
+.PHONY: help
+help:  ## Show this help
+	@echo "\nSpecify a command. The choices are:\n"
+	@grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+	    awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[0;36m%-20s\033[m %s\n", $$1, $$2}'
+	@echo ""
+
+WDIO = npm run wdio
+SPEC = $(WDIO) -- --spec ./test/specs
+
+node_modules: ## Runs `npm install` to prepare this feature
+	npm ci
+
+.PHONY: precommit
+precommit: node_modules  ## Run the precommit: spell check all comments, eslint with sonarJS, prettier-write
+	npm run precommit
+
+# Actual tests are down below:
+
+.PHONY: test-good-login
+test-good-login: node_modules  ## Test that we can log into the server. Requires a running instance of the server.
+	$(SPEC)/good-login.ts
+
+.PHONY: test-bad-login
+test-bad-login: node_modules  ## Test that bad usernames and passwords create appropriate error messages
+	$(SPEC)/bad-logins.ts

tests/wdio/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "my-new-project",
+    "type": "module",
+    "devDependencies": {
+        "@trivago/prettier-plugin-sort-imports": "^4.2.0",
+        "@typescript-eslint/eslint-plugin": "^6.7.2",
+        "@typescript-eslint/parser": "^6.7.2",
+        "@wdio/cli": "^8.16.11",
+        "@wdio/local-runner": "^8.16.11",
+        "@wdio/mocha-framework": "^8.16.11",
+        "@wdio/spec-reporter": "^8.16.9",
+        "eslint": "^8.49.0",
+        "eslint-config-google": "^0.14.0",
+        "eslint-plugin-sonarjs": "^0.21.0",
+        "npm-run-all": "^4.1.5",
+        "prettier": "^3.0.3",
+        "ts-node": "^10.9.1",
+        "typescript": "^5.2.2",
+        "wdio-wait-for": "^3.0.7"
+    },
+    "scripts": {
+        "wdio": "wdio run ./wdio.conf.ts",
+        "lint:precommit": "eslint --max-warnings 0 --config ./.eslintrc.precommit.json $(git status --porcelain . | grep '^[AM?][M?]' | cut -d'/' -f3- | grep -E '\\.(ts|js|tsx|jsx)$')",
+        "lint:spelling": "codespell -D - -D $(git rev-parse --show-toplevel 2> /dev/null)/.github/codespell-dictionary.txt -I $(git rev-parse --show-toplevel 2> /dev/null)/.github/codespell-words.txt ./test -s",
+        "precommit": "run-s lint:precommit lint:spelling prettier",
+        "prettier-check": "prettier --check .",
+        "prettier": "prettier --write ."
+    }
+}

tests/wdio/test/pageobjects/admin-overview.page.ts

@@ -0,0 +1,12 @@
+import AdminPage from "./admin.page.js";
+
+/**
+ * sub page containing specific selectors and methods for a specific page
+ */
+class AdminOverviewPage extends AdminPage {
+    /**
+     * define selectors using getter methods
+     */
+}
+
+export default new AdminOverviewPage();

tests/wdio/test/pageobjects/admin.page.ts

@@ -0,0 +1,25 @@
+import Page from "../pageobjects/page.js";
+import { browser } from "@wdio/globals";
+
+const CLICK_TIME_DELAY = 250;
+
+export default class AdminPage extends Page {
+    public get pageHeader() {
+        return $(">>>ak-page-header h1");
+    }
+
+    async openApplicationsListPage() {
+        await this.open("if/admin/#/core/applications");
+    }
+
+    public open(path: string) {
+        return browser.url(`http://localhost:9000/${path}`);
+    }
+
+    public pause(selector?: string) {
+        if (selector) {
+            return $(selector).waitForDisplayed();
+        }
+        return browser.pause(CLICK_TIME_DELAY);
+    }
+}

tests/wdio/test/pageobjects/application-form.view.ts

@@ -0,0 +1,10 @@
+import Page from "./page.js";
+import { $ } from "@wdio/globals";
+
+export class ApplicationForm extends Page {
+    get name() {
+        return $('>>>ak-form-element-horizontal input[name="name"]');
+    }
+}
+
+export default new ApplicationForm();

tests/wdio/test/pageobjects/application-wizard.page.ts

@@ -0,0 +1,40 @@
+import AdminPage from "./admin.page.js";
+import ApplicationForm from "./application-form.view.js";
+import LdapForm from "./ldap-form.view.js";
+import OauthForm from "./oauth-form.view.js";
+import { $ } from "@wdio/globals";
+
+/**
+ * sub page containing specific selectors and methods for a specific page
+ */
+class ApplicationWizardView extends AdminPage {
+    /**
+     * define selectors using getter methods
+     */
+
+    ldap = LdapForm;
+    oauth = OauthForm;
+    app = ApplicationForm;
+
+    get wizardTitle() {
+        return $(">>>ak-application-wizard-commit-application h1.pf-c-title");
+    }
+
+    get providerList() {
+        return $(">>>ak-application-wizard-authentication-method-choice");
+    }
+
+    get nextButton() {
+        return $(">>>ak-wizard-frame footer button.pf-m-primary");
+    }
+
+    async getProviderType(type: string) {
+        return await this.providerList.$(`>>>input[value="${type}"]`);
+    }
+
+    get commitMessage() {
+        return $(">>>ak-application-wizard-commit-application h1.pf-c-title");
+    }
+}
+
+export default new ApplicationWizardView();

tests/wdio/test/pageobjects/applications-list.page.ts

@@ -0,0 +1,17 @@
+import AdminPage from "./admin.page.js";
+import { $ } from "@wdio/globals";
+
+/**
+ * sub page containing specific selectors and methods for a specific page
+ */
+class ApplicationsListPage extends AdminPage {
+    /**
+     * define selectors using getter methods
+     */
+
+    async startCreateApplicationWizard() {
+        await $('>>>ak-wizard-frame button[slot="trigger"]').click();
+    }
+}
+
+export default new ApplicationsListPage();

tests/wdio/test/pageobjects/ldap-form.view.ts

@@ -0,0 +1,13 @@
+import Page from "./page.js";
+
+export class LdapForm extends Page {
+    async setBindFlow(selector: string) {
+        await this.searchSelect(
+            '>>>ak-tenanted-flow-search[name="authorizationFlow"] input[type="text"]',
+            "authorizationFlow",
+            `button*=${selector}`,
+        );
+    }
+}
+
+export default new LdapForm();

tests/wdio/test/pageobjects/login.page.ts

@@ -0,0 +1,63 @@
+import Page from "./page.js";
+import UserLibraryPage from "./user-library.page.js";
+import { $ } from "@wdio/globals";
+
+/**
+ * sub page containing specific selectors and methods for a specific page
+ */
+class LoginPage extends Page {
+    /**
+     * Selectors
+     */
+    get inputUsername() {
+        return $('>>>input[name="uidField"]');
+    }
+
+    get inputPassword() {
+        return $('>>>input[name="password"]');
+    }
+
+    get btnSubmit() {
+        return $('>>>button[type="submit"]');
+    }
+
+    get authFailure() {
+        return $(">>>h4.pf-c-alert__title");
+    }
+
+    /**
+     * Specific interactions
+     */
+
+    async username(username: string) {
+        await this.inputUsername.waitForClickable();
+        await this.inputUsername.setValue(username);
+        await this.btnSubmit.waitForEnabled();
+        await this.btnSubmit.click();
+    }
+
+    async password(password: string) {
+        await this.inputPassword.waitForClickable();
+        await this.inputPassword.setValue(password);
+        await this.btnSubmit.waitForEnabled();
+        await this.btnSubmit.click();
+    }
+
+    async login(username: string, password: string) {
+        await this.username(username);
+        await this.pause();
+        await this.password(password);
+        await this.pause();
+        await this.pause(">>>div.header h1");
+        return UserLibraryPage;
+    }
+
+    /**
+     * URL for accessing this page (if necessary)
+     */
+    open() {
+        return super.open("");
+    }
+}
+
+export default new LoginPage();

tests/wdio/test/pageobjects/oauth-form.view.ts

@@ -0,0 +1,13 @@
+import Page from "./page.js";
+
+export class OauthForm extends Page {
+    async setAuthorizationFlow(selector: string) {
+        await this.searchSelect(
+            '>>>ak-flow-search[name="authorizationFlow"] input[type="text"]',
+            "authorizationFlow",
+            `button*=${selector}`,
+        );
+    }
+}
+
+export default new OauthForm();

tests/wdio/test/pageobjects/page.ts

@@ -0,0 +1,32 @@
+import { browser } from "@wdio/globals";
+
+const CLICK_TIME_DELAY = 250;
+
+/**
+ * main page object containing all methods, selectors and functionality
+ * that is shared across all page objects
+ */
+export default class Page {
+    /**
+     * Opens a sub page of the page
+     * @param path path of the sub page (e.g. /path/to/page.html)
+     */
+    public open(path: string) {
+        return browser.url(`http://localhost:9000/${path}`);
+    }
+
+    public pause(selector?: string) {
+        if (selector) {
+            return $(selector).waitForDisplayed();
+        }
+        return browser.pause(CLICK_TIME_DELAY);
+    }
+
+    async searchSelect(searchSelector: string, managedSelector: string, buttonSelector: string) {
+        const inputBind = await $(searchSelector);
+        await inputBind.click();
+        const searchBlock = await $(`>>>div[data-managed-for="${managedSelector}"]`);
+        const target = searchBlock.$(buttonSelector);
+        return await target.click();
+    }
+}

tests/wdio/test/pageobjects/types.ts

@@ -0,0 +1 @@
+export type Constructor<T = object> = new (...args: any[]) => T;

tests/wdio/test/pageobjects/user-library.page.ts

@@ -0,0 +1,22 @@
+import Page from "./page.js";
+import { $ } from "@wdio/globals";
+
+/**
+ * sub page containing specific selectors and methods for a specific page
+ */
+class UserLibraryPage extends Page {
+    /**
+     * define selectors using getter methods
+     */
+
+    public get pageHeader() {
+        return $('>>>h1[aria-level="1"]');
+    }
+
+    public async goToAdmin() {
+        await $('>>>a[href="/if/admin"]').click();
+        await $(">>>ak-admin-overview").waitForDisplayed();
+    }
+}
+
+export default new UserLibraryPage();

tests/wdio/test/specs/bad-logins.ts

@@ -0,0 +1,20 @@
+import LoginPage from "../pageobjects/login.page.js";
+import { expect } from "@wdio/globals";
+
+describe("Log into Authentik", () => {
+    it("should fail on a bad username", async () => {
+        await LoginPage.open();
+        await LoginPage.username("bad-username@bad-logio.io");
+        const failure = await LoginPage.authFailure;
+        expect(failure).toHaveText("Failed to authenticate.");
+    });
+
+    it("should fail on a bad password", async () => {
+        await LoginPage.open();
+        await LoginPage.username("ken@goauthentik.io");
+        await LoginPage.pause();
+        await LoginPage.password("-this-is-a-bad-password-");
+        const failure = await LoginPage.authFailure;
+        expect(failure).toHaveText("Failed to authenticate.");
+    });
+});

tests/wdio/test/specs/good-login.ts

@@ -0,0 +1,11 @@
+import LoginPage from "../pageobjects/login.page.js";
+import UserLibraryPage from "../pageobjects/user-library.page.js";
+import { expect } from "@wdio/globals";
+
+describe("Log into Authentik", () => {
+    it("should login with valid credentials", async () => {
+        await LoginPage.open();
+        await LoginPage.login("ken@goauthentik.io", "eat10bugs");
+        await expect(UserLibraryPage.pageHeader).toHaveText("My applications");
+    });
+});

tests/wdio/test/utils/index.ts

@@ -0,0 +1,15 @@
+export function randomId() {
+    let dt = new Date().getTime();
+    return "xxxxxxxx".replace(/x/g, (c) => {
+        const r = (dt + Math.random() * 16) % 16 | 0;
+        dt = Math.floor(dt / 16);
+        return (c == "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+
+export function convertToSlug(text: string) {
+    return text
+        .toLowerCase()
+        .replace(/ /g, "-")
+        .replace(/[^\w-]+/g, "");
+}

tests/wdio/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "compilerOptions": {
+        "moduleResolution": "node",
+        "module": "ESNext",
+        "target": "es2022",
+        "types": ["node", "@wdio/globals/types", "expect-webdriverio", "@wdio/mocha-framework"],
+        "skipLibCheck": true,
+        "noEmit": true,
+        "allowImportingTsExtensions": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "strict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "include": ["test"]
+}

tests/wdio/wdio.conf.ts

@@ -0,0 +1,291 @@
+import type { Options } from "@wdio/types";
+
+export const config: Options.Testrunner = {
+    //
+    // ====================
+    // Runner Configuration
+    // ====================
+    // WebdriverIO supports running e2e tests as well as unit and component tests.
+    runner: "local",
+    autoCompileOpts: {
+        autoCompile: true,
+        tsNodeOpts: {
+            project: "./tsconfig.json",
+            transpileOnly: true,
+        },
+    },
+
+    //
+    // ==================
+    // Specify Test Files
+    // ==================
+    // Define which test specs should run. The pattern is relative to the directory
+    // of the configuration file being run.
+    //
+    // The specs are defined as an array of spec files (optionally using wildcards
+    // that will be expanded). The test for each spec file will be run in a separate
+    // worker process. In order to have a group of spec files run in the same worker
+    // process simply enclose them in an array within the specs array.
+    //
+    // If you are calling `wdio` from an NPM script (see https://docs.npmjs.com/cli/run-script),
+    // then the current working directory is where your `package.json` resides, so `wdio`
+    // will be called from there.
+    //
+    specs: ["./test/specs/**/*.ts"],
+    // Patterns to exclude.
+    exclude: [
+        // 'path/to/excluded/files'
+    ],
+    //
+    // ============
+    // Capabilities
+    // ============
+    // Define your capabilities here. WebdriverIO can run multiple capabilities at the same
+    // time. Depending on the number of capabilities, WebdriverIO launches several test
+    // sessions. Within your capabilities you can overwrite the spec and exclude options in
+    // order to group specific specs to a specific capability.
+    //
+    // First, you can define how many instances should be started at the same time. Let's
+    // say you have 3 different capabilities (Chrome, Firefox, and Safari) and you have
+    // set maxInstances to 1; wdio will spawn 3 processes. Therefore, if you have 10 spec
+    // files and you set maxInstances to 10, all spec files will get tested at the same time
+    // and 30 processes will get spawned. The property handles how many capabilities
+    // from the same test should run tests.
+    //
+    maxInstances: 1,
+    //
+    // If you have trouble getting all important capabilities together, check out the
+    // Sauce Labs platform configurator - a great tool to configure your capabilities:
+    // https://saucelabs.com/platform/platform-configurator
+    //
+    capabilities: [
+        {
+            browserName: "chrome",
+        },
+    ],
+
+    //
+    // ===================
+    // Test Configurations
+    // ===================
+    // Define all options that are relevant for the WebdriverIO instance here
+    //
+    // Level of logging verbosity: trace | debug | info | warn | error | silent
+    logLevel: "info",
+    //
+    // Set specific log levels per logger
+    // loggers:
+    // - webdriver, webdriverio
+    // - @wdio/browserstack-service, @wdio/devtools-service, @wdio/sauce-service
+    // - @wdio/mocha-framework, @wdio/jasmine-framework
+    // - @wdio/local-runner
+    // - @wdio/sumologic-reporter
+    // - @wdio/cli, @wdio/config, @wdio/utils
+    // Level of logging verbosity: trace | debug | info | warn | error | silent
+    // logLevels: {
+    //     webdriver: 'info',
+    //     '@wdio/appium-service': 'info'
+    // },
+    //
+    // If you only want to run your tests until a specific amount of tests have failed use
+    // bail (default is 0 - don't bail, run all tests).
+    bail: 0,
+    //
+    // Set a base URL in order to shorten url command calls. If your `url` parameter starts
+    // with `/`, the base url gets prepended, not including the path portion of your baseUrl.
+    // If your `url` parameter starts without a scheme or `/` (like `some/path`), the base url
+    // gets prepended directly.
+    baseUrl: "http://localhost",
+    //
+    // Default timeout for all waitFor* commands.
+    waitforTimeout: 10000,
+    //
+    // Default timeout in milliseconds for request
+    // if browser driver or grid doesn't send response
+    connectionRetryTimeout: 120000,
+    //
+    // Default request retries count
+    connectionRetryCount: 3,
+    //
+    // Test runner services
+    // Services take over a specific job you don't want to take care of. They enhance
+    // your test setup with almost no effort. Unlike plugins, they don't add new
+    // commands. Instead, they hook themselves up into the test process.
+    // services: [],
+    //
+    // Framework you want to run your specs with.
+    // The following are supported: Mocha, Jasmine, and Cucumber
+    // see also: https://webdriver.io/docs/frameworks
+    //
+    // Make sure you have the wdio adapter package for the specific framework installed
+    // before running any tests.
+    framework: "mocha",
+    //
+    // The number of times to retry the entire specfile when it fails as a whole
+    // specFileRetries: 1,
+    //
+    // Delay in seconds between the spec file retry attempts
+    // specFileRetriesDelay: 0,
+    //
+    // Whether or not retried spec files should be retried immediately or deferred to the end of the queue
+    // specFileRetriesDeferred: false,
+    //
+    // Test reporter for stdout.
+    // The only one supported by default is 'dot'
+    // see also: https://webdriver.io/docs/dot-reporter
+    reporters: ["spec"],
+
+    //
+    // Options to be passed to Mocha.
+    // See the full list at http://mochajs.org/
+    mochaOpts: {
+        ui: "bdd",
+        timeout: 60000,
+    },
+    //
+    // =====
+    // Hooks
+    // =====
+    // WebdriverIO provides several hooks you can use to interfere with the test process in order to enhance
+    // it and to build services around it. You can either apply a single function or an array of
+    // methods to it. If one of them returns with a promise, WebdriverIO will wait until that promise got
+    // resolved to continue.
+    /**
+     * Gets executed once before all workers get launched.
+     * @param {object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     */
+    // onPrepare: function (config, capabilities) {
+    // },
+    /**
+     * Gets executed before a worker process is spawned and can be used to initialise specific service
+     * for that worker as well as modify runtime environments in an async fashion.
+     * @param  {string} cid      capability id (e.g 0-0)
+     * @param  {object} caps     object containing capabilities for session that will be spawn in the worker
+     * @param  {object} specs    specs to be run in the worker process
+     * @param  {object} args     object that will be merged with the main configuration once worker is initialized
+     * @param  {object} execArgv list of string arguments passed to the worker process
+     */
+    // onWorkerStart: function (cid, caps, specs, args, execArgv) {
+    // },
+    /**
+     * Gets executed just after a worker process has exited.
+     * @param  {string} cid      capability id (e.g 0-0)
+     * @param  {number} exitCode 0 - success, 1 - fail
+     * @param  {object} specs    specs to be run in the worker process
+     * @param  {number} retries  number of retries used
+     */
+    // onWorkerEnd: function (cid, exitCode, specs, retries) {
+    // },
+    /**
+     * Gets executed just before initialising the webdriver session and test framework. It allows you
+     * to manipulate configurations depending on the capability or spec.
+     * @param {object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs List of spec file paths that are to be run
+     * @param {string} cid worker id (e.g. 0-0)
+     */
+    // beforeSession: function (config, capabilities, specs, cid) {
+    // },
+    /**
+     * Gets executed before test execution begins. At this point you can access to all global
+     * variables like `browser`. It is the perfect place to define custom commands.
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs        List of spec file paths that are to be run
+     * @param {object}         browser      instance of created browser/device session
+     */
+    // before: function (capabilities, specs) {
+    // },
+    /**
+     * Runs before a WebdriverIO command gets executed.
+     * @param {string} commandName hook command name
+     * @param {Array} args arguments that command would receive
+     */
+    // beforeCommand: function (commandName, args) {
+    // },
+    /**
+     * Hook that gets executed before the suite starts
+     * @param {object} suite suite details
+     */
+    // beforeSuite: function (suite) {
+    // },
+    /**
+     * Function to be executed before a test (in Mocha/Jasmine) starts.
+     */
+    // beforeTest: function (test, context) {
+    // },
+    /**
+     * Hook that gets executed _before_ a hook within the suite starts (e.g. runs before calling
+     * beforeEach in Mocha)
+     */
+    // beforeHook: function (test, context) {
+    // },
+    /**
+     * Hook that gets executed _after_ a hook within the suite starts (e.g. runs after calling
+     * afterEach in Mocha)
+     */
+    // afterHook: function (test, context, { error, result, duration, passed, retries }) {
+    // },
+    /**
+     * Function to be executed after a test (in Mocha/Jasmine only)
+     * @param {object}  test             test object
+     * @param {object}  context          scope object the test was executed with
+     * @param {Error}   result.error     error object in case the test fails, otherwise `undefined`
+     * @param {*}       result.result    return object of test function
+     * @param {number}  result.duration  duration of test
+     * @param {boolean} result.passed    true if test has passed, otherwise false
+     * @param {object}  result.retries   information about spec related retries, e.g. `{ attempts: 0, limit: 0 }`
+     */
+    // afterTest: function(test, context, { error, result, duration, passed, retries }) {
+    // },
+
+    /**
+     * Hook that gets executed after the suite has ended
+     * @param {object} suite suite details
+     */
+    // afterSuite: function (suite) {
+    // },
+    /**
+     * Runs after a WebdriverIO command gets executed
+     * @param {string} commandName hook command name
+     * @param {Array} args arguments that command would receive
+     * @param {number} result 0 - command success, 1 - command error
+     * @param {object} error error object if any
+     */
+    // afterCommand: function (commandName, args, result, error) {
+    // },
+    /**
+     * Gets executed after all tests are done. You still have access to all global variables from
+     * the test.
+     * @param {number} result 0 - test pass, 1 - test fail
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs List of spec file paths that ran
+     */
+    // after: function (result, capabilities, specs) {
+    // },
+    /**
+     * Gets executed right after terminating the webdriver session.
+     * @param {object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {Array.<String>} specs List of spec file paths that ran
+     */
+    // afterSession: function (config, capabilities, specs) {
+    // },
+    /**
+     * Gets executed after all workers got shut down and the process is about to exit. An error
+     * thrown in the onComplete hook will result in the test run failing.
+     * @param {object} exitCode 0 - success, 1 - fail
+     * @param {object} config wdio configuration object
+     * @param {Array.<Object>} capabilities list of capabilities details
+     * @param {<Object>} results object containing test results
+     */
+    // onComplete: function(exitCode, config, capabilities, results) {
+    // },
+    /**
+     * Gets executed when a refresh happens.
+     * @param {string} oldSessionId session ID of the old session
+     * @param {string} newSessionId session ID of the new session
+     */
+    // onReload: function(oldSessionId, newSessionId) {
+    // }
+};