> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/reference/puppeteer.md).

# Puppeteer

Puppeteer already offers a command to take screenshots. The official Argos Puppeteer integration uses it but also does several things:

* Ensuring all images are fully loaded.
* Ensuring all fonts are rendered.
* Confirming the absence of any `aria-busy` (loading) elements on the page.
* Concealing scrollbars.
* Obscuring text cursors or carets.
* Providing CSS utilities to simplify content hiding.

### Installation

{% stepper %}
{% step %}

### Install package

```
npm install --save-dev @argos-ci/cli @argos-ci/puppeteer
```

{% endstep %}

{% step %}

### Use in your tests

`argosScreenshot` command stabilizes the UI and takes a screenshot.

*How to take a screenshot with `argosScreenshot` command*

```js
import puppeteer from "puppeteer";
import { argosScreenshot } from "@argos-ci/puppeteer";

describe("Integration test with visual testing", () => {
  it("loads the homepage", async () => {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();
    await page.goto("http://localhost:3000");
    await argosScreenshot(page, "homepage");
    await browser.close();
  });
});
```

Screenshots are stored in `screenshots/argos` folder, relative to current directory.
{% endstep %}
{% endstepper %}

### API Overview

#### argosScreenshot(page, name\[, options])

* `page` - A `puppeteer` page instance
* `name` - The screenshot name; must be unique. If it ends with `.png`, it is treated as a path.
* `options` - See [Page.screenshot command options](https://pptr.dev/api/puppeteer.page.screenshot)
* `options.element` - Accept an ElementHandle or a string selector to screenshot an element
* `options.viewports` - Specifies the viewports for which to capture screenshots. See [viewports configuration](/docs/learn/how-to-guides/visual-coverage/responsive-viewports.md).
* `options.argosCSS`: Specific CSS applied during the screenshot process. More on [injecting CSS](/docs/learn/how-to-guides/visual-coverage/injecting-css.md)
* `options.disableHover`: Disable hover effects by moving the mouse to the top-left corner of the page. Defaults to `true`.
* `options.threshold`: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Defaults to `0.5`.
* `options.baseName`: Name, or list of names, to compare this screenshot against instead of its own name. Useful to compare a variant against an existing screenshot. More on [fallback baselines](/docs/learn/how-to-guides/visual-coverage/fallback-baselines.md).
* `options.stabilize`: Wait for the UI to stabilize before taking the screenshot. Set to `false` to disable stabilization. Pass an object to customize the stabilization. Defaults to `true`.
* `options.stabilize.disableSpellCheck`: Disable spell check before taking the screenshot. Defaults to `true`.
* `options.stabilize.fontAntialiasing`: Force font antialiasing. Defaults to `true`.
* `options.stabilize.hideCarets`: Hide text carets before taking the screenshot. Defaults to `true`.
* `options.stabilize.hideScrollbars`: Hide scrollbars before taking the screenshot. Defaults to `true`.
* `options.stabilize.loadImageSrcset`: Force the loading of images with `srcset` attributes when the viewport changes. Defaults to `true`.
* `options.stabilize.pauseGifs`: Pause animated GIFs on their first frame so they don't capture a random frame on each run. Defaults to `true`. Flag GIFs served from extension-less URLs with `data-image-type="gif"` so they're detected too.
* `options.stabilize.roundImageSize`: Round image sizes to the nearest integer. Defaults to `true`.
* `options.stabilize.stabilizeSticky`: Stabilize sticky and fixed elements by switching to `position: absolute`. Defaults to `true`.
* `options.stabilize.waitForAriaBusy`: Wait for the `aria-busy` attribute to be removed from the document. Defaults to `true`.
* `options.stabilize.waitForFonts`: Wait for fonts to be loaded. Defaults to `true`.
* `options.stabilize.waitForImages`: Wait for images to be loaded. Defaults to `true`.
* `options.stabilize.waitForBackgroundImages`: Wait for CSS background images (including `::before`/`::after`) to load before taking the screenshot. Enabled by default, scoped to elements flagged with the `data-visual-test-wait-bg-img` attribute (and their descendants). Pass `true` to scan the whole document, `{ selector: string }` to target a custom selector, or `false` to disable it. A failed image (e.g. a 404) is treated as loaded so it never blocks stabilization.
* `options.tag`: Tag or array of tags to attach to the screenshot for filtering in Argos.

Unlike [Puppeteer's `screenshot` method](https://pptr.dev/api/puppeteer.page.screenshot), `argosScreenshot` sets the `fullPage` option to `true` by default. Override it if you prefer partial screenshots of your pages.

### Helper Attributes for Visual Testing

For tailored visual testing, the `data-visual-test` attributes provide control over how elements appear in Argos screenshots. This can be especially useful for obscuring or modifying elements with dynamic content, like dates.

* `[data-visual-test="transparent"]`: Renders the element transparent (`visibility: hidden`).
* `[data-visual-test="removed"]`: Removes the element from view (`display: none`).
* `[data-visual-test-no-radius]`: Strips the border radius from the element.

**Example: Using a helper attribute to hide a div from the captured screenshot:**

```html
<div id="clock" data-visual-test="transparent">...</div>
```

### Additional Resources

* [Quickstart with Argos + Puppeteer](/docs/quickstart/puppeteer-quickstart.md)
* [@argos-ci/puppeteer on GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/puppeteer)
* [@argos-ci/puppeteer on npm](https://www.npmjs.com/package/@argos-ci/puppeteer)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://argos-ci.com/docs/reference/puppeteer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.