How to Ignore Dynamic Elements in Argos CI Visual Comparisons
Keep Argos CI visual comparisons useful when dates, randomized data, animations, or external widgets change between captures. Choose a narrow mask or stabilize the source.
To keep changing content from creating noisy Argos CI visual diffs, first make the test deterministic where practical: freeze dates, use fixed data, and sort results consistently. If the content still must vary, mark the element with data-visual-test: use transparent to hide its contents but preserve its layout space, blackout to obscure its pixels while preserving the region, or removed to remove it from layout.
Use the narrowest treatment that matches the assertion. Hiding content also removes visual coverage: if a date, price, status, or other changing value matters to users, stabilize it rather than mask it.
1. Choose whether to stabilize, hide, mask, or remove
| Situation | First choice | Alternative |
|---|---|---|
| Date, clock, or timestamp | Freeze the test clock or pass a fixed date. | transparent if the text varies but its space and surrounding layout should still be checked. |
| Randomized records or inconsistent ordering | Use a fixed fixture or seed and deterministic sorting. | Hide only the unstable data area if fixed fixtures are impractical. |
| Content should remain in place but its pixels are irrelevant | Use blackout. |
Use transparent when the content should disappear visually rather than be obscured. |
| An element itself creates layout shifts | Stabilize or finish the animation. | Use removed if the element should not occupy layout space. |
| External widget not under test | Prevent its script from loading in the test environment. | Inject CSS to hide it if it cannot be disabled at the source. |
| A fixed, non-DOM screen region such as a status bar | Stabilize or hide it at capture time if supported by the environment. | Use a coordinate mask for a consistently irrelevant rectangle. |
Argos documents automatic handling for CSS animations. TSX-driven animations may need to be paused or completed manually. If an animation changes layout, transparency can leave the shifting geometry in place; stabilize it or consider removing the element instead.
2. Mark a dynamic DOM element with data-visual-test
Add the attribute to the smallest element whose changing pixels should not participate in the comparison. These examples show the three behaviors:
<!-- Hide the changing text but preserve its space -->
<div id="clock" data-visual-test="transparent">10:42</div>
<!-- Obscure pixels but keep the region present -->
<div class="user-avatar" data-visual-test="blackout">
<img src="/avatar.jpg" alt="">
</div>
<!-- Remove the element from layout -->
<div class="animated-promo" data-visual-test="removed">
Promotional content
</div>What each value means
transparent: the element’s visible content is hidden while its layout space remains. This is often suitable for variable text, dates, or avatars when the geometry around them is still meaningful.blackout: the region is masked while remaining in place. Use it when the contents are irrelevant but the area should continue to exist in the comparison.removed: the element is removed from rendered layout. This can help when the element’s presence or animation is itself causing layout movement.
Do not mark a broad parent container just because one child changes. A wide mask can hide meaningful changes elsewhere in the page. Keep the attribute close to the unstable content and review whether the resulting screenshot still checks the UI behavior you care about.
3. Prefer deterministic test inputs when possible
Masking makes comparisons quieter, but it also means changes in the masked content cannot alert you to regressions. A stable input preserves more coverage. In your test setup:
- Freeze the application clock to a known instant when dates or relative times vary.
- Load a fixed fixture or seed randomized data generators.
- Sort records with a deterministic key, including a tie-breaker where needed.
- Wait for data and layout to settle before capture.
- Only then mask content that genuinely cannot be made deterministic and is outside the test’s purpose.
If the changing value is part of the user-visible behavior, assert it separately or keep it visible in the visual comparison with a fixed test value. For example, a screenshot test for a billing page should generally use a fixed date and amount rather than mask the entire invoice summary.
4. Handle animations, scripts, and iframes
Animations
Argos guidance says CSS animations are automatically paused where applicable. Confirm the captured state is the one your test intends to validate. For animations implemented in TSX or application logic, pause them, disable them under a test flag, or wait for a known completion state. If you cannot control the animation, choose the attribute behavior based on layout: transparent preserves space; removed does not.
External scripts and embedded content
For analytics, chat, advertising, or third-party widgets that are not part of the test, the most stable option is to prevent the external script from loading in the test environment. If the script must load, inject CSS to hide its UI. If an iframe’s content is part of the assertion, wait for it to become ready instead of masking it. Cross-origin frame contents may not be controllable from the application page, so the test integration’s capture behavior and the frame provider’s readiness need to be considered.
CSS injection and coordinate masks
Argos also documents CSS injection through argosScreenshot and coordinate masks for fixed regions. An Argos stabilization example for WebDriverIO uses a mask shaped like { x: 0, y: 0, width: 1170, height: 120 }. Treat that as an illustration, not a version-independent recipe: check the reference for the SDK and integration version in your lockfile before using a particular API signature.
DOM attributes and injected CSS are usually easier to maintain when tied to a specific element. Coordinate masks can be useful for a stable screen rectangle with no convenient DOM selector, but viewport changes or responsive layout can make the rectangle cover the wrong content.
5. Distinguish masking from ignoring a reviewed change
A mask suppresses a region from future comparisons, so meaningful changes inside it may no longer be reported. Ignoring a specific already-reviewed change is a different review control: Argos’s July 20, 2025 changelog says that ignoring a specific change leaves different changes in the same region detectable. Prefer a targeted review action when the observed difference is acceptable but future changes in that area still matter.
Argos’s March 10, 2026 changelog says changes detected as flaky are auto-ignored by default, with the repetition threshold configurable in project settings. This can help manage review workflow, but it does not make screenshot capture stable and is not a replacement for fixing a flaky test when the UI is under test.
6. Troubleshooting noisy or misleading diffs
| Symptom | Likely cause | Fix |
|---|---|---|
| The text disappears but the surrounding layout still shifts. | transparent preserves the element’s space; another element or animation is changing geometry. |
Stabilize the changing layout, wait for the settled state, or use removed only if removing that element is appropriate. |
| A large section stops reporting real visual changes. | The attribute, CSS rule, or coordinate mask covers too much. | Narrow the selector or rectangle to the smallest unstable region and recheck the baseline. |
| The element is still visible in the screenshot. | The attribute may be on the wrong node, added after capture, or unsupported by the integration/version in use. | Confirm the attribute is present before capture and consult the Argos reference for the installed integration version. For CSS injection, confirm the rule matches the rendered element. |
| A masked rectangle covers different content at another viewport. | Coordinate masks are tied to screen positions, while responsive layout moved the UI. | Use an element-level approach or define viewport-specific capture handling if the integration supports it. |
| An iframe or third-party widget changes between runs. | External content is nondeterministic or not ready at capture time. | Disable the script in tests if it is not under test; otherwise wait for a ready state or hide only its irrelevant UI. |
| Flaky diffs continue after enabling auto-ignore. | Auto-ignore affects review handling, not the rendering source of instability. | Stabilize the clock, data, animation, resource loading, or capture timing. Use ignore controls only for reviewed differences. |
7. Performance, reliability, and coverage
Stabilizing the source of variation often improves both reliability and diagnosis: when fixtures and capture state are repeatable, a diff is more likely to represent an application change. Masking itself is a capture or comparison rule, not a substitute for deterministic loading. Avoid adding long arbitrary delays as a general fix; wait for a meaningful selector or known application-ready condition where your test setup allows it.
Each ignored region carries a coverage cost. Record why the area is unstable and why it is outside the test’s assertion, keep the rule narrow, and revisit it when the UI or test environment changes. Prefer element-specific handling for responsive content and reserve coordinate masks for stable fixed regions. For a noisy difference that has already been reviewed, use the review workflow rather than disabling future comparisons for the entire area.
8. Or skip the browser setup
If you need a rendered page image outside an Argos CI comparison, ScreenshotNeo provides a website screenshot API and MCP server. Its API captures a URL in one GET request and can return PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Those are useful for rendered captures and agent workflows; Argos remains the tool described above for CI visual comparison and diff review.
Sign up free for 1,000 screenshots a month with no card.
FAQ
Does transparent remove the element from the page?
No. It hides the element’s visible content while keeping its space in the layout. Use removed when the element should no longer occupy space.
Should I mask a changing price?
Only if the price is outside the purpose of the test. If the price is meaningful, use a fixed test fixture and keep it under visual or functional assertion.
Can I use a coordinate mask for a responsive page?
You can when the relevant region stays at the same screen coordinates for the captures being compared. If it moves across viewports, use an element-based rule or another stable capture setup.
Does Argos flaky-change auto-ignore fix the underlying test?
No. It changes how detected flaky diffs are handled in review. Stabilize rendering when the changing UI itself should remain covered.
