fix(webdriver): re-enable undici global dispatcher by christian-bromann · Pull Request #14623 · webdriverio/webdriverio

christian-bromann · 2025-07-08T18:37:58Z

Proposed changes

After commit b70285e, WebdriverIO started caching dispatchers per session and creating its own proxy agents internally, which means it no longer uses the global dispatcher set via setGlobalDispatcher().

The change was introduced to:

Cache dispatchers per session to avoid creating new ones for every request
Have better control over proxy settings per session

Here's what has changed and why the documentation is now outdated:

What Changed

Before v9.12.x: WebdriverIO relied on the global dispatcher set by undici's setGlobalDispatcher()
After v9.12.x: WebdriverIO creates its own dispatchers internally and only looks at HTTP_PROXY/HTTPS_PROXY environment variables

The Problem

The documentation still recommends using setGlobalDispatcher() but this no longer works because:

WebdriverIO now creates its own dispatchers that override the global one
It only reads proxy configuration from HTTP_PROXY/HTTPS_PROXY environment variables

The Solution

Let's ensure we support both to be backwards compatible as well as document the environment only approach.

1. Environment Variables (New, simpler approach)

Users can now simply set standard proxy environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.domain

2. undici's setGlobalDispatcher (Existing approach)

The existing documented approach using setGlobalDispatcher continues to work:

import { setGlobalDispatcher, ProxyAgent } from 'undici';
const dispatcher = new ProxyAgent({ uri: 'http://proxy.example.com:8080' });
setGlobalDispatcher(dispatcher);

Types of changes

Polish (an improvement for an existing feature)
Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update (improvements to the project's docs)
Specification changes (updates to WebDriver command specifications)
Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

I have read the CONTRIBUTING doc
I have added tests that prove my fix is effective or that my feature works
I have added the necessary documentation (if appropriate)
I have added proper type definitions for new commands (if appropriate)

Backport Request

//: # (The current main branch is the development branch for WebdriverIO v9. If your change should be released to the current major version of WebdriverIO (v8), please raise another PR with the same changes against the v8 branch.)

This change is solely for v9 and doesn't need to be back-ported
Back-ported PR at #XXXXX

Further comments

fixes #14621

Reviewers: @webdriverio/project-committers

pkg-pr-new · 2025-07-08T19:55:22Z

Open in StackBlitz

eslint-plugin-wdio

npm i https://pkg.pr.new/webdriverio/webdriverio/eslint-plugin-wdio@14623

@wdio/allure-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/allure-reporter@14623

@wdio/appium-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/appium-service@14623

@wdio/browser-runner

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/browser-runner@14623

@wdio/browserstack-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/browserstack-service@14623

@wdio/cli

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/cli@14623

@wdio/concise-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/concise-reporter@14623

@wdio/config

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/config@14623

@wdio/cucumber-framework

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/cucumber-framework@14623

@wdio/dot-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/dot-reporter@14623

@wdio/firefox-profile-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/firefox-profile-service@14623

@wdio/globals

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/globals@14623

@wdio/jasmine-framework

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/jasmine-framework@14623

@wdio/json-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/json-reporter@14623

@wdio/junit-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/junit-reporter@14623

@wdio/lighthouse-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/lighthouse-service@14623

@wdio/local-runner

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/local-runner@14623

@wdio/logger

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/logger@14623

@wdio/mocha-framework

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/mocha-framework@14623

@wdio/protocols

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/protocols@14623

@wdio/repl

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/repl@14623

@wdio/reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/reporter@14623

@wdio/runner

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/runner@14623

@wdio/sauce-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/sauce-service@14623

@wdio/shared-store-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/shared-store-service@14623

@wdio/smoke-test-cjs-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/smoke-test-cjs-service@14623

@wdio/smoke-test-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/smoke-test-reporter@14623

@wdio/smoke-test-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/smoke-test-service@14623

@wdio/spec-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/spec-reporter@14623

@wdio/static-server-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/static-server-service@14623

@wdio/sumologic-reporter

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/sumologic-reporter@14623

@wdio/testingbot-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/testingbot-service@14623

@wdio/types

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/types@14623

@wdio/utils

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/utils@14623

@wdio/webdriver-mock-service

npm i https://pkg.pr.new/webdriverio/webdriverio/@wdio/webdriver-mock-service@14623

webdriver

npm i https://pkg.pr.new/webdriverio/webdriverio/webdriver@14623

webdriverio

npm i https://pkg.pr.new/webdriverio/webdriverio@14623

commit: 0031a44

fix(webdriver): re-enable undici global dispatcher

275686e

christian-bromann added the PR: Bug Fix 🐛 PRs that contain bug fixes label Jul 8, 2025

Merge branch 'main' into cb/dispatcher-fix

0031a44

christian-bromann merged commit 80cfd4a into main Jul 8, 2025
78 of 79 checks passed

christian-bromann deleted the cb/dispatcher-fix branch July 8, 2025 23:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(webdriver): re-enable undici global dispatcher#14623

fix(webdriver): re-enable undici global dispatcher#14623
christian-bromann merged 2 commits intomainfrom
cb/dispatcher-fix

christian-bromann commented Jul 8, 2025

Uh oh!

pkg-pr-new bot commented Jul 8, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

christian-bromann commented Jul 8, 2025

Proposed changes

What Changed

The Problem

The Solution

1. Environment Variables (New, simpler approach)

2. undici's setGlobalDispatcher (Existing approach)

Types of changes

Checklist

Backport Request

Further comments

Reviewers: @webdriverio/project-committers

Uh oh!

pkg-pr-new bot commented Jul 8, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant