feat(browser): run tests in parallel in headless mode, add page.screenshot method (#5853)

Author: sheremet-va

docs/guide/browser.md

@@ -236,6 +236,11 @@ export const page: {
    * Change the size of iframe's viewport.
    */
   viewport: (width: number | string, height: number | string) => Promise<void>
+  /**
+   * Make a screenshot of the test iframe or a specific element.
+   * @returns Path to the screenshot file.
+   */
+  screenshot: (options?: ScreenshotOptions) => Promise<string>
 }
 ```
 
@@ -360,6 +365,63 @@ declare module '@vitest/browser/context' {
 Custom functions will override built-in ones if they have the same name.
 :::
 
+### Custom `playwright` commands
+
+Vitest exposes several `playwright` specific properties on the command context.
+
+- `page` references the full page that contains the test iframe. This is the orchestrator HTML and you most likely shouldn't touch it to not break things.
+- `tester` is the iframe locator. The API is pretty limited here, but you can chain it further to access your HTML elements.
+- `body` is the iframe's `body` locator that exposes more Playwright APIs.
+
+```ts
+import { defineCommand } from '@vitest/browser'
+
+export const myCommand = defineCommand(async (ctx, arg1, arg2) => {
+  if (ctx.provider.name === 'playwright') {
+    const element = await ctx.tester.findByRole('alert')
+    const screenshot = await element.screenshot()
+    // do something with the screenshot
+    return difference
+  }
+})
+```
+
+::: tip
+If you are using TypeScript, don't forget to add `@vitest/browser/providers/playwright` to your `tsconfig` "compilerOptions.types" field to get autocompletion:
+
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@vitest/browser/providers/playwright"
+    ]
+  }
+}
+```
+:::
+
+### Custom `webdriverio` commands
+
+Vitest exposes some `webdriverio` specific properties on the context object.
+
+- `browser` is the `WebdriverIO.Browser` API.
+
+Vitest automatically switches the `webdriver` context to the test iframe by calling `browser.switchToFrame` before the command is called, so `$` and `$$` methods refer to the elements inside the iframe, not in the orchestrator, but non-webdriver APIs will still refer to the parent frame context.
+
+::: tip
+If you are using TypeScript, don't forget to add `@vitest/browser/providers/webdriverio` to your `tsconfig` "compilerOptions.types" field to get autocompletion:
+
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@vitest/browser/providers/webdriverio"
+    ]
+  }
+}
+```
+:::
+
 ## Limitations
 
 ### Thread Blocking Dialogs

eslint.config.js

@@ -44,6 +44,7 @@ export default antfu(
       // let TypeScript handle this
       'no-undef': 'off',
       'ts/no-invalid-this': 'off',
+      'eslint-comments/no-unlimited-disable': 'off',
 
       // TODO: migrate and turn it back on
       'ts/ban-types': 'off',

packages/browser/context.d.ts

@@ -26,6 +26,14 @@ export interface UpPayload { up: string }
 
 export type SendKeysPayload = TypePayload | PressPayload | DownPayload | UpPayload
 
+export interface ScreenshotOptions {
+  element?: Element
+  /**
+   * Path relative to the `screenshotDirectory` in the test config.
+   */
+  path?: string
+}
+
 export interface BrowserCommands {
   readFile: (path: string, options?: BufferEncoding | FsOptions) => Promise<string>
   writeFile: (path: string, content: string, options?: BufferEncoding | FsOptions & { mode?: number | string }) => Promise<void>
@@ -100,7 +108,7 @@ export const userEvent: UserEvent
  */
 export const commands: BrowserCommands
 
-export const page: {
+export interface BrowserPage {
   /**
    * Serialized test config.
    */
@@ -109,4 +117,11 @@ export const page: {
    * Change the size of iframe's viewport.
    */
   viewport: (width: number, height: number) => Promise<void>
+  /**
+   * Make a screenshot of the test iframe or a specific element.
+   * @returns Path to the screenshot file.
+   */
+  screenshot: (options?: ScreenshotOptions) => Promise<string>
 }
+
+export const page: BrowserPage

packages/browser/package.json

@@ -73,6 +73,7 @@
     "@testing-library/user-event": "^14.5.2",
     "@vitest/utils": "workspace:*",
     "magic-string": "^0.30.10",
+    "msw": "^2.3.1",
     "sirv": "^2.0.4"
   },
   "devDependencies": {
@@ -83,6 +84,7 @@
     "@wdio/protocols": "^8.38.0",
     "birpc": "0.2.17",
     "flatted": "^3.3.1",
+    "pathe": "^1.1.2",
     "periscopic": "^4.0.2",
     "playwright": "^1.44.1",
     "playwright-core": "^1.44.1",

packages/browser/providers/playwright.d.ts

@@ -1,8 +1,20 @@
-import type { Browser, LaunchOptions } from 'playwright'
+import type {
+  BrowserContextOptions,
+  FrameLocator,
+  LaunchOptions,
+  Locator,
+  Page,
+} from 'playwright'
 
 declare module 'vitest/node' {
   interface BrowserProviderOptions {
     launch?: LaunchOptions
-    page?: Parameters<Browser['newPage']>[0]
+    context?: Omit<BrowserContextOptions, 'ignoreHTTPSErrors' | 'serviceWorkers'>
+  }
+
+  export interface BrowserCommandContext {
+    page: Page
+    tester: FrameLocator
+    body: Locator
   }
 }

packages/browser/providers/webdriverio.d.ts

@@ -2,4 +2,8 @@ import type { RemoteOptions } from 'webdriverio'
 
 declare module 'vitest/node' {
   interface BrowserProviderOptions extends RemoteOptions {}
+
+  export interface BrowserCommandContext {
+    browser: WebdriverIO.Browser
+  }
 }

packages/browser/rollup.config.js

@@ -4,6 +4,7 @@ import dts from 'rollup-plugin-dts'
 import resolve from '@rollup/plugin-node-resolve'
 import commonjs from '@rollup/plugin-commonjs'
 import json from '@rollup/plugin-json'
+import { defineConfig } from 'rollup'
 
 const require = createRequire(import.meta.url)
 const pkg = require('./package.json')
@@ -32,7 +33,7 @@ const input = {
   providers: './src/node/providers/index.ts',
 }
 
-export default () => [
+export default () => defineConfig([
   {
     input,
     output: {
@@ -42,6 +43,18 @@ export default () => [
     external,
     plugins,
   },
+  {
+    input: './src/client/context.ts',
+    output: {
+      file: 'dist/context.js',
+      format: 'esm',
+    },
+    plugins: [
+      esbuild({
+        target: 'node18',
+      }),
+    ],
+  },
   {
     input: input.index,
     output: {
@@ -51,4 +64,4 @@ export default () => [
     external,
     plugins: [dts()],
   },
-]
+])

packages/browser/src/client/channel.ts

@@ -0,0 +1,90 @@
+import { getBrowserState } from './utils'
+
+export interface IframeDoneEvent {
+  type: 'done'
+  filenames: string[]
+  id: string
+}
+
+export interface IframeErrorEvent {
+  type: 'error'
+  error: any
+  errorType: string
+  files: string[]
+  id: string
+}
+
+export interface IframeViewportEvent {
+  type: 'viewport'
+  width: number
+  height: number
+  id: string
+}
+
+export interface IframeMockEvent {
+  type: 'mock'
+  paths: string[]
+  mock: string | undefined | null
+}
+
+export interface IframeUnmockEvent {
+  type: 'unmock'
+  paths: string[]
+}
+
+export interface IframeMockingDoneEvent {
+  type: 'mock:done' | 'unmock:done'
+}
+
+export interface IframeMockFactoryRequestEvent {
+  type: 'mock-factory:request'
+  id: string
+}
+
+export interface IframeMockFactoryResponseEvent {
+  type: 'mock-factory:response'
+  exports: string[]
+}
+
+export interface IframeMockFactoryErrorEvent {
+  type: 'mock-factory:error'
+  error: any
+}
+
+export interface IframeViewportChannelEvent {
+  type: 'viewport:done' | 'viewport:fail'
+}
+
+export interface IframeMockInvalidateEvent {
+  type: 'mock:invalidate'
+}
+
+export type IframeChannelIncomingEvent =
+  | IframeViewportEvent
+  | IframeErrorEvent
+  | IframeDoneEvent
+  | IframeMockEvent
+  | IframeUnmockEvent
+  | IframeMockFactoryResponseEvent
+  | IframeMockFactoryErrorEvent
+  | IframeMockInvalidateEvent
+
+export type IframeChannelOutgoingEvent =
+  | IframeMockFactoryRequestEvent
+  | IframeViewportChannelEvent
+  | IframeMockingDoneEvent
+
+export type IframeChannelEvent =
+  | IframeChannelIncomingEvent
+  | IframeChannelOutgoingEvent
+
+export const channel = new BroadcastChannel(`vitest:${getBrowserState().contextId}`)
+
+export function waitForChannel(event: IframeChannelOutgoingEvent['type']) {
+  return new Promise<void>((resolve) => {
+    channel.addEventListener('message', (e) => {
+      if (e.data?.type === event)
+        resolve()
+    }, { once: true })
+  })
+}

packages/browser/src/client/client.ts

@@ -9,7 +9,9 @@ const PAGE_TYPE = getBrowserState().type
 
 export const PORT = import.meta.hot ? '51204' : location.port
 export const HOST = [location.hostname, PORT].filter(Boolean).join(':')
-export const SESSION_ID = crypto.randomUUID()
+export const SESSION_ID = PAGE_TYPE === 'orchestrator'
+  ? getBrowserState().contextId
+  : crypto.randomUUID()
 export const ENTRY_URL = `${
   location.protocol === 'https:' ? 'wss:' : 'ws:'
 }//${HOST}/__vitest_browser_api__?type=${PAGE_TYPE}&sessionId=${SESSION_ID}`
@@ -25,7 +27,7 @@ export interface VitestBrowserClient {
   waitForConnection: () => Promise<void>
 }
 
-type BrowserRPC = BirpcReturn<WebSocketBrowserHandlers, WebSocketBrowserEvents>
+export type BrowserRPC = BirpcReturn<WebSocketBrowserHandlers, WebSocketBrowserEvents>
 
 function createClient() {
   const autoReconnect = true
@@ -120,4 +122,5 @@ function createClient() {
 }
 
 export const client = createClient()
-export const channel = new BroadcastChannel('vitest')
+
+export { channel, waitForChannel } from './channel'