fix(web): hide the screenshot caret with a stylesheet

Merged
DE
19d ago
+344-10

What and why

The web engine captures the observation screenshot that follows an action, including the automatic trace screen after app.open(), in capturePixels (packages/web/src/observe.ts:62). It passed caret: 'hide' to page.screenshot(). Playwright implements that option by walking every input, textarea, and [contenteditable] in each root, storing the current inline caret-color, setting it to transparent with importance, and restoring it after the frame (playwright-core 1.64, inPagePrepareForScreenshots). A server-rendered React page that is still hydrating during that window sees a style React did not render, compares it with the server HTML, and logs "A tree hydrated but some attributes of the server rendered HTML didn't match the client properties" against its own <input> and <textarea>. The screenshot is fine, the warning is a side effect of the mechanism.

The fix hides the caret with the temporary screenshot stylesheet Playwright already supports. caret: 'initial' turns off the inline-style path, and style: '* { caret-color: transparent !important; }' injects a stylesheet into the page and every frame Playwright can reach for the duration of the capture. caret-color is inherited, so the universal rule also covers elements inside closed shadow roots, which Playwright cannot inject into but the engine masks. No element's style attribute changes, so a framework hydrating at that moment has nothing to flag, and the captured pixels still contain no caret.

Fixes #1259.

What changed

  • packages/web/src/observe.ts: caret: 'hide' becomes caret: 'initial' plus the screenshot stylesheet, with a comment naming the reason so the next reader does not switch it back.
  • packages/web/tests/unit/observe.test.ts: a capturePixels case that asserts the screenshot options. It fails on main because the call passes caret: "hide" and no style.
  • packages/web/tests/integration/screenshot-caret.test.ts: a real Chromium capture on a page with inputs and a textarea, with a MutationObserver watching style attributes across the document. It fails on main with eight mutations and passes here with none. The test launches through BrowserConnection and installs the closed-shadow init script, so the secure-field mask selectors resolve the way they do in a run.
  • .changeset/screenshot-caret-stylesheet.md: a patch for @e2e-dev/web.
  • No docs change. docs/visual-testing.mdx:134 says the web engine hides the text caret, which is still true, and no page describes how it does it.

One path is deliberately unchanged: surface.screenshot (packages/web/src/surface.ts:1024), which serves app.screenshot(), failure evidence, and other artifacts, passes no caret option at all, so Playwright's default applies there. The issue and its reproduction are about the observation and trace screen, so this PR leaves the artifact path alone.

Verified

Ran it locally: yes

  • packages/web, unit and integration:
✓ unit tests/unit/observe.test.ts (3 tests)
✓ integration tests/integration/screenshot-caret.test.ts (1 test)
Test Files 2 passed (2)
      Tests 4 passed (4)
  • The same tests against main: the unit case fails on the option value, and the integration case records eight style attribute mutations, one set and one restore for each of the four editable elements on the fixture page.
Checkmainthis branch
capturePixels screenshot optionscaret: "hide", no stylecaret: "initial" plus * { caret-color: transparent !important; }
style attribute mutations during a real capture80
secure-field masking proven during the same capturetruetrue
  • Full web suite: 567 passed, 9 failed, 1 skipped. Six of the nine are the local Windows baseline: five in tests/unit/install.test.ts fail on ERR_UNSUPPORTED_ESM_URL_SCHEME for a d: path, and tests/integration/cli.test.ts expects exit code 143 while Windows reports SIGTERM. The other three (app-log, lifecycle, semantic-fallback) pass when rerun on their own and failed under the suite's three-worker load.
  • oxlint on the three touched files: 0 warnings, 0 errors. tsc --noEmit in packages/web: clean.

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
  • Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.