Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/node-floor-emudhra.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'@wdio/devtools-backend': minor
'@wdio/devtools-service': minor
'@wdio/selenium-devtools': minor
'@wdio/nightwatch-devtools': minor
---

Require Node.js 22.23.4, 24.22.1, 26.12.1 or a later release of these lines. These are the first releases with the updated CA store for the eMudhra intermediate CA compromise ("ca-cert (eMudhra Intermediate CA Compromise) on 26.x, 24.x, 22.x" in the [October 2026 security releases](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases)). Older versions trust intermediates whose private keys are public. `engines` only warns, except with Yarn 1 or `npm --engine-strict`.
6 changes: 6 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ jobs:
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version-file: .nvmrc
# the runner cache can hold a 24.x below the engines floor
check-latest: true
- name: Cache pnpm modules
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
env:
Expand Down Expand Up @@ -73,6 +75,8 @@ jobs:
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version-file: .nvmrc
# the runner cache can hold a 24.x below the engines floor
check-latest: true
- name: Cache pnpm modules
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
env:
Expand Down Expand Up @@ -111,6 +115,8 @@ jobs:
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version-file: .nvmrc
# the runner cache can hold a 24.x below the engines floor
check-latest: true
- name: Cache pnpm modules
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
env:
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ jobs:
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version-file: .nvmrc
# the runner cache can hold a 24.x below the engines floor
check-latest: true
registry-url: "https://registry.npmjs.org"
- uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
with:
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Thanks for contributing to WebdriverIO DevTools! This guide gets you from a clon

## Prerequisites

- **Node.js** ≥ 20
- **Node.js** 22.23.4, 24.22.1, 26.12.1 or a later release of these lines
Comment thread
plum117 marked this conversation as resolved.
Resolved
- **pnpm** ≥ 9 (this is a pnpm workspace / monorepo)

## Setup
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ pip install selenium-devtools-py # or, from this repo: pip install
selenium-devtools install-backend # once — pip cannot install a Node package
```

The Python adapter needs Python 3.10+, selenium 4.44+, and **Node.js 22.19+ on your
The Python adapter needs Python 3.10+, selenium 4.44+, and **Node.js 22.23.4+, 24.22.1+ or 26.12.1+ on your
PATH** — the backend that serves the page collector, carries the event stream
and builds the trace archive is a Node app, so Node is required in every mode,
not just for the dashboard window. Without the install step a run fetches that
Expand Down
2 changes: 1 addition & 1 deletion packages/backend/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "@wdio/devtools-backend",
"version": "2.0.0",
"engines": {
"node": ">=22.19.0"
"node": ">=22.23.4 <23 || >=24.22.1 <25 || >=26.12.1"
},
"description": "Backend service to spin up WebdriverIO Devtools",
"author": "Christian Bromann <mail@bromann.dev>",
Expand Down
2 changes: 1 addition & 1 deletion packages/nightwatch-devtools/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "@wdio/nightwatch-devtools",
"version": "2.0.0",
"engines": {
"node": ">=22.19.0"
"node": ">=22.23.4 <23 || >=24.22.1 <25 || >=26.12.1"
},
"description": "Nightwatch adapter for WebdriverIO DevTools - reuses existing backend, UI, and capture infrastructure",
"type": "module",
Expand Down
4 changes: 2 additions & 2 deletions packages/selenium-devtools-py/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ pays the whole download inside the first run, and fails in the middle of a test
session when a proxy declines the package, so the one-time install is worth the
one line. `selenium-devtools backend-path` says whether it is there.

**Requires Node.js 22.19+ on your PATH — in every mode.** The backend is a Node app
**Requires Node.js 22.23.4+, 24.22.1+ or 26.12.1+ on your PATH — in every mode.** The backend is a Node app
and pip cannot resolve it, so it is obtained separately. It is not
only the dashboard window: the page collector is served by the backend, the
whole event stream goes through its WebSocket, and in trace mode it is also what
Expand Down Expand Up @@ -572,7 +572,7 @@ Two workflows, mirroring the JS split (`ci.yml` tests / `release.yml` publish):
then publishes via **trusted publishing (OIDC)** — no token/secret.

The wheel does **not** bundle the backend — approach A fetches a pinned
`@wdio/devtools-backend` via `npx` at runtime (Node 22.19+ required). Bundling it
`@wdio/devtools-backend` via `npx` at runtime (Node 22.23.4+, 24.22.1+ or 26.12.1+ required). Bundling it
(approach B/C) is a GA-time change.

That pin is the one thing a release here cannot get wrong, because it is the
Expand Down
5 changes: 5 additions & 0 deletions packages/selenium-devtools-py/changes/node-floor-emudhra.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
minor
---

Node.js 22.23.4, 24.22.1, 26.12.1 or a later release of these lines is required on the PATH, where 22.19 was enough before. These are the first releases with the updated CA store for the eMudhra intermediate CA compromise, and the backend now requires them. With a Node release below the floor of its line, for example 22.22 or 24.21, which worked before, `enable()` now logs a warning (`could not start dashboard (...); continuing without capture`) that names the version it found and the versions it needs, then returns `None`, and the run continues without capture; `selenium-devtools install-backend` prints that error and exits with code 1 when it installs (no backend on disk yet, or `--force`); with the backend already on disk it does not check Node and still succeeds. The odd lines (23, 25) behave the same. Update Node on the PATH, or attach to a backend someone else runs via `DEVTOOLS_PORT`, which still needs no local Node.
14 changes: 7 additions & 7 deletions packages/selenium-devtools-py/src/selenium_devtools/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -89,13 +89,13 @@
# `show-trace`, so the name is what picks the right one out of `bin`.
BACKEND_BIN_NAME = "devtools-backend"

# The backend is a Node app, so Python users need a Node runtime. 18 is the
# floor its dependencies require; below it the process starts and then dies on
# syntax it cannot parse, which surfaces here only as "exited before reporting
# a port". Checked up front so the message names the real problem.
# What the pinned backend's own dependencies declare in `engines`; a minor matters, not just a major.
MIN_NODE_VERSION = (22, 19, 0)
MIN_NODE_LABEL = "22.19"
# The backend is a Node app, so Python users need a Node runtime. Below its
# floor the process can start and then die, which surfaces here only as "exited
# before reporting a port". Checked up front so the message names the real problem.
# The backend's `engines`, per line: the first release with the eMudhra CA store
# fix. Odd lines are refused; a line newer than the last one here is accepted.
NODE_LINE_FLOORS = {22: (22, 23, 4), 24: (24, 22, 1), 26: (26, 12, 1)}
MIN_NODE_LABEL = "22.23.4+, 24.22.1+ or 26.12.1+"
NODE_VERSION_TIMEOUT_S = 5.0

# ── Trace mode ───────────────────────────────────────────────────────────────
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
import subprocess
from typing import Optional, Tuple

from .constants import LOGGER_NAME, MIN_NODE_LABEL, MIN_NODE_VERSION, NODE_VERSION_TIMEOUT_S
from .constants import LOGGER_NAME, MIN_NODE_LABEL, NODE_LINE_FLOORS, NODE_VERSION_TIMEOUT_S

_log = logging.getLogger(f"{LOGGER_NAME}.backend")

Expand Down Expand Up @@ -77,8 +77,16 @@ def node_version(executable: str) -> Optional[Tuple[int, int, int]]:
return (int(match.group(1)), int(match.group(2)), int(match.group(3)))


def node_supported(version: Tuple[int, int, int]) -> bool:
"""Whether ``version`` is in the backend's ``engines`` range."""
if version[0] > max(NODE_LINE_FLOORS):
return True
floor = NODE_LINE_FLOORS.get(version[0])
return floor is not None and version >= floor


def require_node() -> str:
"""Absolute path to a Node new enough to run the backend.
"""Absolute path to a Node that can run the backend.

Raises :class:`RuntimeError` naming what was found and what is needed. It
is called only on the paths that actually spawn Node — attaching to a
Expand All @@ -88,21 +96,21 @@ def require_node() -> str:
if executable is None:
raise RuntimeError(
f"Node.js not found on PATH. The devtools dashboard backend is a "
f"Node app, so Node {MIN_NODE_LABEL}+ is required — install it "
f"Node app, so Node {MIN_NODE_LABEL} is required — install it "
f"from https://nodejs.org. {_ESCAPE_HATCH}"
)
version = node_version(executable)
if version is None:
raise RuntimeError(
f'"{executable}" did not report a usable version, so it cannot be '
f"used to run the devtools dashboard backend (Node "
f"{MIN_NODE_LABEL}+ required). {_ESCAPE_HATCH}"
f"{MIN_NODE_LABEL} required). {_ESCAPE_HATCH}"
)
if version < MIN_NODE_VERSION:
if not node_supported(version):
found = ".".join(str(part) for part in version)
raise RuntimeError(
f"Node {found} at \"{executable}\" is too old to run the devtools "
f"dashboard backend, which needs Node {MIN_NODE_LABEL}+. Upgrade "
f"Node {found} at \"{executable}\" cannot run the devtools "
f"dashboard backend, which needs Node {MIN_NODE_LABEL}. Upgrade "
f"from https://nodejs.org. {_ESCAPE_HATCH}"
)
return executable
48 changes: 31 additions & 17 deletions packages/selenium-devtools-py/tests/test_node_runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
from unittest import mock

from selenium_devtools import backend, node_runtime
from selenium_devtools.constants import MIN_NODE_LABEL, MIN_NODE_VERSION
from selenium_devtools.constants import MIN_NODE_LABEL, NODE_LINE_FLOORS


def _completed(stdout: str, returncode: int = 0):
Expand Down Expand Up @@ -79,11 +79,14 @@ def test_anything_unreadable_is_none_rather_than_a_guess(self):


class TestRequiringNode(unittest.TestCase):
def test_returns_the_resolved_executable_when_new_enough(self):
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
node_runtime, "node_version", return_value=MIN_NODE_VERSION
):
self.assertEqual(node_runtime.require_node(), "/usr/bin/node")
def test_returns_the_resolved_executable_on_a_supported_node(self):
newest = max(NODE_LINE_FLOORS)
for version in [*NODE_LINE_FLOORS.values(), (22, 30, 0), (newest + 1, 0, 0)]:
with self.subTest(version=version):
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
node_runtime, "node_version", return_value=version
):
self.assertEqual(node_runtime.require_node(), "/usr/bin/node")

def test_missing_node_says_node_and_how_to_get_it(self):
with mock.patch("shutil.which", return_value=None):
Expand All @@ -99,23 +102,34 @@ def test_an_old_node_names_the_version_found_and_the_one_needed(self):
# Previously this reached the user as "backend exited (code 1) before
# reporting a port", which says nothing about Node.
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
node_runtime, "node_version", return_value=(MIN_NODE_VERSION[0] - 2, 4, 1)
node_runtime, "node_version", return_value=(20, 4, 1)
):
with self.assertRaises(RuntimeError) as ctx:
node_runtime.require_node()
message = str(ctx.exception)
self.assertIn(f"{MIN_NODE_VERSION[0] - 2}.4.1", message)
self.assertIn("20.4.1", message)
self.assertIn(MIN_NODE_LABEL, message)

# The floor has a minor: the backend's dependencies declare 22.19, and a 22.0 fails later and worse.
def test_a_node_on_the_right_major_but_below_the_minor_is_refused(self):
major, minor, _ = MIN_NODE_VERSION
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
node_runtime, "node_version", return_value=(major, minor - 1, 9)
):
with self.assertRaises(RuntimeError) as ctx:
node_runtime.require_node()
self.assertIn(f"{major}.{minor - 1}.9", str(ctx.exception))
# Each line has its own floor, down to the patch: the release with the eMudhra CA store fix.
def test_a_node_below_the_floor_of_its_line_is_refused(self):
for major, minor, patch in NODE_LINE_FLOORS.values():
for version in [(major, minor, patch - 1), (major, minor - 1, 9), (major, 0, 0)]:
with self.subTest(version=version):
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
node_runtime, "node_version", return_value=version
):
with self.assertRaises(RuntimeError) as ctx:
node_runtime.require_node()
self.assertIn(".".join(map(str, version)), str(ctx.exception))

def test_an_odd_line_between_the_floors_is_refused(self):
for version in [(23, 99, 0), (25, 9, 0)]:
with self.subTest(version=version):
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
node_runtime, "node_version", return_value=version
):
with self.assertRaises(RuntimeError):
node_runtime.require_node()

def test_a_node_that_will_not_report_a_version_is_refused(self):
with mock.patch("shutil.which", return_value="/usr/bin/node"), mock.patch.object(
Expand Down
2 changes: 1 addition & 1 deletion packages/selenium-devtools/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "@wdio/selenium-devtools",
"version": "2.0.0",
"engines": {
"node": ">=22.19.0"
"node": ">=22.23.4 <23 || >=24.22.1 <25 || >=26.12.1"
},
"description": "Selenium WebDriver adapter for WebdriverIO DevTools \u2014 runner-agnostic, reuses existing backend, UI, and capture infrastructure",
"type": "module",
Expand Down
2 changes: 1 addition & 1 deletion packages/service/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "@wdio/devtools-service",
"version": "11.0.0",
"engines": {
"node": ">=22.19.0"
"node": ">=22.23.4 <23 || >=24.22.1 <25 || >=26.12.1"
},
"description": "Hook up WebdriverIO with DevTools",
"author": "Christian Bromann <mail@bromann.dev>",
Expand Down
Loading