Snapvisor Docs

WebdriverIO

Capture screenshots from WebdriverIO tests with @snapvisor/webdriverio, upload them with the Snapvisor CLI and review visual changes on pull requests.

@snapvisor/webdriverio saves screenshots from your WebdriverIO tests to a folder, and @snapvisor/cli uploads that folder as a build. Snapvisor compares each screenshot with the approved baseline and reports the result as a status check on your pull request.

The package is a fork of the Argos WebdriverIO SDK. That is why the screenshot function is still called argosScreenshot and the project token is still read from ARGOS_TOKEN: the names are kept so a pipeline already wired for Argos works unchanged.

Install

npm install --save-dev @snapvisor/webdriverio @snapvisor/cli

Node.js 22 or newer is required, and webdriverio has to be installed in the project (versions 6 to 10 are supported).

Configure the token

Create a project in the Snapvisor app, then copy its project token from the project's settings under Authentication. Set it as ARGOS_TOKEN, and store it as a secret in CI:

export ARGOS_TOKEN="<your-project-token>"

No change to wdio.conf.ts is needed. The package does not register a service or a reporter; you call it from your tests.

Capture screenshots

Call argosScreenshot with the browser object and a name. It saves a PNG to ./screenshots/argos/<name>.png.

// test/specs/home.e2e.ts
import { browser } from "@wdio/globals";
import { argosScreenshot } from "@snapvisor/webdriverio";

describe("Homepage", () => {
  it("matches the approved screenshot", async () => {
    await browser.url("http://localhost:3000");
    await $("h1").waitForDisplayed();
    await argosScreenshot(browser, "homepage");
  });
});

Use a different name for each screenshot, otherwise the later file replaces the earlier one.

No automatic stabilization

Unlike the Playwright adapter, the WebdriverIO adapter does not freeze animations or wait for fonts and images before it captures. Wait for the content you want to compare before you call argosScreenshot, for example with waitForDisplayed(), and mask or remove anything that changes between runs:

await argosScreenshot(browser, "homepage", {
  mask: ["#clock", { x: 0, y: 0, width: 100, height: 40 }],
  remove: [".cookie-banner"],
});
OptionDescription
maskSelectors or { x, y, width, height } rectangles (in screenshot pixels) to cover with a solid box.
maskColorCSS color of the mask box. Defaults to #FF00FF.
hideSelectors to make transparent. The element keeps its space in the layout.
removeSelectors to remove from the layout.
argosCSSCSS applied only while the screenshot is taken.

You can also add data-visual-test="blackout", "transparent" or "removed" to elements in your application.

Upload

The adapter does not upload by itself. Run your tests, then upload the screenshots folder with the CLI:

npx wdio run wdio.conf.ts
npx @snapvisor/cli upload ./screenshots/argos

The first build on your base branch becomes the baseline, and later builds are compared against it. Review and approve the changes in the Snapvisor app.

Add --wait to make the step wait for the build to finish. It exits 0 when the build is accepted or has no changes, and 1 when it needs review, is rejected or the wait times out, so unreviewed changes fail the CI job:

npx @snapvisor/cli upload ./screenshots/argos --wait

In GitHub Actions:

- run: npx wdio run wdio.conf.ts
- run: npx @snapvisor/cli upload ./screenshots/argos --wait
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

Other upload options, such as --build-name and parallel shards, are described in CI integration.

On this page