feat(browser): expose CDP in the browser (#5938)

Author: sheremet-va

docs/guide/browser.md

@@ -453,6 +453,8 @@ export const page: {
    */
   screenshot: (options?: ScreenshotOptions) => Promise<string>
 }
+
+export const cdp: () => CDPSession
 ```
 
 ## Interactivity API
@@ -841,6 +843,29 @@ it('handles files', async () => {
 })
 ```
 
+## CDP Session
+
+Vitest exposes access to raw Chrome Devtools Protocol via the `cdp` method exported from `@vitest/browser/context`. It is mostly useful to library authors to build tools on top of it.
+
+```ts
+import { cdp } from '@vitest/browser/context'
+
+const input = document.createElement('input')
+document.body.appendChild(input)
+input.focus()
+
+await cdp().send('Input.dispatchKeyEvent', {
+  type: 'keyDown',
+  text: 'a',
+})
+
+expect(input).toHaveValue('a')
+```
+
+::: warning
+CDP session works only with `playwright` provider and only when using `chromium` browser. You can read more about it in playwright's [`CDPSession`](https://playwright.dev/docs/api/class-cdpsession) documentation.
+:::
+
 ## Custom Commands
 
 You can also add your own commands via [`browser.commands`](/config/#browser-commands) config option. If you develop a library, you can provide them via a `config` hook inside a plugin:

packages/browser/context.d.ts

@@ -19,6 +19,10 @@ export interface FsOptions {
   flag?: string | number
 }
 
+export interface CDPSession {
+  // methods are defined by the provider type augmentation
+}
+
 export interface ScreenshotOptions {
   element?: Element
   /**
@@ -242,3 +246,4 @@ export interface BrowserPage {
 }
 
 export const page: BrowserPage
+export const cdp: () => CDPSession

packages/browser/providers/playwright.d.ts

@@ -4,7 +4,9 @@ import type {
   Frame,
   LaunchOptions,
   Page,
+  CDPSession
 } from 'playwright'
+import { Protocol } from 'playwright-core/types/protocol'
 import '../matchers.js'
 
 declare module 'vitest/node' {
@@ -40,4 +42,23 @@ declare module '@vitest/browser/context' {
   export interface UserEventDragOptions extends UserEventDragAndDropOptions {}
 
   export interface ScreenshotOptions extends PWScreenshotOptions {}
+
+  export interface CDPSession {
+    send<T extends keyof Protocol.CommandParameters>(
+      method: T,
+      params?: Protocol.CommandParameters[T]
+    ): Promise<Protocol.CommandReturnValues[T]>
+    on<T extends keyof Protocol.Events>(
+      event: T,
+      listener: (payload: Protocol.Events[T]) => void
+    ): this;
+    once<T extends keyof Protocol.Events>(
+      event: T,
+      listener: (payload: Protocol.Events[T]) => void
+    ): this;
+    off<T extends keyof Protocol.Events>(
+      event: T,
+      listener: (payload: Protocol.Events[T]) => void
+    ): this;
+  }
 }

packages/browser/src/client/client.ts

@@ -56,6 +56,13 @@ function createClient() {
         }
         getBrowserState().createTesters?.(files)
       },
+      cdpEvent(event: string, payload: unknown) {
+        const cdp = getBrowserState().cdp
+        if (!cdp) {
+          return
+        }
+        cdp.emit(event, payload)
+      },
     },
     {
       post: msg => ctx.ws.send(msg),

packages/browser/src/client/tester/context.ts

@@ -163,6 +163,10 @@ function getSimpleSelectOptions(element: Element, value: string | string[] | HTM
   })
 }
 
+export function cdp() {
+  return runner().cdp!
+}
+
 const screenshotIds: Record<string, Record<string, string>> = {}
 export const page: BrowserPage = {
   get config() {

packages/browser/src/client/tester/state.ts

@@ -1,8 +1,10 @@
 import type { WorkerGlobalState } from 'vitest'
 import { parse } from 'flatted'
 import { getBrowserState } from '../utils'
+import type { BrowserRPC } from '../client'
 
 const config = getBrowserState().config
+const contextId = getBrowserState().contextId
 
 const providedContext = parse(getBrowserState().providedContext)
 
@@ -44,3 +46,71 @@ const state: WorkerGlobalState = {
 globalThis.__vitest_browser__ = true
 // @ts-expect-error not typed global
 globalThis.__vitest_worker__ = state
+
+getBrowserState().cdp = createCdp()
+
+function rpc() {
+  return state.rpc as any as BrowserRPC
+}
+
+function createCdp() {
+  const listenersMap = new WeakMap<Function, string>()
+
+  function getId(listener: Function) {
+    const id = listenersMap.get(listener) || crypto.randomUUID()
+    listenersMap.set(listener, id)
+    return id
+  }
+
+  const listeners: Record<string, Function[]> = {}
+
+  const error = (err: unknown) => {
+    window.dispatchEvent(new ErrorEvent('error', { error: err }))
+  }
+
+  const cdp = {
+    send(method: string, params?: Record<string, any>) {
+      return rpc().sendCdpEvent(contextId, method, params)
+    },
+    on(event: string, listener: (payload: any) => void) {
+      const listenerId = getId(listener)
+      listeners[event] = listeners[event] || []
+      listeners[event].push(listener)
+      rpc().trackCdpEvent(contextId, 'on', event, listenerId).catch(error)
+      return cdp
+    },
+    once(event: string, listener: (payload: any) => void) {
+      const listenerId = getId(listener)
+      const handler = (data: any) => {
+        listener(data)
+        cdp.off(event, listener)
+      }
+      listeners[event] = listeners[event] || []
+      listeners[event].push(handler)
+      rpc().trackCdpEvent(contextId, 'once', event, listenerId).catch(error)
+      return cdp
+    },
+    off(event: string, listener: (payload: any) => void) {
+      const listenerId = getId(listener)
+      if (listeners[event]) {
+        listeners[event] = listeners[event].filter(l => l !== listener)
+      }
+      rpc().trackCdpEvent(contextId, 'off', event, listenerId).catch(error)
+      return cdp
+    },
+    emit(event: string, payload: unknown) {
+      if (listeners[event]) {
+        listeners[event].forEach((l) => {
+          try {
+            l(payload)
+          }
+          catch (err) {
+            error(err)
+          }
+        })
+      }
+    },
+  }
+
+  return cdp
+}

packages/browser/src/client/utils.ts

@@ -25,6 +25,13 @@ export interface BrowserRunnerState {
   contextId: string
   runTests?: (tests: string[]) => Promise<void>
   createTesters?: (files: string[]) => Promise<void>
+  cdp?: {
+    on: (event: string, listener: (payload: any) => void) => void
+    once: (event: string, listener: (payload: any) => void) => void
+    off: (event: string, listener: (payload: any) => void) => void
+    send: (method: string, params?: Record<string, unknown>) => Promise<unknown>
+    emit: (event: string, payload: unknown) => void
+  }
 }
 
 /* @__NO_SIDE_EFFECTS__ */

packages/browser/src/node/cdp.ts

@@ -0,0 +1,58 @@
+import type { CDPSession } from 'vitest/node'
+import type { WebSocketBrowserRPC } from './types'
+
+export class BrowserServerCDPHandler {
+  private listenerIds: Record<string, string[]> = {}
+
+  private listeners: Record<string, (payload: unknown) => void> = {}
+
+  constructor(
+    private session: CDPSession,
+    private tester: WebSocketBrowserRPC,
+  ) {}
+
+  send(method: string, params?: Record<string, unknown>) {
+    return this.session.send(method, params)
+  }
+
+  detach() {
+    return this.session.detach()
+  }
+
+  on(event: string, id: string, once = false) {
+    if (!this.listenerIds[event]) {
+      this.listenerIds[event] = []
+    }
+    this.listenerIds[event].push(id)
+
+    if (!this.listeners[event]) {
+      this.listeners[event] = (payload) => {
+        this.tester.cdpEvent(
+          event,
+          payload,
+        )
+        if (once) {
+          this.off(event, id)
+        }
+      }
+
+      this.session.on(event, this.listeners[event])
+    }
+  }
+
+  off(event: string, id: string) {
+    if (!this.listenerIds[event]) {
+      this.listenerIds[event] = []
+    }
+    this.listenerIds[event] = this.listenerIds[event].filter(l => l !== id)
+
+    if (!this.listenerIds[event].length) {
+      this.session.off(event, this.listeners[event])
+      delete this.listeners[event]
+    }
+  }
+
+  once(event: string, listener: string) {
+    this.on(event, listener, true)
+  }
+}

packages/browser/src/node/plugin.ts

@@ -182,7 +182,7 @@ export default (browserServer: BrowserServer, base = '/'): Plugin[] => {
         if (rawId.startsWith('/__virtual_vitest__')) {
           const url = new URL(rawId, 'http://localhost')
           if (!url.searchParams.has('id')) {
-            throw new TypeError(`Invalid virtual module id: ${rawId}, requires "id" query.`)
+            return
           }
 
           const id = decodeURIComponent(url.searchParams.get('id')!)

packages/browser/src/node/plugins/pluginContext.ts

@@ -67,7 +67,7 @@ async function generateContextFile(
   const distContextPath = slash(`/@fs/${resolve(__dirname, 'context.js')}`)
 
   return `
-import { page, userEvent as __userEvent_CDP__ } from '${distContextPath}'
+import { page, userEvent as __userEvent_CDP__, cdp } from '${distContextPath}'
 ${userEventNonProviderImport}
 const filepath = () => ${filepathCode}
 const rpc = () => __vitest_worker__.rpc
@@ -84,7 +84,7 @@ export const server = {
 }
 export const commands = server.commands
 export const userEvent = ${getUserEvent(provider)}
-export { page }
+export { page, cdp }
 `
 }
 

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

@@ -130,6 +130,29 @@ export class PlaywrightBrowserProvider implements BrowserProvider {
     await browserPage.goto(url)
   }
 
+  async getCDPSession(contextId: string) {
+    const page = this.getPage(contextId)
+    const cdp = await page.context().newCDPSession(page)
+    return {
+      async send(method: string, params: any) {
+        const result = await cdp.send(method as 'DOM.querySelector', params)
+        return result as unknown
+      },
+      on(event: string, listener: (...args: any[]) => void) {
+        cdp.on(event as 'Accessibility.loadComplete', listener)
+      },
+      off(event: string, listener: (...args: any[]) => void) {
+        cdp.off(event as 'Accessibility.loadComplete', listener)
+      },
+      once(event: string, listener: (...args: any[]) => void) {
+        cdp.once(event as 'Accessibility.loadComplete', listener)
+      },
+      detach() {
+        return cdp.detach()
+      },
+    }
+  }
+
   async close() {
     const browser = this.browser
     this.browser = null

packages/browser/src/node/rpc.ts

@@ -40,7 +40,7 @@ export function setupBrowserRpc(
     wss.handleUpgrade(request, socket, head, (ws) => {
       wss.emit('connection', ws, request)
 
-      const rpc = setupClient(ws)
+      const rpc = setupClient(sessionId, ws)
       const state = server.state
       const clients = type === 'tester' ? state.testers : state.orchestrators
       clients.set(sessionId, rpc)
@@ -50,6 +50,7 @@ export function setupBrowserRpc(
       ws.on('close', () => {
         debug?.('[%s] Browser API disconnected from %s', sessionId, type)
         clients.delete(sessionId)
+        server.state.removeCDPHandler(sessionId)
       })
     })
   })
@@ -62,7 +63,7 @@ export function setupBrowserRpc(
     }
   }
 
-  function setupClient(ws: WebSocket) {
+  function setupClient(sessionId: string, ws: WebSocket) {
     const rpc = createBirpc<WebSocketBrowserEvents, WebSocketBrowserHandlers>(
       {
         async onUnhandledError(error, type) {
@@ -182,11 +183,21 @@ export function setupBrowserRpc(
             }
           })
         },
+
+        // CDP
+        async sendCdpEvent(contextId: string, event: string, payload?: Record<string, unknown>) {
+          const cdp = await server.ensureCDPHandler(contextId, sessionId)
+          return cdp.send(event, payload)
+        },
+        async trackCdpEvent(contextId: string, type: 'on' | 'once' | 'off', event: string, listenerId: string) {
+          const cdp = await server.ensureCDPHandler(contextId, sessionId)
+          cdp[type](event, listenerId)
+        },
       },
       {
         post: msg => ws.send(msg),
         on: fn => ws.on('message', fn),
-        eventNames: ['onCancel'],
+        eventNames: ['onCancel', 'cdpEvent'],
         serialize: (data: any) => stringify(data, stringifyReplace),
         deserialize: parse,
         onTimeoutError(functionName) {