Set the headless flag in the browser’s WebDriver capability in wdio.conf.js, then run the WebdriverIO testrunner with npx wdio run ./wdio.conf.js. Use the flag and capability namespace for your browser: Chrome, Firefox, and Edge each have their own settings. Try native headless mode first; on Linux, use Xvfb when the application or test stack depends on a display server or desktop behavior. WebdriverIO defines a headless browser as one running “without window or UI.”
Configure headless mode for your browser
Put the browser’s headless argument inside its vendor-specific options object in the capability. Do not copy one browser’s options namespace or flag to another.
As an Amazon Associate I earn from qualifying purchases.
Chrome or Chromium
export const config = {
capabilities: [{
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless=new', '--no-sandbox']
}
}]
}Use browserName: 'chromium' if that is the browser name configured for your environment. The documented Chrome example includes --no-sandbox; treat it as an environment-specific flag, not a universal security recommendation. In a container, assess the image’s security model before using it.
Firefox
export const config = {
capabilities: [{
browserName: 'firefox',
'moz:firefoxOptions': {
args: ['-headless']
}
}]
}Microsoft Edge
export const config = {
capabilities: [{
browserName: 'msedge',
'ms:edgeOptions': {
args: ['--headless']
}
}]
}These examples follow the WebdriverIO capabilities guide. It says Safari does not support headless execution. Browser flags and behavior can change across releases, so check the browser and WebdriverIO versions used by your project.
#1 Best Overall
Run the tests
Once the capability is configured, run the testrunner from the project directory:
npx wdio run ./wdio.conf.jsTo isolate a startup problem or a failing test, run one spec file:
npx wdio run ./wdio.conf.js --spec example.e2e.jsThe getting started guide documents the --spec option. Replace the example path with a spec file in your project.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
Choose native headless mode or Xvfb
Use native headless mode first
Native headless mode is the simplest route when the browser, application, and test tooling work without a desktop session. Start with the browser-specific arguments above and add Xvfb only if the environment requires a display.
Use Xvfb for display-dependent Linux runs
Xvfb provides a virtual display on Linux. Consider it when the application or test stack expects DISPLAY, a window manager, GLX, or other desktop behavior—for example, some Electron tests. WebdriverIO’s Headless & Xvfb guide describes how the testrunner considers Xvfb when DISPLAY is absent or headless browser flags are passed.
The relevant settings have distinct purposes:
autoXvfbcontrols whether WebdriverIO wraps a worker with Xvfb. Set it deliberately;autoXvfb: falsedisables the automatic behavior.- If CI already provides an X server, export its
DISPLAYvalue so the runner can use it, or explicitly disable automatic Xvfb if that fits the setup. xvfbAutoInstallrelates to installing Xvfb ifxvfb-runis missing. It does not itself turn on Xvfb use.
For example, a configuration may combine automatic Xvfb handling with Chrome’s headless arguments:
export const config = {
autoXvfb: true,
capabilities: [{
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless=new', '--no-sandbox']
}
}]
}Only enable automatic package installation when the CI image and its permissions make that appropriate. The guide’s Docker example installs xvfb on Ubuntu or Debian with apt-get; other distributions use different package names and installers.
Check browser and driver setup in CI or Docker
A headless flag cannot fix a browser binary that is missing or a driver that cannot start it. Before diagnosing a test assertion, verify the browser and driver are available in the execution environment. WebdriverIO can locate or install supported browsers and drivers under documented conditions; if automatic discovery does not find the browser, its driver binaries guide shows how to specify a binary path with goog:chromeOptions.binary or moz:firefoxOptions.binary.
For Docker, WebdriverIO’s Docker guide demonstrates Chrome arguments including --no-sandbox, --disable-gpu, and a window-size flag. These are example settings to adapt—not a requirement that every container use the same flags. Keep the installed Chrome version aligned with the ChromeDriver version configured for the image, and pin compatible versions in the project’s environment.
Troubleshoot failed headless runs
- Session creation fails immediately: Confirm the browser is installed or configured, the capability has the correct
browserName, and the options use the matching vendor namespace. If necessary, set the browser binary path. - The browser opens with a visible window or rejects the option: Check that the flag is spelled for that browser and placed inside its
argsarray. Chrome, Firefox, and Edge do not share identical flags. - It works locally but fails in Docker: Check that the browser and driver versions match, that the binary exists in the image, and that any container-specific flags reflect the image’s security and graphics setup.
- The application behaves differently or cannot start: Determine whether it depends on
DISPLAY, a window manager, GLX, or desktop behavior. On Linux, check whether CI already supplies Xvfb and whetherautoXvfbshould be enabled or disabled. - Xvfb does not start: Check whether
xvfb-runis installed and review the WebdriverIO guide’s retry and troubleshooting options. Avoid automatic installation in locked-down CI unless package installation is permitted and intended. - The log mentions
DevToolsActivePortor a user-data-directory collision: WebdriverIO notes these messages may follow a browser crash and restart. Investigate the initial browser launch and environment first rather than assuming the profile directory is the root cause. - You need to separate setup from test behavior: Rerun one spec with
npx wdio run ./wdio.conf.js --spec example.e2e.js, then expand back to the full suite once the browser starts reliably.
Or skip the browser setup
If your immediate need is a screenshot or PDF of a page rather than an interactive WebdriverIO test, ScreenshotNeo offers a one-request website capture API. Its API documentation covers the request options.
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes 60+ known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers indicate the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Sign up for ScreenshotNeo’s free plan.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
