Devtools screencast feature followup

vishnuv688 · vishnuv688 · commit 9726be73ede7 · 2026-04-14T17:08:13.000+05:30
diff --git a/example/wdio.conf.ts b/example/wdio.conf.ts
@@ -63,7 +63,7 @@ export const config: Options.Testrunner = {
   capabilities: [
     {
       browserName: 'chrome',
-      browserVersion: '146.0.7680.178', // specify chromium browser version for testing
+      browserVersion: '147.0.7727.56', // specify chromium browser version for testing
       'goog:chromeOptions': {
         args: [
           '--headless',
@@ -127,7 +127,20 @@ export const config: Options.Testrunner = {
   // Services take over a specific job you don't want to take care of. They enhance
   // your test setup with almost no effort. Unlike plugins, they don't add new
   // commands. Instead, they hook themselves up into the test process.
-  services: ['devtools'],
+  services: [
+    [
+      'devtools',
+      {
+        screencast: {
+          enabled: true,
+          captureFormat: 'jpeg', // 'jpeg' or 'png' — frame format sent by Chrome over CDP
+          quality: 70, // JPEG quality 0–100
+          maxWidth: 1280, // max frame width in px
+          maxHeight: 720 // max frame height in px
+        }
+      }
+    ]
+  ],
   //
   // Framework you want to run your specs with.
   // The following are supported: Mocha, Jasmine, and Cucumber
diff --git a/packages/service/README.md b/packages/service/README.md
@@ -1,32 +1,122 @@
 
 # @wdio/devtools-service
 
-DevTools is a UI test runner for WebdriverIO. It provides a user interface for running, debugging, and inspecting your browser automation tests, along with advanced features like network interception, performance tracing, and more.
+A WebdriverIO service that provides a developer tools UI for running, debugging, and inspecting browser automation tests. Features include DOM mutation replay, per-command screenshots, network request inspection, console log capture, and session screencast recording.
 
 ## Installation
 
-Install the service in your project:
-
 ```sh
 npm install @wdio/devtools-service --save-dev
-```
-
-or with pnpm:
-
-```sh
+# or
 pnpm add -D @wdio/devtools-service
 ```
 
 ## Usage
 
-### WebdriverIO Test Runner
+### Test Runner
 
-Add the service to your `wdio.conf.ts`:
-
-```js
+```ts
+// wdio.conf.ts
 export const config = {
-  // ...
   services: ['devtools'],
-  // ...
 }
 ```
+
+### Standalone
+
+```ts
+import { remote } from 'webdriverio'
+import { setupForDevtools } from '@wdio/devtools-service'
+
+const browser = await remote(setupForDevtools({
+  capabilities: { browserName: 'chrome' }
+}))
+await browser.url('https://example.com')
+await browser.deleteSession()
+```
+
+## Service Options
+
+```ts
+services: [['devtools', options]]
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `port` | `number` | random | Port the DevTools UI server listens on |
+| `hostname` | `string` | `'localhost'` | Hostname the DevTools UI server binds to |
+| `devtoolsCapabilities` | `Capabilities` | Chrome 1600×1200 | Capabilities used to open the DevTools UI window |
+| `screencast` | `ScreencastOptions` | — | Session video recording (see below) |
+
+## Screencast Recording
+
+Records browser sessions as `.webm` videos using the Chrome DevTools Protocol. Videos are displayed in the DevTools UI alongside the snapshot and DOM mutation views.
+
+### Setup
+
+Screencast encoding requires **ffmpeg** on `PATH` and the `fluent-ffmpeg` package:
+
+```sh
+# Install ffmpeg — https://ffmpeg.org/download.html
+brew install ffmpeg        # macOS
+sudo apt install ffmpeg    # Ubuntu/Debian
+
+# Install fluent-ffmpeg
+npm install fluent-ffmpeg
+```
+
+### Configuration
+
+```ts
+services: [
+  [
+    'devtools',
+    {
+      screencast: {
+        enabled: true,
+        captureFormat: 'jpeg',
+        quality: 70,
+        maxWidth: 1280,
+        maxHeight: 720,
+      }
+    }
+  ]
+]
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | Enable session recording |
+| `captureFormat` | `'jpeg' \| 'png'` | `'jpeg'` | Frame image format. **Chrome/Chromium only** — controls the format Chrome sends over CDP. Ignored in polling mode (Firefox, Safari) where screenshots are always PNG. Does not affect the output video container, which is always `.webm` |
+| `quality` | `number` | `70` | JPEG compression quality 0–100. Only applies in Chrome/Chromium CDP mode with `captureFormat: 'jpeg'` |
+| `maxWidth` | `number` | `1280` | Maximum frame width in pixels. **Chrome/Chromium only** — Chrome scales frames before sending over CDP. Ignored in polling mode |
+| `maxHeight` | `number` | `720` | Maximum frame height in pixels. **Chrome/Chromium only** — same as above |
+| `pollIntervalMs` | `number` | `200` | Screenshot interval in milliseconds for non-Chrome browsers (polling mode). Lower = smoother video but more WebDriver round-trips during test execution |
+
+### Browser support
+
+Recording works across all major browsers using automatic mode selection:
+
+| Browser | Mode | Notes |
+|---|---|---|
+| Chrome / Chromium / Edge | **CDP push** | Chrome pushes frames over the DevTools Protocol. Efficient — no impact on test command timing |
+| Firefox / Safari / others | **BiDi polling** | Falls back to calling `browser.takeScreenshot()` at `pollIntervalMs` intervals. Works wherever WebDriver screenshots are supported; adds a small overhead proportional to the interval |
+
+No configuration change is needed to switch modes — the service detects browser capabilities automatically and logs which mode is active.
+
+### Behaviour
+
+- Recording starts when the browser session opens and stops when it closes.
+- Leading blank frames (captured before the first URL navigation) are automatically trimmed so videos begin at the first meaningful page action.
+- If `browser.reloadSession()` is called mid-run, the service finalises the current recording and starts a fresh one for the new session. Each session produces its own `.webm` file.
+- When multiple recordings exist, the DevTools UI shows a **Recording N** dropdown to switch between them.
+- Output files are written to the directory containing `wdio.conf.ts` (WDIO's `rootDir`) or `outputDir` if explicitly configured.
+
+### Output files
+
+| File | Description |
+|---|---|
+| `wdio-trace-{sessionId}.json` | Full trace: DOM mutations, commands, screenshots, console logs, network requests |
+| `wdio-video-{sessionId}.webm` | Screencast video (only produced when `screencast.enabled: true`) |
diff --git a/packages/service/src/constants.ts b/packages/service/src/constants.ts
@@ -1,3 +1,14 @@
+import type { ScreencastOptions } from './types.js'
+
+export const SCREENCAST_DEFAULTS: Required<ScreencastOptions> = {
+  enabled: false,
+  captureFormat: 'jpeg',
+  quality: 70,
+  maxWidth: 1280,
+  maxHeight: 720,
+  pollIntervalMs: 200
+}
+
 export const PAGE_TRANSITION_COMMANDS: string[] = [
   'url',
   'navigateTo',
@@ -32,7 +43,7 @@ export const LOG_LEVEL_PATTERNS: ReadonlyArray<{
 /**
  * Visual indicators that suggest error-level logs
  */
-export const ERROR_INDICATORS = ['✗', '✓', 'failed', 'failure'] as const
+export const ERROR_INDICATORS = ['✗', 'failed', 'failure'] as const
 
 /**
  * Console log source types
diff --git a/packages/service/src/index.ts b/packages/service/src/index.ts
@@ -11,8 +11,16 @@ import { SessionCapturer } from './session.js'
 import { TestReporter } from './reporter.js'
 import { DevToolsAppLauncher } from './launcher.js'
 import { getBrowserObject } from './utils.js'
+import { ScreencastRecorder } from './screencast.js'
+import { encodeToVideo } from './video-encoder.js'
 import { parse } from 'stack-trace'
-import { type TraceLog, TraceType, type ServiceOptions } from './types.js'
+import {
+  type TraceLog,
+  TraceType,
+  type ServiceOptions,
+  type ScreencastOptions,
+  type ScreencastInfo
+} from './types.js'
 import {
   INTERNAL_COMMANDS,
   SPEC_FILE_PATTERN,
@@ -89,6 +97,12 @@ export default class DevToolsHookService implements Services.ServiceInstance {
   #sessionCapturer = new SessionCapturer()
   #browser?: WebdriverIO.Browser
   #bidiListenersSetup = false
+  #screencastRecorder?: ScreencastRecorder
+  #screencastOptions?: ScreencastOptions
+
+  constructor(serviceOptions: ServiceOptions = {}) {
+    this.#screencastOptions = serviceOptions.screencast
+  }
 
   /**
    * This is used to capture the command stack to ensure that we only capture
@@ -136,6 +150,16 @@ export default class DevToolsHookService implements Services.ServiceInstance {
       )
     }
 
+    /**
+     * Start screencast recording if the user has enabled it.
+     * Options come from the service constructor (services: [['devtools', { screencast: { enabled: true } }]]).
+     * Failures are non-fatal — a warning is logged and the session continues.
+     */
+    if (this.#screencastOptions?.enabled) {
+      this.#screencastRecorder = new ScreencastRecorder(this.#screencastOptions)
+      await this.#screencastRecorder.start(browser)
+    }
+
     /**
      * propagate session metadata at the beginning of the session
      */
@@ -233,9 +257,14 @@ export default class DevToolsHookService implements Services.ServiceInstance {
     }
 
     /**
-     * propagate url change to devtools app
+     * On the first URL navigation, mark this moment as the start of meaningful
+     * recording so leading blank/black frames (browser not yet loaded, pre-test
+     * pauses, etc.) are trimmed from the encoded video.
+     * This fires via beforeCommand regardless of test runner (Mocha, Jasmine,
+     * Cucumber, or standalone), making it universally applicable.
      */
     if (command === 'url') {
+      this.#screencastRecorder?.setStartMarker()
       this.#sessionCapturer.sendUpstream('metadata', { url: args[0] })
     }
 
@@ -334,7 +363,11 @@ export default class DevToolsHookService implements Services.ServiceInstance {
     if (!this.#browser) {
       return
     }
-    const outputDir = this.#browser.options.outputDir || process.cwd()
+
+    // Stop and encode the screencast for the current session.
+    await this.#finalizeScreencast(this.#browser.sessionId)
+
+    const outputDir = this.#outputDir
     const { ...options } = this.#browser.options
     const traceLog: TraceLog = {
       mutations: this.#sessionCapturer.mutations,
@@ -363,6 +396,88 @@ export default class DevToolsHookService implements Services.ServiceInstance {
     this.#sessionCapturer.cleanup()
   }
 
+  /**
+   * Called by WebdriverIO after browser.reloadSession() completes.
+   * The old browser session (and its CDP connection) is destroyed at this
+   * point, so any in-flight screencast is already dead. We encode whatever
+   * frames were captured for the old session and then start a fresh recorder
+   * on the new session so the second scenario is also covered.
+   */
+  async onReload(oldSessionId: string, _newSessionId: string) {
+    if (!this.#screencastOptions?.enabled || !this.#browser) {
+      return
+    }
+
+    // Finalize the recording from the old session (CDP is already gone, so
+    // stop() will fail gracefully and we encode whatever frames arrived).
+    await this.#finalizeScreencast(oldSessionId)
+
+    // Start a new recorder for the new session.
+    this.#screencastRecorder = new ScreencastRecorder(this.#screencastOptions)
+    await this.#screencastRecorder.start(this.#browser)
+  }
+
+  /**
+   * Resolves the directory where devtools output files (trace JSON, video WebM)
+   * should be written, using the following priority:
+   *  1. `outputDir` if the user explicitly set it in wdio.conf — respected as-is.
+   *  2. `rootDir`   — WDIO automatically sets this to the directory containing
+   *                   wdio.conf.ts, so files always land next to the config file
+   *                   regardless of where the `wdio` command is invoked from.
+   *  3. `process.cwd()` — last-resort fallback.
+   *
+   * NOTE: Avoid setting `outputDir` in wdio.conf just to fix the output path —
+   * doing so redirects WDIO worker logs to files and silences the terminal.
+   * Rely on `rootDir` instead (it is set automatically by WDIO).
+   */
+  get #outputDir(): string {
+    const opts = this.#browser?.options as any
+    return opts?.outputDir || opts?.rootDir || process.cwd()
+  }
+
+  /**
+   * Stops the current screencast recorder, encodes collected frames into a
+   * .webm file, and notifies the backend. Safe to call even if recording
+   * never started or the CDP session died early.
+   */
+  async #finalizeScreencast(sessionId: string) {
+    if (!this.#screencastRecorder) {
+      return
+    }
+
+    await this.#screencastRecorder.stop()
+
+    // Skip ghost sessions: browser.reloadSession() creates a new session at the
+    // end of a test run that has no steps — it captures at most a handful of
+    // frames before teardown. Require at least 5 frames so we don't produce
+    // empty videos for these ephemeral sessions.
+    if (this.#screencastRecorder.frames.length < 5) {
+      return
+    }
+
+    const outputDir = this.#outputDir
+    const videoFile = `wdio-video-${sessionId}.webm`
+    const videoPath = path.join(outputDir, videoFile)
+    try {
+      await encodeToVideo(this.#screencastRecorder.frames, videoPath, {
+        captureFormat: this.#screencastOptions?.captureFormat
+      })
+      const screencastInfo: ScreencastInfo = {
+        sessionId,
+        videoPath,
+        videoFile,
+        frameCount: this.#screencastRecorder.frames.length,
+        duration: this.#screencastRecorder.duration
+      }
+      // Notify the backend (and then the UI) that a video is ready.
+      // The backend stores the absolute videoPath and exposes it via
+      // GET /api/video/:sessionId, forwarding only { sessionId } to the UI.
+      this.#sessionCapturer.sendUpstream('screencast', screencastInfo)
+    } catch (encodeErr) {
+      log.warn(`Screencast encode failed: ${(encodeErr as Error).message}`)
+    }
+  }
+
   /**
    * Synchronous injection that blocks until complete
    */
diff --git a/packages/service/src/session.ts b/packages/service/src/session.ts
diff --git a/packages/service/src/types.ts b/packages/service/src/types.ts
