Debugging WebdriverIO Tests
On this page
A failing end-to-end test tells you that something went wrong, rarely why. The fix is almost never to add a pause and rerun. This chapter is a routine for finding the cause: read the error properly, look at what the browser showed, stop the test at the right moment and poke at the page, and turn up the logs when nothing else explains it.
1. Read the whole error#
WebdriverIO's errors are specific, and most of the time they name the cause. The ones you met in this course:
| Error | What it means |
|---|---|
StrictSelectorError: ... resolved to 2 elements, expected 1 |
The selector is too broad (chapter 2). |
Can't call click on element with selector "..." because element wasn't found |
Nothing matched within waitforTimeout. Wrong selector, wrong page, or the element is inside an iframe. |
Expect $(...) to have text with Expected and Received
|
The element was found; its content is not what the test expected. Compare the two lines. |
Timeout of 60000ms exceeded |
Mocha's own test timeout, longer than any WebdriverIO wait. Usually a forgotten await or a wait without a timeout. |
...at the limit of the maximum allowed parallel + queued tests... |
The grid refused the session. No test ran (chapter 7). |
The Received line is the most underrated piece of information. In chapter 6 the Login spec on Chrome failed with Expected: "You logged out of the secure area!" but Received: "You logged into a secure area!". That already said "the logout click did not happen", which pointed straight at something covering the button.
2. Watch the session video#
On TestingBot every session records a video and a screenshot per step, linked from the session in the dashboard. Open the failed session (the reporter prints its id; the build name from chapter 6 narrows the list) and jump to the end. For "the click did nothing" and "the element was not found", the video answers the question in seconds: a cookie banner, a native dialog, a page that never finished loading, a login that silently failed.
You can fetch the same data from the TestingBot REST API, which is handy in a script or a CI step that posts a link next to a failure:
curl -s -u "$TESTINGBOT_KEY:$TESTINGBOT_SECRET" \
"https://api.testingbot.com/v1/tests/<SESSION_ID>"
The JSON response includes the session's success state, its name and build, and a video URL. The video link is signed and expires after a while, so fetch it when you need it rather than storing it.
A test fails on Safari only: Can't call click on element with selector "button=Checkout" because element wasn't found. What is the quickest way to find out why?
"Not found" means the page did not contain that button when the test looked, which could be a different page, an error message, or a different label. The video shows which. A longer timeout or a new selector changes the test before you know what is wrong.
3. Stop the test and explore with browser.debug()#
browser.debug() pauses the test at that line and turns your terminal into a REPL connected to the live browser session. You can run commands against the page exactly as it is at that moment:
it('pauses on the secure page', async () => {
await browser.url('/login')
await $('#username').setValue('tomsmith')
await $('#password').setValue('SuperSecretPassword!')
await $('button=Login').click()
await browser.debug()
await expect($('h2')).toHaveText(expect.stringContaining('Secure Area'))
})
Run the spec on its own and the runner stops when it reaches debug():
The execution has stopped!
You can now go into the browser or use the command line as REPL
(To exit, press ^C again or type .exit)
[0-0] › $("h2").getText()
'Secure Area'
[0-0] › $$("a").length
7
[0-0] › .exit
Type commands without await: the REPL resolves promises for you, and await at its prompt is a syntax error. Try the selector you suspect, read text and attributes, click things, and when you know the answer type .exit (or press Ctrl+C) and the test continues from the next line.
Things to know:
-
Run one spec file with one capability. With several workers, several REPLs fight over one terminal.
--specplus the local config is the usual way. -
Raise the Mocha timeout while debugging. The test is still running while you explore, and Mocha fails it once
mochaOpts.timeout(60 seconds in the course config) runs out. Pass--mochaOpts.timeout 600000on the command line for the debugging run instead of changing the config. -
On a cloud grid, the session has an idle timeout too. TestingBot ends a session that receives no command for 130 seconds by default; the configuration reference shows how to change it with the
idleTimeoutcapability. Prefer debugging locally, and use the cloud video for problems that only happen there. -
Remove
browser.debug()before committing. In CI there is no one to type.exit, so the run hangs until a timeout.
You can also open a REPL without any test: npx wdio repl chrome starts a browser and gives you the same prompt, which is a quick way to try selectors on a page.
You add browser.debug() to a test and start exploring. A minute later the run ends with "Timeout of 60000ms exceeded" while you are still typing. What do you change?
The test is still running while the REPL is open, so Mocha's per-test timeout keeps counting. waitforTimeout only applies to element waits and matchers.
4. Turn up the logs#
When the error, the video and the REPL do not explain it, look at the WebDriver traffic. Run with the debug log level and write the logs to files:
npx wdio run wdio.conf.ts --spec test/specs/login.e2e.ts --logLevel debug --outputDir ./logs
The runner writes logs/wdio.log for the launcher, one log per worker named after the spec file (such as login.e2e-0-0.log), and the browser driver's own log. The worker log lists every command in order:
INFO webdriver: COMMAND getWindowHandle()
INFO webdriver: BIDI COMMAND browsingContext.getTree {}
This is where you find out that a command was sent to the wrong window, that a navigation never completed, or that the test ran a step you did not expect. On TestingBot the session page in the dashboard shows the same command list next to the video, with the screenshot for each step.
5. Fix the cause, then make it impossible to recur#
Once you know why a test failed, fix that: a selector that names one element, a wait for the state the test depends on, a capability that turns off a browser feature that gets in the way. Then ask whether the same mistake could happen elsewhere. The Chrome password dialog from chapter 6 was fixed in the shared config, so every future spec gets the fix. A pause added to one test would have fixed nothing and slowed down every run.
For failures that come and go between runs, the flaky tests course is the next step.