# WebdriverIO

Canonical: https://snapvisor.io/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 [#install]

```bash
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 [#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:

```bash
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 [#capture-screenshots]

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

```ts
// 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 [#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:

```ts
await argosScreenshot(browser, "homepage", {
  mask: ["#clock", { x: 0, y: 0, width: 100, height: 40 }],
  remove: [".cookie-banner"],
});
```

| Option      | Description                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `mask`      | Selectors or `{ x, y, width, height }` rectangles (in screenshot pixels) to cover with a solid box. |
| `maskColor` | CSS color of the mask box. Defaults to `#FF00FF`.                                                   |
| `hide`      | Selectors to make transparent. The element keeps its space in the layout.                           |
| `remove`    | Selectors to remove from the layout.                                                                |
| `argosCSS`  | CSS applied only while the screenshot is taken.                                                     |

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

## Upload [#upload]

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

```bash
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:

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

In GitHub Actions:

```yaml
- 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](/ci-integration#upload-options).

