Skip to content

README.md

Latest commit

 

History

History
124 lines (92 loc) · 4.61 KB

README.md

File metadata and controls

124 lines (92 loc) · 4.61 KB

@wdio/devtools-service

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

npm install @wdio/devtools-service --save-dev
# or
pnpm add -D @wdio/devtools-service

Usage

Test Runner

// wdio.conf.ts
export const config = {
  services: ['devtools'],
}

Standalone

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

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. Videos are displayed in the DevTools UI alongside the snapshot and DOM mutation views.

Note: Screencast recording is currently supported for WebdriverIO only. Nightwatch.js support is planned for a future release.

Setup

Screencast encoding requires ffmpeg on PATH and the fluent-ffmpeg package:

# 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

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)