Skip to content

chore(web): bump jsdom to 31.0.1 - #1441

Merged
mforce merged 4 commits into
mainfrom
chore/jsdom-31
Nov 14, 2026
Merged

mforce merged 4 commits into
mainfrom
chore/jsdom-31

Conversation

@mforce

@mforce mforce commented Nov 14, 2026

Copy link
Copy Markdown
Owner

Bumps jsdom in web/ from 30.1.3 to 31.0.1 and updates the web tests that depended on jsdom 30's CSS handling. This supersedes #1426, Dependabot's jsdom 31.0.0 bump. I chose to refactor first (#1437 added the phone mode seam) and then upgrade by hand. No product code changes behaviour. One commit corrects comments in web/src/lib/breakpoints.ts.

What changed in jsdom 31

  • jsdom 31 applies CSS media rules against a fixed 1024×768 viewport. jsdom 30 ignored @media rules, so both the phone and the desktop variant of every { xs, md } switch rendered. Under 31, phone-only UI (the tab bar, the More sheet, phone-only labels) is display: none in every test. jsdom has no matchMedia, and a matchMedia stub cannot change which CSS media rules jsdom applies.
  • jsdom 31 resolves var() in computed styles. jsdom 30 returned the raw var(--token) string, and many assertions compared against that string. Tests load no app stylesheet, so under 31 an undefined token falls back to the inherited or initial value, and two different tokens compute the same colour.
  • It also serializes some values the way a browser does: media text, box-shadow, transition durations and the outline shorthand.

Without test changes, jsdom 31 fails 97 tests in 21 files. After this PR the full web suite passes: 184 files and 4,428 tests, the same count as main at 16830d14.

Lock changes

npm install --save-dev jsdom@31.0.1 regenerated the lock.

Package Before After
jsdom 30.1.3 31.0.1
entities 8.0.0 9.0.0 (major; only parse5 under jsdom uses it)
parse5 8.0.1 8.1.1
whatwg-url 17.2.0 17.3.0
parse5-parser-stream, bcp-47, bcp-47-match, is-alphabetical, is-alphanumerical, is-decimal absent added
@asamuzakjp/css-color, @asamuzakjp/dom-selector, @bramus/specificity, @csstools/color-helpers, @csstools/css-calc, @csstools/css-color-parser, @csstools/css-parser-algorithms, @csstools/css-syntax-patches-for-csstree, @csstools/css-tokenizer, bidi-js, css-tree, mdn-data present removed (jsdom 30's CSS engine)

jsdom 31 needs Node 22 or later. web/package.json already requires Node 26.

Test changes

(a) Tests that mean the phone layout now force it. BottomNav, the AppLayout bottom-tab cases, the UpdatePrompt More-menu integration and the AppLayout More-menu sign-out case call stubMatchMedia(false) from src/test/matchMedia.ts. These components go through the phone mode seam, so a stubbed matchMedia sets a literal display.

(a′) Phone-only elements with a plain sx media rule. The OrderLines price summary (an sr-only span) and the TwoFactorFlow "Open in your authenticator app" link use display: { xs: "inline", md: "none" } directly. stubMatchMedia cannot reach them, so jsdom 31 always applies the desktop rule. Each test now:

  1. checks the phone and desktop media rules with the existing responsiveStyle helper;
  2. checks that the element has no inline display;
  3. sets the phone display inline, so the accessibility tree includes the element;
  4. runs the original assertions again: the row's accessible name, and the link's role, name and href.

(b) Changes caused by jsdom 31's CSS engine.

  • Every computed-style assertion that named a token now names it through cssVar("--token") instead of the string "var(--token)". This covers the toHaveStyle checks in nine route test files, the Connect, Login and Settings getComputedStyle checks, and the Field Console footer guard in src/test/ledgerCellStyles.ts.
  • FlocksPage media text: min-width:0px became min-width: 0px, and the same for 900px.
  • FarmThemeProvider box-shadow: inset 0 2px 0 0 #4a154b became rgb(74, 21, 75) 0px 2px inset.
  • FarmThemeProvider transition durations: 240ms and 160ms became 0.24s and 0.16s.
  • SettingsPage focus outline: 2px solid became 2px solid rgb(2, 136, 209).
  • Login now compares backgroundColor instead of the background shorthand.

The cssVar helper

src/test/cssVar.ts gives each undefined token its own value on :root during a test, and setup.ts removes those values after each test. cssVar(name, property, scope) returns what property: var(name) computes inside scope. A token the component defines locally keeps its real value.

Without it, the 19 not.toHaveStyle({ color: "var(--x)" }) assertions and the 3 negative Login checks passed no matter which colour the element used. The Field Console row guard also stopped seeing masked rows, because a row coloured with an undefined token computes the same as its parent. The helper gives back the distinction that jsdom 30's raw strings provided. It does not stub matchMedia or change how jsdom applies media rules.

Seam guard

With no matchMedia, usePhoneMode() returns null and the CSS media rule decides. Under jsdom 31 that is the desktop layout at 1024px. The "no matchMedia" case in phoneModeSeam.test.tsx now asserts the sidebar is in the accessibility tree and the tab bar is not. It also checks that the tab bar still has its { xs: block, md: none } media rule. A forced answer sets a literal display and adds no media rule, so this check tells "the CSS decides" apart from "forced desktop".

Mutations

Each mutation was applied to product code, run, and reverted.

Mutation Tests that fail
usePhoneMode returns false instead of null without matchMedia seam guard, no-matchMedia case
Field Console footer colour var(--ink) changed to var(--muted) ledger guard, 5 periodComparison tests
Field Console edit link colour changed to var(--error) GradesPage "edit is not destructive"
aria-hidden="true" on the OrderLines price summary both "manifest prices available to screen readers" cases
aria-hidden="true" on the TwoFactorFlow app link Security enrolment case
style={{ display: "none" }} on the OrderLines price summary both manifest price cases
style={{ display: "none" }} on the TwoFactorFlow app link Security enrolment case

My local review ran three rounds:

  • Round 1 found that the (a′) tests had lost their screen-reader assertions. I restored them behind the inline display override.
  • Round 2 found that the override would hide inline display: none written in the component. I added the no-inline-display check.
  • Round 3 found nothing. The reviewer's eight hiding mutations (inline display: none, aria-hidden, hidden and visibility: hidden on each of the two elements) all fail the committed tests.

Verification

  • npm run typecheck
  • npm run lint
  • npm run test: 184 files, 4,428 tests (97 failures before the test changes)
  • npm run build

Docs-impact: none - a dev dependency bump and test changes; no user-visible strings or help content change.

jsdom 31 evaluates CSS media queries at a fixed 1024x768 viewport and
resolves var() in computed styles. Tests now force the phone layout with
stubMatchMedia where they mean it, and name design tokens through a
cssVar test helper that gives each undefined token its own value, so a
computed colour still tells tokens apart. Assertions on serialized CSS
(media text, box-shadow, transition) follow jsdom 31's browser-style
forms.
…nd app link

After pinning each element's phone media rule, the test applies that display inline so the accessibility tree includes it, then asserts the row's accessible name and the link's role and name as before jsdom 31.
The tests set the phone display inline to read the accessibility tree; assert the element had no inline display first, so inline hiding in the component still fails them.
@mforce
mforce merged commit f0f8ab9 into main Nov 14, 2026
21 checks passed
@mforce
mforce deleted the chore/jsdom-31 branch November 14, 2026 20:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant