Running WebdriverIO?
WebdriverIO suite flaky or hanging in CI? We bring it back.
A WebdriverIO suite that is green locally and red in the pipeline is usually not a test problem, it is a configuration problem. Sync and async modes mixed, wait conditions that trust the wrong event, selectors that snap on a design refresh. We work through each failure, replace the brittle bits, and leave you with a suite the pipeline trusts.
- Since 2015Fixing technology
- FreeEstimates
- US teamReal engineers
What it is
WebdriverIO at a glance
WebdriverIO is a Node.js-based browser and mobile automation framework that speaks WebDriver, WebDriver BiDi and Chrome DevTools Protocol. It has been around since 2015 and is widely used by teams that outgrew Selenium bindings but did not want to move to Playwright or Cypress.
The project ships a CLI, a test runner, a reporter layer and integrations with Sauce Labs, BrowserStack, Appium and most cloud browser grids. It supports Mocha, Jasmine and Cucumber, and comes with a growing set of services for visual testing, Applitools, image comparison and performance. As of version 8 it is async-first, which is the single biggest source of upgrade friction we see.
- Type
- Browser and mobile automation framework
- First released
- 2015
- License
- MIT, free and permissive
- Maintained by
- The OpenJS Foundation and community maintainers
- Typically used for
- End to end testing of web and mobile apps, cross-browser regression, visual testing, cloud grid automation
The honest version
WebdriverIO pros and cons
No technology is all upside. This is where WebdriverIO earns its place and where it tends to cause trouble.
Where WebdriverIO is strong
Speaks multiple protocolsWebDriver, WebDriver BiDi and CDP all work, which means you can target Chrome, Firefox, Safari, Edge and mobile from one codebase without replacing frameworks.
Good Appium integrationNative iOS and Android automation with the same API shape as the browser tests, which is far less common than it sounds.
Smart selectorsThe $('aria/Login') and $('role=button') style selectors read like English and survive a design change better than a CSS class chain.
Cloud grid support out of the boxSauce Labs, BrowserStack, LambdaTest and your own Selenium grid are first-class targets, not an aftermarket plugin.
Reasonable upgrade paceThe maintainers ship a major version roughly once a year with real migration notes, and the deprecation periods are long enough for most teams to keep up.
Where WebdriverIO bites
The sync to async upgrade is painfulThe move to async-first in v8 rewrote a lot of test code. Teams that skipped the migration are now stuck on a legacy major version that does not get features.
Error messages are crypticA stale element or an invalid session id does not tell you why. Debugging requires turning on the trace logger and reading WebDriver protocol output, which is its own skill.
Flakiness has many sourcesA failing test can be the app, the selector, the wait condition, the driver, the browser version, the grid, or the network. Narrowing it down is where most of the time goes.
Reporters are a mixed bagThe built-in HTML and JSON reporters are basic, and the Allure integration needs attention to get genuinely useful output in CI.
Cloud grid costs rise fastParallel runs on Sauce or BrowserStack bill by minute per concurrent session. A test suite that doubled in size can triple the cloud bill without anyone noticing.
Smaller community than Playwright and CypressFinding a Stack Overflow answer for a specific version of a specific service is harder than it used to be, as mind-share moves elsewhere.
Sound familiar?
Common WebdriverIO problems we fix
The WebdriverIO problems that bring people to us, and what you have once each one is fixed.
sync mode is deprecated, switch to async
Suite is stuck on an old major version
Code was written in sync mode on v6, and the team never migrated. Features and browser support have moved on, but every attempt to upgrade broke dozens of tests at once.
Suite on a supported major, incrementally
stale element reference
Tests flake on a re-render
A reference was captured before the framework re-rendered the element, so by the time WebdriverIO clicks, the DOM node is gone and a new one has taken its place.
Selectors that resolve fresh
element still not clickable after 10000ms
Wait conditions time out intermittently
A wait that trusts visibility but the element is covered by a toast, a modal, or a loading spinner. The default waitForClickable does not know about the overlay.
Waits that match real UI state
session not created: ChromeDriver version mismatch
Driver versions keep breaking CI
A browser auto-update on the CI image, a pinned ChromeDriver that no longer matches, or a Docker image rebuild that pulled a new Chrome. The classic flake that is not a flake.
Driver pinning that survives rebuilds
wdio-selenium-standalone-service: port 4444 already in use
Local runs hang on the second attempt
A Selenium server from a previous run was not shut down cleanly, so the port is held and the next run cannot bind. We add a cleanup step and pin the port.
Clean start every run
wdio-sauce-service: credentials missing
Cloud grid fails silently
Sauce or BrowserStack credentials rotated and the CI secret was not updated, so sessions never start and the suite runs but tests all show as skipped.
Grid credentials rotated and tested
browser.waitUntil timed out
Tests pass locally and fail in CI
Different network latency, different viewport, different browser version. A wait that was enough on a laptop is not enough on a shared CI runner.
Thresholds that reflect CI reality
What we do
WebdriverIO help, from stabilisation to upkeep
Call us for one flaky suite, or hand us the whole WebdriverIO pipeline and we will run it with you.
01
- Rescue
- Red pipelines, hangs on CI, or a sync-mode codebase that refuses to upgrade. We stabilise the suite first and explain the root causes second.
02
- Flakiness audit
- Every failing test classified by cause, waits replaced with explicit conditions, and selectors rewritten to survive a design refresh.
03
- Upgrade to async
- Moving a legacy sync suite to the current major version without a weeklong freeze, with the tests still green at every step.
04
- CI pipeline
- Docker images with pinned browsers, parallel sharding that does not thrash the grid, and reporters that let the dev team actually find the failure.
05
- Managed Tech
- Ongoing watch on the suite and the grid bill, driver and browser updates kept in step, flaky tests triaged weekly, and a person to call when CI stops going green.
How it works
From first message to fixed
1
Look Free estimate
Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.
2
Fix
We fix the cause, not the symptom. If something is down, getting it back up comes first.
3
Harden
Backups, monitoring, updates and access, so the same problem can't quietly come back.
4
Hand back or stay on
You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.
Often found together
Running WebdriverIO alongside something else?
We work on the whole stack, so the problem can be wherever it actually is.
Why is our WebdriverIO suite flaky only in CI?
Three common causes. CI runners have different timing and viewport, so waits that pass locally time out in the pipeline. The CI browser image updates independently of the pinned driver, so Chrome and ChromeDriver drift apart. And shared cloud grids throttle under load, which makes a selector resolve slowly. Fixing each is mechanical once you know which you have.
Should we move from WebdriverIO to Playwright or Cypress?
Sometimes, but not always. If you need native mobile automation or cross-browser Safari coverage WebdriverIO is still the better fit. If you are purely web Chrome and Firefox and want fewer protocol surprises, Playwright is a strong alternative. We give you an honest read based on your stack rather than the framework we most recently used.
How do we upgrade from sync to async WebdriverIO?
Not in one pass. We fork the config, run both versions side by side, migrate tests in batches starting with the most stable, and only turn off the legacy pipeline once every test is passing on the new one. A rushed migration usually ends with a frozen pipeline and a reverted branch.
Can WebdriverIO drive mobile apps?
Yes, via Appium. The API shape is similar enough that a web engineer can read the mobile tests without a second framework in their head, which is the real appeal. The install footprint is larger than pure web, and the first setup on a Mac for iOS can take a day.
Why do my selectors keep breaking?
Because they are pointed at implementation detail. A CSS class generated by a build tool, an nth-of-type on a layout that changes, or an id that is regenerated on every mount. The lasting fix is accessibility-first selectors like $('aria/Login') and $('role=button') which track the semantic intent rather than the markup.
How much does WebdriverIO help cost?
Nothing to get a price. Share the suite size, the flake rate and where it runs, and we send a figure back before any work begins.