/ Testing

Managing Configurations in WebdriverIO

WebdriverIO provides a configuration utility out of the box, which is great for sharing settings across a simple suite of tests. But it's not quite enough if those settings need to slightly shift when testing on different environments (e.g. your development server vs. production).

I plan on covering this in-depth in my online WebdriverIO course, but here's a blog post in the meantime.

Overriding Defaults via Command Line Arguments

The simplest example of this is altering the baseUrl value when running your test suite. It's possible to override the url via a command line parameter, so that we test our development site instead of the default of production:

wdio --baseUrl=http://dev.example.com

There are other simple overrides you can use to change options like which Mocha tests to run:

wdio --mochaOpts.grep=smoke

You can even combine these parameters to come up with very specific outcomes. Here we'll run all the tests with "smoke" in their description using the http://dev.example.com domain:

wdio --baseUrl=http://dev.example.com --mochaOpts.grep=smoke

Multiple Environment Defaults

While these overrides are useful for one-off needs, if we're regularly using the same options, it's time-consuming to type out the baseUrl and grep options every time we want to test our dev server.

We can make it easier by storing these overrides in a file and referencing it via the command line. One way to do is to create a separate configuration file and pass the path to it:

wdio wdio.dev.conf.js

That will tell wdio to use the wdio.dev.conf.js file, instead of the default wdio.conf.js.

Configuration File Hierarchy

While we could just redefine all of our configurations in our new .dev. file,it'd be nicer if we could only override what we need and use the defaults for the rest.

The good news is that our wdio.conf.js file is already set up to do that. It follows the Node 'exports' pattern, so we can simply require it in our .dev. file then use a little bit of Lodash to merge the two configurations:


exports.config = {
	// Here are all of my common/default settings. Things like:
	baseUrl: "http://example.com",
	specs: [
	// and many other options found here: http://webdriver.io/guide/testrunner/configurationfile.html


// Let's load the default configs:
var defaults = require("./wdio.conf.js").config;
var _ = require("lodash");

var overrides = {
	// Here are all my 'dev' specific overrides:
	baseUrl: "http://dev.example.com",
	mochaOpts: {
		grep: "smoke"

// Send the merged config to wdio
exports.config = _.defaultsDeep(overrides, defaults);

The outcome of combining these two files will look something like:

	baseUrl: "http://dev.example.com",
	mochaOpts = {
		grep: "smoke"
	specs: [

Again, all we have to do to use our new file is call wdio with a reference to the specific configuration we want:

wdio wdio.dev.conf.js

One Last Note

If you've got a really complex set of environment requirements, take a look at the NPM node-config module. It provides a wrapper for this hierarchal setting configuration and can make this set up even simpler.

More WebdriverIO!

If you're interested in learning more about WebdriverIO and all the ways you can take advantage of it, check out my Learn WebdriverIO Course, currently at a 50% early acccess discount.