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/cliNode.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"],
});| 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
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/argosThe 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 --waitIn 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.
GitHub Actions recipes
Copy-paste GitHub Actions workflows for Snapvisor with Playwright, plus how builds behave in merge queues, shallow checkouts, fork pull requests and re-runs.
Run on a preview deployment
Run Playwright or Cypress against a Vercel preview URL from a GitHub Actions deployment_status workflow, and upload the screenshots to Snapvisor with the right branch and commit.