feat: webdriverio (+ custom providers) integration for browser mode (#…

…2999)

Co-authored-by: Christian Bromann <git@bromann.dev>
Co-authored-by: Vladimir <sleuths.slews0s@icloud.com>
Co-authored-by: userquin <userquin@gmail.com>
Co-authored-by: Anjorin Damilare <damilareanjorin1@gmail.com>

.github/workflows/ci.yml

@@ -101,3 +101,61 @@ jobs:
 
       - name: Test UI
         run: pnpm run ui:test
+
+  test-browser:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        browser: [chrome, firefox, edge]
+
+    timeout-minutes: 10
+
+    env:
+      BROWSER: ${{ matrix.browser }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: ./.github/actions/setup-and-cache
+        with:
+          node-version: 18
+
+      - uses: browser-actions/setup-chrome@v1
+      - uses: browser-actions/setup-firefox@v1
+      - uses: browser-actions/setup-edge@v1
+
+      - name: Install
+        run: pnpm i
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Test Browser
+        run: pnpm run browser:test
+
+  test-browser-safari:
+    runs-on: macos-latest
+    timeout-minutes: 10
+
+    env:
+      BROWSER: safari
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: ./.github/actions/setup-and-cache
+        with:
+          node-version: 18
+
+      - name: Info
+        run: system_profiler SPSoftwareDataType
+
+      - name: Install
+        run: pnpm i
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Enable
+        run: sudo safaridriver --enable
+
+      - name: Test Browser
+        run: sudo pnpm run browser:test

.gitignore

@@ -16,6 +16,7 @@ ltex*
 .DS_Store
 bench/test/*/*/
 **/benchmark/bench.json
+**/browser/browser.json
 cypress/videos
 cypress/downloads
 cypress/screenshots

docs/.vitepress/config.ts

@@ -175,6 +175,10 @@ export default withPwa(defineConfig({
               text: 'Vitest UI',
               link: '/guide/ui',
             },
+            {
+              text: 'Browser Mode',
+              link: '/guide/browser',
+            },
             {
               text: 'In-source Testing',
               link: '/guide/in-source',

docs/config/index.md

@@ -383,7 +383,7 @@ export default defineConfig({
 
 ### poolMatchGlobs
 
-- **Type:** `[string, 'threads' | 'child_process'][]`
+- **Type:** `[string, 'browser' | 'threads' | 'child_process'][]`
 - **Default:** `[]`
 - **Version:** Since Vitest 0.29.4
 
@@ -399,7 +399,9 @@ export default defineConfig({
     poolMatchGlobs: [
       // all tests in "worker-specific" directory will run inside a worker as if you enabled `--threads` for them,
       ['**/tests/worker-specific/**', 'threads'],
-      // all other tests will run based on "threads" option, if you didn't specify other globs
+      // run all tests in "browser" directory in an actual browser
+      ['**/tests/browser/**', 'browser'],
+      // all other tests will run based on "browser.enabled" and "threads" options, if you didn't specify other globs
       // ...
     ]
   }
@@ -992,6 +994,80 @@ Open Vitest UI (WIP)
 
 Listen to port and serve API. When set to true, the default port is 51204
 
+### browser
+
+- **Type:** `{ enabled?, name?, provider?, headless?, api? }`
+- **Default:** `{ enabled: false, headless: process.env.CI, api: 63315 }`
+- **Version:** Since Vitest 0.30.0
+- **CLI:** `--browser`, `--browser=<name>`, `--browser.name=chrome --browser.headless`
+
+Run Vitest tests in a browser. If the browser name is not specified, Vitest will try to determine your default browser automatically. We use [WebdriverIO](https://webdriver.io/) for running tests by default, but it can be configured with [browser.provider](/config/#browser-provider) option.
+
+::: tip NOTE
+Read more about testing in a real browser in the [guide page](/guide/browser).
+:::
+
+::: warning
+This is an experimental feature. Breaking changes might not follow semver, please pin Vitest's version when using it.
+:::
+
+#### browser.enabled
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **CLI:** `--browser`, `--browser.enabled=false`
+
+Run all tests inside a browser by default. Can be overriden with [`poolMatchGlobs`](/config/#poolmatchglobs) option.
+
+#### browser&#46;name
+
+- **Type:** `string`
+- **Default:** _tries to find default browser automatically_
+- **CLI:** `--browser=safari`
+
+Run all tests in a specific browser. If not specified, tries to find a browser automatically.
+
+
+#### browser.headless
+
+- **Type:** `boolean`
+- **Default:** `process.env.CI`
+- **CLI:** `--browser.headless`, `--brower.headless=false`
+
+Run the browser in a `headless` mode. If you are running Vitest in CI, it will be enabled by default.
+
+#### browser.api
+
+- **Type:** `number | { port?, strictPort?, host? }`
+- **Default:** `63315`
+- **CLI:** `--browser.api=63315`, `--browser.api.port=1234, --browser.api.host=example.com`
+
+Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](/config/#api) option.
+
+#### browser.provider
+
+- **Type:** `string`
+- **Default:** `'webdriverio'`
+- **CLI:** `--browser.provider=./custom-provider.ts`
+
+Path to a provider that will be used when running browser tests. Provider should be exported using `default` export and have this shape:
+
+```ts
+export interface BrowserProvider {
+  initialize(ctx: Vitest): Awaitable<void>
+  createPool(): {
+    runTests: (files: string[], invalidated: string[]) => void
+    close: () => Awaited<void>
+  }
+  // signals that test file stopped running, if it was opened with `id=` query
+  testFinished?(testId: string): Awaitable<void>
+}
+```
+
+::: warning
+This is an advanced API for library authors. If you just need to run tests in a browser, use the [browser](/config/#browser) option.
+:::
+
 ### clearMocks
 
 - **Type:** `boolean`

docs/guide/browser.md

@@ -0,0 +1,89 @@
+---
+title: Browser mode | Guide
+---
+
+# Browser mode (experimental)
+
+This page provides information about the experimental browser mode feature in the Vitest API, which allows you to run your tests in the browser natively, providing access to browser globals like window and document. This feature is currently under development, and APIs may change in the future.
+
+## Configuration
+
+To activate browser mode in your Vitest configuration, you can use the `--browser` flag or set the `browser.enabled` field to `true` in your Vitest configuration file. Here is an example configuration using the browser field:
+
+```ts
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true
+    },
+  }
+})
+```
+
+## Browser Option Types:
+
+The browser option in Vitest can be set to either a boolean or a string type. If set to `true`, Vitest will try to automatically find your default browser. You can also specify a browser by providing its name as a `string`. The available browser options are:
+- `firefox`
+- `chrome`
+- `edge`
+- `safari`
+
+Here's an example configuration setting chrome as the browser option:
+
+```ts
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      name: 'chrome',
+    },
+  }
+})
+```
+
+## Cross-browser Testing:
+
+When you specify a browser name in the browser option, Vitest will try to run the specified browser using [WebdriverIO](https://webdriver.io/) by default, and then run the tests there. This feature makes cross-browser testing easy to use and configure in environments like a CI. If you don't want to use WebdriverIO, you can configure the custom browser provider by using `browser.provider` option.
+
+To specify a browser using the CLI, use the `--browser` flag followed by the browser name, like this:
+
+```sh
+npx vitest --browser=chrome
+```
+
+Or if you pass down several options, you dot-syntax:
+
+```sh
+npx vitest --browser.name=chrome --browser.headless
+```
+
+::: tip NOTE
+When using the Safari browser option, the `safaridriver` needs to be activated by running `sudo safaridriver --enable` on your device.
+
+Additionally, when running your tests, Vitest will attempt to install some drivers for compatibility with `safaridriver`.
+:::
+
+## Headless
+
+Headless mode is another option available in the browser mode. In headless mode, the browser runs in the background without a user interface, which makes it useful for running automated tests. The headless option in Vitest can be set to a boolean value to enable or disable headless mode.
+
+Here's an example configuration enabling headless mode:
+
+```ts
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      headless: true,
+    },
+  }
+})
+```
+
+You can also set headless mode using the `--browser.headless` flag in the CLI, like this:
+
+```sh
+npx vitest --browser.name=chrome --browser.headless
+```
+
+In this case, Vitest will run in headless mode using the Chrome browser.

docs/guide/cli.md

@@ -84,7 +84,7 @@ Run only [benchmark](https://vitest.dev/guide/features.html#benchmarking-experim
 | `--mode <name>` | Override Vite mode (default: `test`) |
 | `--globals` | Inject APIs globally |
 | `--dom` | Mock browser api with happy-dom |
-| `--browser` | Run tests in browser |
+| `--browser [options]` | Run tests in [the browser](/guide/browser) (default: `false`) |
 | `--environment <env>` | Runner environment (default: `node`) |
 | `--passWithNoTests` | Pass when no tests found |
 | `--logHeapUsage` | Show the size of heap for each test |

package.json

@@ -7,7 +7,7 @@
   "description": "A blazing fast unit test framework powered by Vite",
   "scripts": {
     "ci": "ni && nr typecheck && nr lint && nr build && nr test:all",
-    "build": "pnpm -r --filter='./packages/**' run build",
+    "build": "pnpm -r --filter='./packages/**' run build && pnpm -C ./packages/browser run copy",
     "dev": "NODE_OPTIONS=\"--max-old-space-size=8192\" pnpm -r --parallel --filter='./packages/**' run dev",
     "docs": "pnpm -C docs run dev",
     "docs:build": "pnpm -C docs run build",
@@ -28,7 +28,8 @@
     "typecheck:why": "tsc --noEmit --explainFiles > explainTypes.txt",
     "ui:build": "vite build packages/ui",
     "ui:dev": "vite packages/ui",
-    "ui:test": "npm -C packages/ui run test:run"
+    "ui:test": "npm -C packages/ui run test:run",
+    "browser:test": "npm -C test/browser run test"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^0.34.1",

packages/browser/package.json

@@ -24,7 +24,7 @@
     "stubs"
   ],
   "scripts": {
-    "build": "rimraf dist && pnpm build:node && pnpm build:client && pnpm copy",
+    "build": "rimraf dist && pnpm build:node && pnpm build:client",
     "build:client": "vite build src/client",
     "build:node": "rollup -c",
     "dev:client": "vite build src/client --watch",
@@ -33,11 +33,14 @@
     "copy": "esno scripts/copy-ui-to-browser.ts",
     "prepublishOnly": "pnpm build"
   },
+  "peerDependencies": {
+    "vitest": ">=0.30.0"
+  },
   "dependencies": {
     "@vitest/runner": "workspace:*",
     "local-pkg": "^0.4.2",
     "mlly": "^1.1.0",
-    "modern-node-polyfills": "0.0.9",
+    "modern-node-polyfills": "0.1.0",
     "rollup-plugin-node-polyfills": "^0.2.1",
     "sirv": "^2.0.2"
   },