Configuration Reference

All DevTools options at a glance, across the three adapters. Shared options have the same names, types and defaults on every adapter; where behaviour or availability differs, it's noted, and adapter-only options are listed separately. The Python adapter takes no options object; see the Python tabs on the Selenium page. For the full explanation of each trace option see the linked section on the Trace Mode page.

Pass options the way each adapter takes them:

• WebdriverIO — services: [['devtools', { … }]]
• Selenium — DevTools.configure({ … })
• Nightwatch — globals: nightwatchDevtools({ … })

Mode & live-mode options

Option	Type / values	Default	Notes
mode	'live' | 'trace'	'live'	'live' opens the DevTools UI dashboard; 'trace' skips it and writes a portable artifact. The two are mutually exclusive.
port	number	3000 (a free port is used if it is taken)	Port the DevTools UI / backend binds to. Live mode only.
hostname	string	'localhost'	Hostname the server binds to. Live mode only.
screencast	ScreencastOptions	{ enabled: false }	Continuous session video (.webm). Live mode only — for trace mode use video. Includes maxBufferFrames (default 2000), the cap on frames held in memory. See Screencast.
devtoolsCapabilities	Capabilities	Chrome 1600×1200	Capabilities used to open the DevTools UI window. WebdriverIO, live mode only.

Trace-mode options

Only apply when mode: 'trace'.

Option	Type / values	Default	Details
traceFormat	'zip' | 'ndjson-directory'	'zip'	Single archive vs. an unpacked directory. Output format
traceGranularity	'session' | 'spec' | 'test'	'session'	One trace per session / spec file / test. 'test' is required for per-test screenshot/video and inline Allure attach. Trace granularity
tracePolicy	'on' | 'retain-on-failure' | 'retain-on-first-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure-and-retries'	'on'	Which traces to keep. Pairs with traceGranularity: 'test'. Retention
filmstrip	boolean	true	Dense, continuous screencast into the trace for smooth scrubbing; false records one frame per action. Thinned at export to frames at least 100 ms apart, about 600 at most. Dense filmstrip
screenshot	'off' | 'on' | 'only-on-failure'	'off'	Per-test screenshot (needs traceGranularity: 'test'). Attached inline to Allure on WebdriverIO and Selenium; produce-only on Nightwatch. Per-test screenshot & video
video	'off' | <tracePolicy value>	'off'	Per-test video slice (needs traceGranularity: 'test'; encoding needs ffmpeg on PATH). Attached inline to Allure on WebdriverIO and Selenium; produce-only on Nightwatch. Per-test screenshot & video
emitArtifactsManifest	boolean	false	Write devtools-artifacts-<sessionId>.json. Auto-enabled when an Allure reporter is detected (opt-in on Nightwatch). Artifacts manifest
captureAssertions	boolean	true	Capture node:assert (and framework expect matchers where supported) as trace actions. Assertions

Selenium-only (Node.js)

Option	Type / values	Default	Notes
openUi	boolean	true	Open the dashboard window automatically. Set false for CI.
headless	boolean	false	Run the test browser headless (--headless=old). The dashboard window is unaffected.
rerunCommand	string	auto	Command template for a per-test rerun; {{testName}} is substituted. Derived from the runner's argv when omitted.

Nightwatch-only

Option	Type / values	Default	Notes
bidi	boolean	false	Opt into WebDriver BiDi capture (console + JS exceptions + network). Requires webSocketUrl: true in capabilities. On WebdriverIO and Selenium, BiDi is auto-attached. See Nightwatch → BiDi capture.

Per-adapter differences

Some trace capabilities degrade on certain adapters — see the cross-framework support matrix for the full picture. The notable ones:

• Nightwatch retry-aware retention — only retain-on-failure is reliable; other tracePolicy values degrade to it.
• Nightwatch BDD describe/it — traceGranularity: 'test' collapses to one session-scoped slice.
• Nightwatch Allure attach — per-test screenshot/video are produce-only (files + manifest), not attached inline.