DEV Community

Cover image for Debugging webdriverio tests with VSCode
Danny Perez
Danny Perez

Posted on • Updated on • Originally published at


Debugging webdriverio tests with VSCode

EDIT - If you're interested in seeing me walk through this post live - check out my latest Youtube video!

Debugging tests with webdriverio can get frustrating when you’re trying to figure out why your test is sometimes clicking the wrong elements or just plain not working. Am I using the correct selector? Which element is it actually clicking on? There’s 3 things that you can do to help you drill down:

I searched and had found this post of getting webdriverio tests running inside of vscode to help me step through a test file line by line. That post is using an older version of node, and newer versions of node (v8.11.x+) throw an error like below:

node --debug=

(node:29011) [DEP0062] DeprecationWarning: `node --debug` and `node --debug-brk` are invalid. Please use `node --inspect` or `node --inspect-brk` instead.
Enter fullscreen mode Exit fullscreen mode

There's 2 parts to get this to work with newer versions of node: VSCode configuration and webdriverio configuration

VSCode configuration

See here for creating a VSCode Launch Configuration. Adding this file will allow you to run the VSCode debugger and step through your code line by line.

Heres a working .vscode/launch.json file that you can use and adapt to fit your needs

  "type": "node",
  "request": "launch",
  "name": "Run in debug",
  "port": 5859,
  "timeout": 60000,
  "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/wdio",
  "cwd": "${workspaceRoot}",
  "console": "integratedTerminal",
  "args": [
      "--spec", "main.js"
  // "--spec main.js" will be passed to your executable as
  // "wdio '--spec main.js'" (which isn't what you want)
  "env": {
      "DEBUG": "1" 
      // use an environment variable to be able
      // to toggle debug mode on and off
Enter fullscreen mode Exit fullscreen mode

This configuration will run your runtimeExecutable and by defining the "port" variable, it will attempt a connection to port 5859. Once that connection is successfully made, you'll be able to set breakpoints and step through your test.

webdriverio configuration

On the webdriverio side, we need to tell it to listen for connections from a debugger on port 5859.

In your wdio.conf.js file:

exports.config = {
  debug: true,
  execArgv: ['--inspect-brk=],

  // other wdio configuration
  specs: ['some/specs/here'],
  suites: {
Enter fullscreen mode Exit fullscreen mode

This snippet will start webdriverio and start listening for connections from a debugger on (which you did in your VSCode configuration). The program will stop at this point to wait for a debugger to connect, and if nothing connects, the command will fail.

Once you run it successfully, you should see this type of output

/Users/dperez/workspace/wdio/node_modules/.bin/wdio "--spec" "main.js"

Debugger listening on ws://
Debugger attached.
Enter fullscreen mode Exit fullscreen mode

You'll see the program pause at this point until a connection is made. If you never see "Debugger attached", it means VSCode has not connected to your program, and so you can't set breakpoints and debug.

If you run this as part of your CI process (Gitlab/Jenkins), you can make debug mode configurable. You can use env vars in your .vscode/launch.json configuration.

"console": "integratedTerminal",
"env": {
  "DEBUG": 1
Enter fullscreen mode Exit fullscreen mode

This will run your program with that env var set by using:

DEBUG=1 /Users/dperez/workspace/wdio/node_modules/.bin/wdio "--spec" "main.js"
Enter fullscreen mode Exit fullscreen mode

Then in your wdio.conf.js file:

exports.config = {
  debug: process.env.DEBUG === '1',
  execArgv: process.env.DEBUG === '1' ? ['--inspect-brk='] : []
  // remaining wdio options
Enter fullscreen mode Exit fullscreen mode

This way, the program will only wait to attach to the debugger when you run it inside of VSCode (where the environment variable is set), and everywhere else it will run normally without it.

Wrapping up

Add these snippets to your configuration if you need to step through your program and watch how the program is executing. It sure beats writing tons of console.logs all over your code.

If you want to read more stuff like this, give me a ❤️ and follow me here on

Top comments (0)

An Animated Guide to Node.js Event Loop

Node.js doesn’t stop from running other operations because of Libuv, a C++ library responsible for the event loop and asynchronously handling tasks such as network requests, DNS resolution, file system operations, data encryption, etc.

What happens under the hood when Node.js works on tasks such as database queries? We will explore it by following this piece of code step by step.