feat(browser): implement connect option for playwright browser provider (#7915)

Co-authored-by: Vladimir <[email protected]>

Author: egfx-notifications

docs/guide/browser/playwright.md

@@ -16,9 +16,9 @@ Alternatively, you can also add it to `compilerOptions.types` field in your `tsc
 }
 ```
 
-Vitest opens a single page to run all tests in the same file. You can configure the `launch` and `context` properties in `instances`:
+Vitest opens a single page to run all tests in the same file. You can configure the `launch`, `connect` and `context` properties in `instances`:
 
-```ts{9-10} [vitest.config.ts]
+```ts{9-11} [vitest.config.ts]
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
@@ -28,6 +28,7 @@ export default defineConfig({
         {
           browser: 'firefox',
           launch: {},
+          connect: {},
           context: {},
         },
       ],
@@ -65,6 +66,14 @@ Vitest will ignore `launch.headless` option. Instead, use [`test.browser.headles
 Note that Vitest will push debugging flags to `launch.args` if [`--inspect`](/guide/cli#inspect) is enabled.
 :::
 
+## connect <Version>3.2.0</Version> {#connect}
+
+These options are directly passed down to `playwright[browser].connect` command. You can read more about the command and available arguments in the [Playwright documentation](https://playwright.dev/docs/api/class-browsertype#browser-type-connect).
+
+::: warning
+Since this command connects to an existing Playwright server, any `launch` options will be ignored.
+:::
+
 ## context
 
 Vitest creates a new context for every test file by calling [`browser.newContext()`](https://playwright.dev/docs/api/class-browsercontext). You can configure this behaviour by specifying [custom arguments](https://playwright.dev/docs/api/class-apirequest#api-request-new-context).

packages/browser/providers/playwright.d.ts

@@ -5,7 +5,8 @@ import type {
   FrameLocator,
   LaunchOptions,
   Page,
-  CDPSession
+  CDPSession,
+  ConnectOptions
 } from 'playwright'
 import { Protocol } from 'playwright-core/types/protocol'
 import '../matchers.js'
@@ -14,6 +15,10 @@ import type {} from "vitest/node"
 declare module 'vitest/node' {
   export interface BrowserProviderOptions {
     launch?: LaunchOptions
+    connect?: {
+      wsEndpoint: string
+      options?: ConnectOptions
+    }
     context?: Omit<
       BrowserContextOptions,
       'ignoreHTTPSErrors' | 'serviceWorkers'

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

@@ -3,6 +3,7 @@ import type {
   Browser,
   BrowserContext,
   BrowserContextOptions,
+  ConnectOptions,
   Frame,
   FrameLocator,
   LaunchOptions,
@@ -18,6 +19,7 @@ import type {
   TestProject,
 } from 'vitest/node'
 import { createManualModuleSource } from '@vitest/mocker/node'
+import c from 'tinyrainbow'
 import { createDebugger } from 'vitest/node'
 
 const debug = createDebugger('vitest:browser:playwright')
@@ -41,6 +43,10 @@ export class PlaywrightBrowserProvider implements BrowserProvider {
 
   private options?: {
     launch?: LaunchOptions
+    connect?: {
+      wsEndpoint: string
+      options?: ConnectOptions
+    }
     context?: BrowserContextOptions & { actionTimeout?: number }
   }
 
@@ -86,6 +92,20 @@ export class PlaywrightBrowserProvider implements BrowserProvider {
 
       const playwright = await import('playwright')
 
+      if (this.options?.connect) {
+        if (this.options.launch) {
+          this.project.vitest.logger.warn(
+            c.yellow(`Found both ${c.bold(c.italic(c.yellow('connect')))} and ${c.bold(c.italic(c.yellow('launch')))} options in browser instance configuration.
+          Ignoring ${c.bold(c.italic(c.yellow('launch')))} options and using ${c.bold(c.italic(c.yellow('connect')))} mode.
+          You probably want to remove one of the two options and keep only the one you want to use.`),
+          )
+        }
+        const browser = await playwright[this.browserName].connect(this.options.connect.wsEndpoint, this.options.connect.options)
+        this.browser = browser
+        this.browserPromise = null
+        return this.browser
+      }
+
       const launchOptions = {
         ...this.options?.launch,
         headless: options.headless,

pnpm-lock.yaml

@@ -0,0 +1,12 @@
+import { test, expect } from 'vitest';
+
+test('[playwright] Run basic test in browser via connect mode', () => {
+  expect(1).toBe(1)
+})
+
+test('[playwright] Run browser-only test in browser via connect mode', () => {
+  const element = document.createElement("div")
+  expect(element instanceof HTMLDivElement).toBe(true)
+  expect(element instanceof HTMLElement).toBe(true)
+  expect(element instanceof HTMLInputElement).not.toBe(true)
+})

test/browser/fixtures/playwright-connect/basic.test.js

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url'
+
+const provider = process.env.PROVIDER || 'playwright'
+
+export default defineConfig({
+  clearScreen: false,
+  cacheDir: fileURLToPath(new URL("./node_modules/.vite", import.meta.url)),
+  test: {
+    browser: {
+      provider: provider,
+      enabled: true,
+      headless: true,
+      screenshotFailures: false,
+    },
+  },
+})

test/browser/fixtures/playwright-connect/vitest.config.js

@@ -31,6 +31,7 @@
     "@vitest/bundled-lib": "link:./bundled-lib",
     "@vitest/cjs-lib": "link:./cjs-lib",
     "@vitest/injected-lib": "link:./injected-lib",
+    "playwright": "^1.52.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "url": "^0.11.4",

test/browser/package.json

@@ -0,0 +1,57 @@
+import { chromium } from 'playwright'
+import { expect, test } from 'vitest'
+import { provider } from '../settings'
+import { runBrowserTests } from './utils'
+
+test.runIf(provider === 'playwright')('[playwright] runs in connect mode', async () => {
+  const browserServer = await chromium.launchServer()
+  const wsEndpoint = browserServer.wsEndpoint()
+
+  const { stdout, exitCode, stderr } = await runBrowserTests({
+    root: './fixtures/playwright-connect',
+    browser: {
+      instances: [
+        {
+          browser: 'chromium',
+          name: 'chromium',
+          connect: {
+            wsEndpoint,
+          },
+        },
+      ],
+    },
+  })
+
+  await browserServer.close()
+
+  expect(stdout).toContain('Tests  2 passed')
+  expect(exitCode).toBe(0)
+  expect(stderr).toBe('')
+})
+
+test.runIf(provider === 'playwright')('[playwright] warns if both connect and launch mode are configured', async () => {
+  const browserServer = await chromium.launchServer()
+  const wsEndpoint = browserServer.wsEndpoint()
+
+  const { stdout, exitCode, stderr } = await runBrowserTests({
+    root: './fixtures/playwright-connect',
+    browser: {
+      instances: [
+        {
+          browser: 'chromium',
+          name: 'chromium',
+          connect: {
+            wsEndpoint,
+          },
+          launch: {},
+        },
+      ],
+    },
+  })
+
+  await browserServer.close()
+
+  expect(stdout).toContain('Tests  2 passed')
+  expect(exitCode).toBe(0)
+  expect(stderr).toContain('Found both connect and launch options in browser instance configuration.')
+})