Repository navigation
feat: add waitForBackgroundImages stabilization plugin - #324
Merged
Merged
Conversation
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>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
jsfez
approved these changes
Jun 26, 2026
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
getComputedStyleand preloads them viaImageobjects, polling.complete. To keep the cost in check (the original workaround in the issue rangetComputedStyleover the whole DOM):optInflag on the plugin system.stabilize: truedoes not enable it; only explicit config does.data-attributes).beforeEach;wait.foronly 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
Changes
waitForBackgroundImages(packages/browser).optInflag (off unless explicitly enabled) and per-plugin option values passed into hooks; new exportedWaitForBackgroundImagesOptionstype that flows through to the Playwright/Cypressstabilizeoption.#background-imagefixture element. The image request is gated viacontext.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>, whichwaitForImagesre-reads live). This is the trade-off for keepingwait.forcheap — fine for the responsive-viewport case in the issue.🤖 Generated with Claude Code