@wdio/browser-runner 8.0.0-alpha.537 → 8.0.0-alpha.558

package/README.md

@@ -1,4 +1,67 @@
-WebdriverIO Local Runner
-========================
+WebdriverIO Browser Runner
+==========================
 
-> A WebdriverIO runner to run tests locally
+> A WebdriverIO runner to run unit and component tests within the browser
+
+As opposed to the [Local Runner]((https://www.npmjs.com/package/@wdio/local-runner)) the [Browser Runner]((https://www.npmjs.com/package/@wdio/browser-runner)) initiates and executes the framework within the browser. This allows you to run unit tests or component tests in an actual browser rather than in a JSDOM like many other test frameworks.
+
+While [JSDOM](https://www.npmjs.com/package/jsdom) is widely used for testing purposes, it is in the end not an actual browser nor can you emulate mobile environments with it. With this runner WebdriverIO enables you to easily run your tests in the browser and use WebDriver commands to interact with elements rendered on the page.
+
+Here is an overview of running tests within JSDOM vs. WebdriverIOs Browser Runner
+
+| | JSDOM | WebdriverIO Browser Runner |
+|-|-------|----------------------------|
+|1.| Runs your tests within Node.js using a re-implementation of web standards, notably the WHATWG DOM and HTML Standards | Executes your test in an actual browser and runs the code in an environment that your users use |
+|2.| Interactions with components can only be imitated via JavaScript | You can use the [WebdriverIO API](api) to interact with elements through the WebDriver protocol |
+|3.| Canvas support requires [additional dependencies](https://www.npmjs.com/package/canvas) and [has limitations](https://github.com/Automattic/node-canvas/issues) | You have access to the real [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) |
+|4.| JSDOM has some [caveats](https://www.npmjs.com/package/jsdom#user-content-caveats) and unsupported Web APIs | All Web APIs are supported as test run in an actual browser |
+|5.| Impossible to detect errors cross browser | Support for all browsers including mobile browser |
+
+This runner uses [Vite](https://vitejs.dev/) to compile your test code and load it in the browser. It comes with presets for the following component frameworks:
+
+- React
+- Preact
+- Vue.js
+- Svelte
+
+Every test file / test file group runs within a single page which means that between each test the page is being reloaded to guarantee isolation between tests.
+
+### Install
+
+To use the Browser Runner you can install it via:
+
+```sh
+npm install --save-dev @wdio/browser-runner
+```
+
+### Setup
+
+To use the Browser runner, you have to define a `runner` property within your `wdio.conf.js` file, e.g.:
+
+```js
+// wdio.conf.js
+export const {
+    // ...
+    runner: 'browser',
+    // ...
+}
+```
+
+If you test components using one of the mentioned frameworks above, you can define a preset that ensures everything is configured out of the box, e.g. when you want to import and test Svelte components, define the Browser Runner as follows:
+
+```js
+// wdio.conf.js
+export const {
+    // ...
+    runner: ['browser', {
+        preset: 'Svelte'
+    }],
+    // ...
+}
+```
+
+Make sure to check out the docs around [component testing](https://webdriver.io/docs/component-testing) and have a look into the [example repository](https://github.com/webdriverio/component-testing-examples) for examples using these and various other frameworks.
+
+---
+
+For more information on WebdriverIO runner, check out the [documentation](https://webdriver.io/docs/runner).

package/build/browser/setup.d.ts

@@ -1,4 +1,4 @@
-declare type WDIOErrorEvent = Pick<ErrorEvent, 'filename' | 'message'>;
+type WDIOErrorEvent = Pick<ErrorEvent, 'filename' | 'message'>;
 declare global {
     interface Window {
         __wdioErrors__: WDIOErrorEvent[];

package/build/browser/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/browser/setup.ts"],"names":[],"mappings":"AAKA,aAAK,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;AAE9D,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,cAAc,EAAE,cAAc,EAAE,CAAA;KACnC;CACJ;AAQD,wBAAsB,QAAQ,kBAW7B"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/browser/setup.ts"],"names":[],"mappings":"AAKA,KAAK,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;AAE9D,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,cAAc,EAAE,cAAc,EAAE,CAAA;KACnC;CACJ;AAQD,wBAAsB,QAAQ,kBAW7B"}

package/build/plugins/testrunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testrunner.d.ts","sourceRoot":"","sources":["../../src/plugins/testrunner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AA+ClC,wBAAgB,UAAU,CAAE,OAAO,EAAE,WAAW,CAAC,oBAAoB,GAAG,MAAM,CAkH7E"}
+{"version":3,"file":"testrunner.d.ts","sourceRoot":"","sources":["../../src/plugins/testrunner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AA6ClC,wBAAgB,UAAU,CAAE,OAAO,EAAE,WAAW,CAAC,oBAAoB,GAAG,MAAM,CAkH7E"}

package/build/plugins/testrunner.js

@@ -25,8 +25,6 @@ const virtualModuleId = 'virtual:wdio';
 const resolvedVirtualModuleId = '\0' + virtualModuleId;
 const MODULES_TO_MOCK = [
     'node:module', 'node:events', 'node:path', 'node:url', 'puppeteer-core', 'archiver',
-    'query-selector-shadow-dom/plugins/puppeteer/index.js',
-    'query-selector-shadow-dom/plugins/webdriverio/index.js',
     'glob', 'devtools', 'ws'
 ];
 const FETCH_FROM_ESM = [

package/build/types.d.ts

@@ -6,7 +6,7 @@ declare global {
         wdioDebugContinue: (value: unknown) => void;
     }
 }
-export declare type FrameworkPreset = 'react' | 'preact' | 'vue' | 'svelte' | 'lit';
+export type FrameworkPreset = 'react' | 'preact' | 'vue' | 'svelte' | 'lit';
 export interface BrowserRunnerOptions {
     /**
      * Project root directory

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,WAAW,EAAE,WAAW,CAAA;QACxB,iBAAiB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;KAC9C;CACJ;AAED,oBAAY,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,CAAA;AAE3E,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,YAAY,CAAA;CAC5B;AAED,MAAM,WAAW,OAAQ,SAAQ,OAAO,CAAC,gBAAgB;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,GAAG,CAAA;IACT,GAAG,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,GAAG,CAAA;IACT,YAAY,EAAE,YAAY,CAAC,gBAAgB,CAAA;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;IACjD,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,WAAW,EAAE,WAAW,CAAA;QACxB,iBAAiB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;KAC9C;CACJ;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,CAAA;AAE3E,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,YAAY,CAAA;CAC5B;AAED,MAAM,WAAW,OAAQ,SAAQ,OAAO,CAAC,gBAAgB;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,GAAG,CAAA;IACT,GAAG,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,GAAG,CAAA;IACT,YAAY,EAAE,YAAY,CAAC,gBAAgB,CAAA;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;IACjD,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACd"}

package/build/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,eAAe,EAAa,MAAM,IAAI,CAAA;AAI/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAKxC,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAA;AAI3D,wBAAsB,WAAW,CAAE,OAAO,EAAE,WAAW,CAAC,oBAAoB,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,mBA2E3G;AAED,wBAAsB,gBAAgB,CAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,mBAUrE;AAiBD,wBAAsB,aAAa,CAC/B,OAAO,EAAE,WAAW,CAAC,oBAAoB,EACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC,CAAC,CAyEnD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,eAAe,EAAa,MAAM,IAAI,CAAA;AAI/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAKxC,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAA;AAI3D,wBAAsB,WAAW,CAAE,OAAO,EAAE,WAAW,CAAC,oBAAoB,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,mBA6E3G;AAED,wBAAsB,gBAAgB,CAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,mBAUrE;AAiBD,wBAAsB,aAAa,CAC/B,OAAO,EAAE,WAAW,CAAC,oBAAoB,EACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC,CAAC,CA0DnD"}

package/build/utils.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import getPort from 'get-port';
 import topLevelAwait from 'vite-plugin-top-level-await';
+import { deepmerge } from 'deepmerge-ts';
 import { WebSocketServer } from 'ws';
 import { esbuildCommonjs } from '@originjs/vite-plugin-commonjs';
 import { NodeGlobalsPolyfillPlugin } from '@esbuild-plugins/node-globals-polyfill';
@@ -45,6 +46,7 @@ export async function getTemplate(options, env, spec) {
     <html>
         <head>
             <title>WebdriverIO Browser Test</title>
+            <link rel="icon" type="image/x-icon" href="https://webdriver.io/img/favicon.png">
             <link rel="stylesheet" href="https://unpkg.com/mocha@10.0.0/mocha.css">
             <script type="module">
                 /**
@@ -69,10 +71,11 @@ export async function getTemplate(options, env, spec) {
                 import { setupEnv } from '@wdio/browser-runner/setup'
                 import { formatMessage } from '@wdio/mocha-framework/common'
 
+                window.__wdioEvents__ = []
+
                 await setupEnv()
                 await import('${spec}')
 
-                window.__wdioEvents__ = []
                 console.log('[WDIO] Start Mocha testsuite')
                 const runner = mocha.run((failures) => {
                     window.__wdioFailures__ = failures
@@ -109,27 +112,10 @@ export async function getViteConfig(options, root, port) {
     const wsPort = await getPort();
     const wss = new WebSocketServer({ port: wsPort });
     wss.on('connection', (ws) => ws.on('message', handleBrowserCommand(ws)));
-    /**
-     * user provided vite config
-     */
-    if (options.viteConfig) {
-        options.viteConfig.plugins = [
-            ...(options.viteConfig.plugins || []),
-            testrunner(options)
-        ];
-        options.viteConfig.server = {
-            ...(options.viteConfig.server || {}),
-            proxy: {
-                ...(options.viteConfig.server?.proxy || {}),
-                '/ws': {
-                    target: `ws://localhost:${wsPort}`,
-                    ws: true
-                }
-            }
-        };
-        return [options.viteConfig, wss];
+    if (options.preset && options.viteConfig) {
+        throw new Error('Invalid runner configuration: "preset" and "viteConfig" options are defined but only one of each can be used at the same time');
     }
-    const config = {
+    let config = {
         configFile: false,
         root,
         server: {
@@ -166,7 +152,10 @@ export async function getViteConfig(options, root, port) {
             },
         }
     };
-    if (options.preset) {
+    if (options.viteConfig) {
+        config = deepmerge(config, options.viteConfig);
+    }
+    else if (options.preset) {
         const [pkg, importProp, opts] = PRESET_DEPENDENCIES[options.preset] || [];
         const plugin = (await userfriendlyImport(options.preset, pkg))[importProp || 'default'];
         if (plugin) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdio/browser-runner",
-  "version": "8.0.0-alpha.537+c2761a175",
+  "version": "8.0.0-alpha.558+9156ec0f4",
   "description": "A WebdriverIO runner to run unit tests tests in the browser.",
   "author": "Christian Bromann <mail@bromann.dev>",
   "homepage": "https://github.com/webdriverio/webdriverio/tree/main/packages/wdio-browser-runner",
@@ -30,19 +30,20 @@
     "@babel/plugin-proposal-class-properties": "^7.18.6",
     "@esbuild-plugins/node-globals-polyfill": "^0.1.1",
     "@originjs/vite-plugin-commonjs": "^1.0.3",
-    "@wdio/globals": "8.0.0-alpha.537+c2761a175",
-    "@wdio/local-runner": "8.0.0-alpha.537+c2761a175",
-    "@wdio/logger": "8.0.0-alpha.537+c2761a175",
-    "@wdio/mocha-framework": "8.0.0-alpha.537+c2761a175",
-    "@wdio/protocols": "8.0.0-alpha.537+c2761a175",
-    "@wdio/runner": "8.0.0-alpha.537+c2761a175",
-    "@wdio/types": "8.0.0-alpha.537+c2761a175",
+    "@wdio/globals": "8.0.0-alpha.558+9156ec0f4",
+    "@wdio/local-runner": "8.0.0-alpha.558+9156ec0f4",
+    "@wdio/logger": "8.0.0-alpha.558+9156ec0f4",
+    "@wdio/mocha-framework": "8.0.0-alpha.558+9156ec0f4",
+    "@wdio/protocols": "8.0.0-alpha.558+9156ec0f4",
+    "@wdio/runner": "8.0.0-alpha.558+9156ec0f4",
+    "@wdio/types": "8.0.0-alpha.558+9156ec0f4",
+    "deepmerge-ts": "^4.2.2",
     "expect-webdriverio": "^4.0.0-alpha.6",
     "get-port": "^6.1.2",
     "vite": "^3.1.7",
     "vite-plugin-top-level-await": "^1.2.1",
-    "webdriver": "8.0.0-alpha.537+c2761a175",
-    "webdriverio": "8.0.0-alpha.537+c2761a175",
+    "webdriver": "8.0.0-alpha.558+9156ec0f4",
+    "webdriverio": "8.0.0-alpha.558+9156ec0f4",
     "ws": "^8.10.0"
   },
   "scripts": {
@@ -54,5 +55,5 @@
   "devDependencies": {
     "@types/ws": "^8.5.3"
   },
-  "gitHead": "c2761a17597c5dfbd349445fc203183fb004c3f5"
+  "gitHead": "9156ec0f422b7e784ea148e569fe423ba21a0355"
 }