Pause animated GIFs

Freeze animated GIFs on their first frame with the pauseGifs stabilization option so they no longer capture a random frame on each run.

Animated GIFs keep playing while your test runs, so each screenshot captures whatever frame happens to be on screen at capture time. That frame is non-deterministic—it depends on network timing, CPU load, and how long stabilization took—so a GIF turns an otherwise-stable page into a flaky one.

The pauseGifs stabilization option removes that source of noise: it freezes every animated GIF on its first frame before the screenshot is taken, then restores the original animation afterwards.

This is on by default. Setting stabilize: true (the default) already pauses GIFs—there's nothing to configure unless you want to turn it off.

How it works

For each <img> that resolves to a GIF, the SDK loads a fresh copy of the image and draws its first decoded frame to a canvas—an already-rendered <img> has been animating since it loaded, so its current frame is unpredictable. The static frame is swapped in for the screenshot and the original GIF is put back once the capture is done.

A cross-origin GIF served without the right CORS headers taints the canvas and can't be frozen; those are left animating rather than blocking the screenshot.

Flagging GIFs that aren't detected automatically

The SDK recognizes GIFs from their URL—a .gif extension or a data:image/gif URI. A GIF served from a URL that carries neither (for example a CDN endpoint like /media/1234) can't be detected this way, so it keeps animating.

Flag those images explicitly with the data-image-type="gif" attribute and they'll be paused like any other GIF:

<img src="https://cdn.example.com/media/1234" data-image-type="gif" />

Disabling it

If you specifically want to capture the live animation, disable the plugin:

Playwright

await argosScreenshot(page, "homepage", {
  stabilize: { pauseGifs: false },
});

Cypress

See the full stabilize option reference for every stabilization setting.