Skip to main content

Argos Puppeteer SDK

Integrating Argos with your Puppeteer tests to enable visual testing on your application.

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​

1. Install package​

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

2. Use in your tests​

argosScreenshot command stabilizes the UI and takes a screenshot.

How to take a screenshot with argosScreenshot command

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(TEST_URL);
    await argosScreenshot(page, this.test.fullTitle());
  });
});

Screenshots are stored in screenshots/argos folder, relative to current directory.

API Overview​

argosScreenshot(page, name[, options])​

  • page - A puppeteer page instance
  • name - The screenshot name; must be unique. If ends by .png we treat it as a path.
  • options - See Page.screenshot command options
  • 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.
  • options.argosCSS: Specific CSS applied during the screenshot process. More on injecting CSS
  • options.disableHover: Disable hover effects by moving the mouse to the top-left corner of the page. Default to true.
  • options.threshold: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to 0.5.
  • 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. Default to true.
  • options.stabilize.ariaBusy: Wait for the aria-busy attribute to be removed from the document. Default to true.
  • options.stabilize.fonts: Wait for fonts to be loaded. Default to true.
  • options.stabilize.images: Wait for images to be loaded. Default to true.

Unlike Puppeteer's screenshot method, argosScreenshot set fullPage option to true by default. Feel free to override this option 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 (visiblity: hidden).
  • [data-visual-test="removed"]: Removes the element from view (display: none).
  • [data-visual-test="blackout"]: Masks the element with a blackout effect.
  • [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:

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

Additional Resources​