feat: playwright as browser provider (#3079)

Co-authored-by: Vladimir Sheremet <sleuths.slews0s@icloud.com>

Author: Aslemammad

.github/workflows/ci.yml

@@ -106,12 +106,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        browser: [chrome, firefox, edge]
+        browser: [[chrome, chromium], [firefox, firefox], [edge, webkit]]
 
     timeout-minutes: 10
 
     env:
-      BROWSER: ${{ matrix.browser }}
+      BROWSER: ${{ matrix.browser[0] }}
     steps:
       - uses: actions/checkout@v3
 
@@ -126,36 +126,42 @@ jobs:
       - name: Install
         run: pnpm i
 
+      - name: Install Playwright Dependencies
+        run: pnpx playwright install-deps
+
       - name: Build
         run: pnpm run build
 
-      - name: Test Browser
-        run: pnpm run browser:test
+      - name: Test Browser (webdriverio)
+        run: pnpm run test:browser:webdriverio
+
+      - name: Test Browser (playwright)
+        run: pnpm run test:browser:playwright
+        env:
+          BROWSER: ${{ matrix.browser[1] }}
 
   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
+        run: sudo pnpm i
 
       - name: Build
-        run: pnpm run build
+        run: sudo pnpm run build
 
       - name: Enable
         run: sudo safaridriver --enable
 
-      - name: Test Browser
-        run: sudo pnpm run browser:test
+      - name: Test Browser (webdriverio)
+        run: sudo BROWSER=safari pnpm run test:browser:webdriverio
+
+      - name: Test Browser (playwright)
+        run: sudo BROWSER=webkit pnpm run test:browser:playwright

docs/config/index.md

@@ -1001,7 +1001,7 @@ Listen to port and serve API. When set to true, the default port is 51204
 - **Version:** Since Vitest 0.29.4
 - **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.
+Run Vitest tests in a browser. 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).
@@ -1022,11 +1022,13 @@ Run all tests inside a browser by default. Can be overriden with [`poolMatchGlob
 #### 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.
+Run all tests in a specific browser. Possible options in different providers:
 
+- `webdriverio`: `firefox`, `chrome`, `edge`, `safari`
+- `playwright`: `firefox`, `webkit`, `chromium`
+- custom: any string that will be passed to the provider
 
 #### browser.headless
 
@@ -1046,21 +1048,19 @@ Configure options for Vite server that serves code in the browser. Does not affe
 
 #### browser.provider
 
-- **Type:** `string`
+- **Type:** `'webdriverio' | 'playwright' | string`
 - **Default:** `'webdriverio'`
-- **CLI:** `--browser.provider=./custom-provider.ts`
+- **CLI:** `--browser.provider=playwright`
 
-Path to a provider that will be used when running browser tests. Provider should be exported using `default` export and have this shape:
+Path to a provider that will be used when running browser tests. Vitest provides two providers which are `webdriverio` (default) and `playwright`. Custom providers 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>
+  name: string
+  getSupportedBrowsers(): readonly string[]
+  initialize(ctx: Vitest, options: { browser: string }): Awaitable<void>
+  openPage(url: string): Awaitable<void>
+  close(): Awaitable<void>
 }
 ```
 

docs/guide/browser.md

@@ -14,32 +14,26 @@ To activate browser mode in your Vitest configuration, you can use the `--browse
 export default defineConfig({
   test: {
     browser: {
-      enabled: true
+      enabled: true,
+      name: 'chrome', // browser name is required
     },
   }
 })
 ```
 
 ## 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:
+The browser option in Vitest depends on the provider. Vitest will fail, if you pass `--browser` and don't specify its name in the config file. Available options:
 
-```ts
-export default defineConfig({
-  test: {
-    browser: {
-      enabled: true,
-      name: 'chrome',
-    },
-  }
-})
-```
+- `webdriverio` (default) supports these browsers:
+  - `firefox`
+  - `chrome`
+  - `edge`
+  - `safari`
+- `playwright` supports these browsers:
+  - `firefox`
+  - `webkit`
+  - `chromium`
 
 ## Cross-browser Testing:
 
@@ -58,7 +52,7 @@ 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.
+When using the Safari browser option with WebdriverIO, 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`.
 :::

package.json

@@ -29,7 +29,8 @@
     "ui:build": "vite build packages/ui",
     "ui:dev": "vite packages/ui",
     "ui:test": "npm -C packages/ui run test:run",
-    "browser:test": "npm -C test/browser run test"
+    "test:browser:webdriverio": "npm -C test/browser run test:webdriverio",
+    "test:browser:playwright": "npm -C test/browser run test:playwright"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^0.34.1",

packages/vitest/package.json

@@ -102,7 +102,10 @@
     "@vitest/browser": "*",
     "@vitest/ui": "*",
     "happy-dom": "*",
-    "jsdom": "*"
+    "jsdom": "*",
+    "playwright": "*",
+    "safaridriver": "*",
+    "webdriverio": "*"
   },
   "peerDependenciesMeta": {
     "@vitest/ui": {
@@ -123,6 +126,9 @@
     "safaridriver": {
       "optional": true
     },
+    "playwright": {
+      "optional": true
+    },
     "@edge-runtime/vm": {
       "optional": true
     }
@@ -186,6 +192,7 @@
     "natural-compare": "^1.4.0",
     "p-limit": "^4.0.0",
     "pkg-types": "^1.0.1",
+    "playwright": "^1.28.0",
     "pretty-format": "^27.5.1",
     "prompts": "^2.4.2",
     "rollup": "^2.79.1",

packages/vitest/rollup.config.js

@@ -53,6 +53,7 @@ const external = [
   'inspector',
   'webdriverio',
   'safaridriver',
+  'playwright',
   'vite-node/source-map',
   'vite-node/client',
   'vite-node/server',

packages/vitest/src/api/setup.ts

@@ -36,7 +36,7 @@ export function setup(ctx: Vitest, server?: ViteDevServer) {
     const rpc = createBirpc<WebSocketEvents, WebSocketHandlers>(
       {
         async onDone(testId) {
-          await ctx.browserProvider?.testFinished?.(testId)
+          return ctx.state.browserTestPromises.get(testId)?.resolve(true)
         },
         async onCollected(files) {
           ctx.state.collectFiles(files)

packages/vitest/src/defaults.ts

@@ -39,11 +39,6 @@ export const coverageConfigDefaults: ResolvedCoverageOptions = {
   extension: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte'],
 }
 
-export const browserConfigDefaults = {
-  enabled: false,
-  headless: isCI,
-} as const
-
 export const fakeTimersDefaults = {
   loopLimit: 10_000,
   shouldClearNativeTimers: true,
@@ -73,7 +68,6 @@ const config = {
   hookTimeout: 10000,
   teardownTimeout: 10000,
   isolate: true,
-  browser: browserConfigDefaults,
   watchExclude: ['**/node_modules/**', '**/dist/**'],
   forceRerunTriggers: [
     '**/package.json/**',

packages/vitest/src/integrations/browser.ts

@@ -1,3 +1,4 @@
+import { PlaywrightBrowserProvider } from '../node/browser/playwright'
 import { WebdriverBrowserProvider } from '../node/browser/webdriver'
 import type { BrowserProviderModule, ResolvedBrowserOptions } from '../types/browser'
 
@@ -6,8 +7,17 @@ interface Loader {
 }
 
 export async function getBrowserProvider(options: ResolvedBrowserOptions, loader: Loader): Promise<BrowserProviderModule> {
-  if (!options.provider || options.provider === 'webdriverio')
-    return WebdriverBrowserProvider
+  switch (options.provider) {
+    case undefined:
+    case 'webdriverio':
+      return WebdriverBrowserProvider
+
+    case 'playwright':
+      return PlaywrightBrowserProvider
+
+    default:
+      break
+  }
 
   let customProviderModule
 

packages/vitest/src/node/browser/playwright.ts

@@ -0,0 +1,63 @@
+import type { Page } from 'playwright'
+import type { BrowserProvider, BrowserProviderOptions } from '../../types/browser'
+import { ensurePackageInstalled } from '../pkg'
+import type { Vitest } from '../core'
+
+export const playwrightBrowsers = ['firefox', 'webkit', 'chromium'] as const
+export type PlaywrightBrowser = typeof playwrightBrowsers[number]
+
+export interface PlaywrightProviderOptions extends BrowserProviderOptions {
+  browser: PlaywrightBrowser
+}
+
+export class PlaywrightBrowserProvider implements BrowserProvider {
+  public name = 'playwright'
+
+  private cachedBrowser: Page | null = null
+  private browser!: PlaywrightBrowser
+  private ctx!: Vitest
+
+  getSupportedBrowsers() {
+    return playwrightBrowsers
+  }
+
+  async initialize(ctx: Vitest, { browser }: PlaywrightProviderOptions) {
+    this.ctx = ctx
+    this.browser = browser
+
+    const root = this.ctx.config.root
+
+    if (!await ensurePackageInstalled('playwright', root))
+      throw new Error('Cannot find "playwright" package. Please install it manually.')
+  }
+
+  async openBrowser() {
+    if (this.cachedBrowser)
+      return this.cachedBrowser
+
+    const options = this.ctx.config.browser
+
+    const playwright = await import('playwright')
+
+    const playwrightInstance = await playwright[this.browser].launch({ headless: options.headless })
+    this.cachedBrowser = await playwrightInstance.newPage()
+
+    this.cachedBrowser.on('close', () => {
+      playwrightInstance.close()
+    })
+
+    return this.cachedBrowser
+  }
+
+  async openPage(url: string) {
+    const browserInstance = await this.openBrowser()
+    await browserInstance.goto(url)
+  }
+
+  async close() {
+    await this.cachedBrowser?.close()
+    // TODO: right now process can only exit with timeout, if we use browser
+    // needs investigating
+    process.exit()
+  }
+}