How to Set Browser Capabilities in WebDriverJS (Ex: Headless Mode)

Skip Right to the Chase

TLDR, here’s the code. If you want more explanation or how I figured out how to do it, see below. Just swap calls to specific browsers depending on which one you want.

Browser Capabilities with Chrome and Firefox (Example: Running Headlessly)

// Include the libraries - this will differ depending on JS flavor you're using.
// Note that chromedriver/geckodriver are not actually used in this example
// but you're likely to need them in an actual test
const webdriver = require('selenium-webdriver');
const chromeDriver = require('chromedriver');
// User-set variables
const browserName = 'chrome'; // Switch to 'firefox' if desired
const capabilityName = 'goog:chromeOptions'; // Switch to 'moz:firefoxOptions' if desired
// Set up the commandline options for launching the driver.
// In this example, I'm using various headless options.
var browserOptions = {
	'args': [
// Set up the browser capabilities.
// Some lines could be condensed into one-liners if that's your preferred style.
var browserCapabilities = browserName === 'chrome'
	: webdriver.Capabilities.firefox();
browserCapabilities = browserCapabilities.set(capabilityName, browserOptions);
var builder = new webdriver.Builder().forBrowser(browserName);
var driver = builder.withCapabilities(browserCapabilities).build();
// Now you can actually use the driver, like:

The flags that you can throw into browserOptions are the ones referenced here:


WebDriverJS, the official JavaScript implementation of Selenium's WebDriver, is a very useful tool for fully-JavaScript projects. The ability to launch an actual browser, navigate around, and receive test results in test runners like Supertest is really invaluable.

Unfortunately, I've found that there's a real dearth of useful documentation. Sure, there's their GitHub wiki page (, but that hasn't been updated since October 31, 2017. There's also their "blog", which, as of the writing of this article (August 13, 2019) has a single post.

So, how do you figure out how to do things you want, like run Chrome in "headless" mode (where no GUI browser launches, but it still runs in the background)? Well, you Google a lot, and write the documentation yourself!

After a significant amount of Googling, I found an obscure Github gist from 2015 with an actual use case: I don't know this anandsunderraman user, but they saved myself (and the other commenters on the gist) quite a bit of time!

At some point recently, though, this stopped working. As referenced by this comment by user EzequielCaballero, the options seem to have died with some combination of Selenium-WebDriver v4 and Chromedriver V75 (although I actually noticed that it broke for me while running V74...go figure. Again, no real documentation, and I'm limited in the time I want to spend digging through soucre code).

EzequielCaballero specifically calls out the fact that you need to add the string "goog:" in front of the "chromeOptions", which is not an update I've seen anywhere. There is a bug about it from January 2018 with a comment saying "...this has changed in recent releases of Selenium", but again, I wasn't able to easily find an update mentioned anywhere. In addition, most of the time when you Google "WebDriverJS" or "WebDriver JavaScript", you actually get results from other languages, which can be confusing

One last point of annoyance, I was trying to figure out what the "goog:chromeOptions" equivalent for Firefox was. I Googled that exact string, including the quotes, to try to find references - at the time of writing this blog post, none were JS-specific and straight from the project itself. However, I did find docs for the Python implementation for Selenium at Poking around on the site, I was able to find the same type of file, but for Firefox options: - and this code referenced "moz:firefoxOptions".

So, in the end, Googling an error I had lead me to an obscure gist from 2015, with an update from 2019, and some Python sources - but in the end, my WebDriverJS is back up and running. Hope this helps people.

Minor edit: A nice explanation (though no actual JavaScript code examples) can be found here: