fix: activate a page in a background tab before a check or save command

[dprevost-LMI]

Summary

In a WebDriver BiDi session with a Chromium-based browser, a check or save command on a page in a background tab could pass without a comparison, or hang for 180 seconds. The visual service now brings that page to the front before the command, as ChromeDriver does for a WebDriver Classic screenshot.

Replaces #1270 (its test commit is included here).

Problem

In WebdriverIO v10, browser.newWindow() does not switch to the new tab, but Chrome brings the new tab to the front. The page of the browser commands is then in a background tab (document.visibilityState is hidden). On Linux headless Chrome (the CI platform):

• Wrong file name, no comparison: the hidden page reports outerHeight = innerHeight, and the desktop file name uses the outer size. With autoSaveBaseline (the default), the check saved a new baseline and returned 0. Found in CI: the newWindow() test saved …-1366x625.png and …-1366x768.png for the same page and never compared.
• Hang: browsingContext.captureScreenshot on the hidden page never returned, until bidiResponseTimeout (180 s by default). Found in CI on refactor: find a stale ignore element again with WebdriverIO #1254.

WebDriver Classic does not have these problems, because ChromeDriver brings the tab to the front before a screenshot (ActivateWebView in ExecuteScreenshot). Our BiDi path did not.

Root cause: a Chromium bug

The hang also happens with the Chrome DevTools Protocol only, without WebDriver: Page.captureScreenshot on a page in a background tab never returns when the page had no new frame for about 300 ms. Pure CDP reproduction (Puppeteer, Chrome 154, 10 runs per mode):

Platform	Background tab	Foreground tab	Background + Page.bringToFront
Linux x64 (Docker)	10/10 hang	0/10	0/10
macOS arm64	0/10	0/10	0/10

Firefox 157 (BiDi) does not hang.

Reported:

• Chromium: https://issues.chromium.org/issues/571157133
• WebDriver BiDi spec (the steps of browsingContext.captureScreenshot do not say what to do for a hidden page): browsingContext.captureScreenshot: what should happen for a navigable that is not visible (background tab)? w3c/webdriver-bidi#1176

Changes

Fix (@wdio/visual-service, patch changeset)

• New activateHiddenBrowsingContext(): if document.visibilityState is hidden, call browsingContext.activate for the current context, and log it. Any error only logs a warning, so the command never fails because of this step.
• Scope: BiDi sessions of Chromium-based desktop browsers (Chrome, Chromium, Edge), web context, and only when the page is hidden. Firefox, Safari, mobile, native context and WebDriver Classic sessions do not change.
• Not limited to Linux: the browser can run on another OS than the test runner (grid, cloud), the hang is also reported on macOS with Chrome 149 (agent-browser#1437), and Windows was not tested. The cost is one execute call per command.
• Called in wrapWithContext(), so before every check and save command (single browser, multiremote, page and element), before the page size is read and the screenshot is taken.
• Side effect: the tab of the page comes to the front, the same as with a Classic screenshot.
• The JSDoc explains why, and links both reports. When Chromium fixes the bug, we can limit the step to older Chrome versions or remove it.

Test

• The newWindow() e2e test checks that the second check uses the same baseline file as the first one (so a new name fails instead of passing), that the mismatch is 0, and that page A is visible after the check. Page B is blue and page A is red, so a screenshot of the wrong tab fails.
• The local Chrome v10 config (also used by the Jasmine suite) names the files without {width}x{height}: it runs one fixed Chrome.
• Unit tests for the helper: hidden, visible, Classic/mobile/native, Chrome/Edge/Chromium names, Firefox, an activation error and an execute error. A unit test for the call order in wrapWithContext(). The old wrapWithContext tests passed the browser with the wrong key (browser instead of browserInstance); corrected.

Test

• pnpm test (lint, types, unit): pass.
• Local Chrome v10 suites (Mocha, Jasmine, emulation): pass on macOS.
• Linux container (Chrome 155), the same platform as CI:

Variant	Before	After
This branch	—	2 passing
Tab B left open	hang, 180 s	2 passing in 5 s
{width}x{height} in the file name	2 names (625 / 768), no comparison	1 baseline, a real comparison

Notes

• bidiResponseTimeout (WebdriverIO, 180 s by default) already ends a hung command, so the service does not add another timeout. This fix removes the cause.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 35f959f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@wdio/visual-service	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Visual service now activates background tabs before screenshots.

The PR appears safe to merge; no actionable defects were found.

What we checked:

• Every capture reaches activation: Single-browser and multiremote page and element commands all use wrapWithContext, which calls activation before running the command.
• The test still checks zero: The configuration removes the baseline folder before the run. The first check copies the captured image into the baseline and compares against it, so the second result must also report zero.

Summary

The visual service brings hidden Chromium desktop tabs to the front before BiDi check and save commands.

• Activation runs before the command reads page sizes and takes a screenshot.
• Classic, mobile, native, and non-Chromium sessions skip this step.
• Tests cover activation, skipped cases, errors, and stable comparison filenames.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Check or save command] --> B[Desktop Chromium BiDi session?]
  B -->|No| E[Run existing command]
  B -->|Yes| C[Read page visibility]
  C -->|Visible| E
  C -->|Hidden| D[Activate current tab]
  D --> E
  C -->|Error| W[Log warning]
  D -->|Error| W
  W --> E
  E --> F[Read page sizes and capture image]

Loading

_{Reviews (2) · Last reviewed commit: "test: compare the 2 results of the newWi..." · Reviewed by Greptile}