Skip to content

feat: add waitForBackgroundImages stabilization plugin - #324

Merged
gregberge merged 1 commit into
mainfrom
wait-for-background-images
Jun 26, 2026
Merged

gregberge merged 1 commit into
mainfrom
wait-for-background-images

Conversation

@gregberge

Copy link
Copy Markdown
Member

Summary

Adds an opt-in stabilization plugin that waits for CSS background images to load before taking a screenshot. Resolves argos-ci/argos#1943, where background images (especially responsive ones that re-fetch on viewport resize) weren't awaited and produced flaky screenshots.

There's no native load event for CSS background images, so the plugin discovers URLs with getComputedStyle and preloads them via Image objects, polling .complete. To keep the cost in check (the original workaround in the issue ran getComputedStyle over the whole DOM):

  • Off by default / opt-in — a new optIn flag on the plugin system. stabilize: true does not enable it; only explicit config does.
  • Scopable by selector — defaults to the whole document so it "just works" when enabled, but large pages can narrow it (and teammates don't have to remember per-element data- attributes).
  • Scan once, poll cheap — the expensive sweep runs once per viewport in beforeEach; wait.for only checks the preloaded images.

Like waitForImages, a failed background image (e.g. 404) is treated as "done" so it never blocks stabilization. The scan also covers ::before/::after, a common home for decorative backgrounds.

Usage

// whole document
argosScreenshot(page, name, { stabilize: { waitForBackgroundImages: true } });
// scoped
argosScreenshot(page, name, {
  stabilize: { waitForBackgroundImages: { selector: ".hero, [data-bg]" } },
});

Changes

  • New plugin waitForBackgroundImages (packages/browser).
  • Plugin system: optIn flag (off unless explicitly enabled) and per-plugin option values passed into hooks; new exported WaitForBackgroundImagesOptions type that flows through to the Playwright/Cypress stabilize option.
  • E2e tests + a #background-image fixture element. The image request is gated via context.route (deterministic, not timing-based): with the plugin enabled the screenshot stays blocked until the image loads; with it disabled the screenshot completes even though the image is permanently stuck.

Known limitation

Because the scan runs in beforeEach, background images added to the DOM during the wait window aren't caught (unlike <img>, which waitForImages re-reads live). This is the trade-off for keeping wait.for cheap — fine for the responsive-viewport case in the issue.

🤖 Generated with Claude Code

Add an opt-in plugin that waits for CSS background images to be loaded
before taking a screenshot, addressing #1943.

There is no native load event for CSS background images, so URLs are
discovered with getComputedStyle and preloaded through Image objects.
The plugin is opt-in because the scan is resource-intensive, and it can
be scoped to a selector to avoid a full-document sweep:

  stabilize: { waitForBackgroundImages: true }
  stabilize: { waitForBackgroundImages: { selector: ".hero, [data-bg]" } }

The expensive scan runs once per viewport in `beforeEach`; `wait.for`
only polls the preloaded images. To support this, plugins gained an
`optIn` flag (off unless explicitly enabled) and now receive their own
option value in their hooks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
argos-js-sdk-reference Ready Ready Preview, Comment Jun 26, 2026 7:50am

Request Review

@gregberge
gregberge merged commit c37e520 into main Jun 26, 2026
68 checks passed
@gregberge
gregberge deleted the wait-for-background-images branch June 26, 2026 08:50
gregberge added a commit to argos-ci/docs that referenced this pull request Jun 26, 2026
Add the new opt-in `waitForBackgroundImages` stabilization option
(argos-ci/argos-javascript#324) to the Playwright, Cypress, and Puppeteer
SDK references, making it explicit that it is disabled by default and must
be enabled explicitly. Add a dedicated "Wait for background images" page to
the flaky tests playbook covering responsive/decorative background images,
and wire it into SUMMARY.md and the playbook index.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
Preview — 8d052295 Deployed Jun 26, 2026 by vercel[bot]
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.

Argos not reliably waiting for background images to download

2 participants