Image Comparison (Visual Regression Testing) Service

@wdio/visual-service is a 3rd party package, for more information please see GitHub | npm

For documentation on visual testing with WebdriverIO, please refer to the docs. This project contains all relevant modules for running visual tests with WebdriverIO. Within the ./packages directory you will find:

• @wdio/visual-testing: the WebdriverIO service for integrating visual testing
• webdriver-image-comparison: An image compare module that can be used for different NodeJS Test automation frameworks that support the WebDriver protocol

Storybook Runner (BETA)

Click to find out more documentation about the Storybook Runner BETA

Storybook Runner is still in BETA, the docs will later move to the WebdriverIO documentation pages.

This module now supports Storybook with a new Visual Runner. This runner automatically scans for a local/remote storybook instance and will create element screenshots of each component. This can be done by adding

export const config: Options.Testrunner = {
    // ...
    services: ['visual'],
    // ....
}

to your services and running npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook through the command line. It will use Chrome in headless mode as the default browser.

[!NOTE]

• Most of the Visual Testing options will also work for the Storybook Runner, see the WebdriverIO documentation.
• The Storybook Runner will overwrite all your capabilities and can only run on the browsers that it supports, see --browsers.
• The Storybook Runner does not support an existing config that uses Multiremote capabilities and will throw an error.
• The Storybook Runner only supports Desktop Web, not Mobile Web.

Storybook Runner Service Options

Service options can be provided like this

export const config: Options.Testrunner = {
    // ...
    services: [
      [
        'visual',
        {
            // Some default options
            baselineFolder: join(process.cwd(), './__snapshots__/'),
            debug: true,
            // The storybook options, see cli options for the description
            storybook: {
                clip: false,
                clipSelector: ''#some-id,
                numShards: 4,
                // `skipStories` can be a string ('example-button--secondary'),
                // an array (['example-button--secondary', 'example-button--small'])
                // or a regex which needs to be provided as as string ("/.*button.*/gm")
                skipStories: ['example-button--secondary', 'example-button--small'],
                url: 'https://www.bbc.co.uk/iplayer/storybook/',
                version: 6,
            },
        },
      ],
    ],
    // ....
}

Storybook Runner CLI options

--browsers

• Type: string
• Mandatory: No
• Default: chrome, you can select from chrome|firefox|edge|safari
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --browsers=chrome,firefox,edge,safari
• NOTE: Only available through the CLI

It will use the provided browsers to take component screenshots

[!NOTE] Make sure you have the browsers you want to run on installed on your local machine

--clip

• Type: boolean
• Mandatory: No
• Default: true
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --clip=false

When disabled it will create a viewport screenshot. When enabled it will create element screenshots based on the --clipSelector which will reduce the amount of whitespace around the component screenshot and reduce the screenshot size.

--clipSelector

• Type: string
• Mandatory: No
• Default: #storybook-root > :first-child for Storybook V7 and #root > :first-child:not(script):not(style) for Storybook V6, see also --version
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --clipSelector="#some-id"

This is the selector that will be used:

• to select the element to take the screenshot of
• for the element to wait to be visible before a screenshot is taken

--devices

• Type: string
• Mandatory: No
• Default: You can select from the deviceDescriptors.ts
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --devices="iPhone 14 Pro Max","Pixel 3 XL"
• NOTE: Only available through the CLI

It will use the provided devices that match the deviceDescriptors.ts to take component screenshots

[!NOTE]

• If you miss a device config, then feel free to submit a Feature request
• This will only work with Chrome:
  • if you provide --devices then all Chrome instances will run in Mobile Emulation mode
  • if you also provide other browser then Chrome, like --devices --browsers=firefox,safari,edge it will automatically add Chrome in Mobile emulation mode
• The Storybook Runner will by default create element snapshots, if you want to see the complete Mobile Emulated screenshot then provide --clip=false through the command line
• The file name will for example look like __snapshots__/example/button/desktop_chrome/example-button--large-local-chrome-iPhone-14-Pro-Max-430x932-dpr-3.png
• SRC: Testing a mobile website on a desktop using mobile emulation can be useful, but testers should be aware that there are many subtle differences such as:
  • entirely different GPU, which may lead to big performance changes;
  • mobile UI is not emulated (in particular, the hiding url bar affects page height);
  • disambiguation popup (where you select one of a few touch targets) is not supported;
  • many hardware APIs (for example, orientationchange event) are unavailable.

--headless

• Type: boolean
• Mandatory: No
• Default: true
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --headless=false
• NOTE: Only available through the CLI

This will run the tests by default in headless mode (when the browser supports it) or can be disabled

--numShards

• Type: number
• Mandatory: No
• Default: true
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --numShards=10

This will be the number of parallel instances that will be used to run the stories. This will be limited by the maxInstances in your wdio.conf-file.

[!IMPORTANT] When running in headless-mode then do not increase the number to more than 20 to prevent flakiness due to resource restrictions

--skipStories

• Type: string|regex
• Mandatory: No
• Default: null
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --skipStories="/.*button.*/gm"

This can be:

• a string (example-button--secondary,example-button--small)
• or a regex ("/.*button.*/gm")

to skip certain stories. Use the id of the story that can be found in the URL of the story. For example, the id in this URL http://localhost:6006/?path=/story/example-page--logged-out is example-page--logged-out

--url

• Type: string
• Mandatory: No
• Default: http://127.0.0.1:6006
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --url="https://example.com"

The URL where your Storybook instance is hosted.

--version

• Type: number
• Mandatory: No
• Default: 7
• Example: npx wdio tests/configs/wdio.local.desktop.storybook.conf.ts --storybook --version=6

This is the version of Storybook, it defaults to 7. This is needed to know if the V6 clipSelector needs to be used.

Contributing

This package depends on node-canvas, make sure you have all required dependencies installed before starting development.

Questions

Please join our Discord Server if you have any questions or issues contributing to this project. Catch us contributors in the 🙏-contributing channel.

Issues

If you have questions, bugs or feature requests, please file an issue. Before submitting an issue, please search the issue archive to help reduce duplicates, and read the FAQ.

If you can't find it there you can submit an issue where you can submit:

• 🐛Bug report: Create a report to help us improve
• 📖Documentation: Suggest improvements or report missing/unclear documentation.
• 💡Feature request: Suggest an idea for this module.
• 💬Question: Ask questions.

Development Workflow

To create a PR for this project and start contributing follow this step-by-step guide:

• Fork the project.

• Clone the project somewhere on your computer

  $ git clone https://github.com/webdriverio/visual-testing.git

• Go to the directory and setup the project

  $ cd visual-testing
  $ pnpm install

• Run the watch mode that will automatically transpile the code

  $ pnpm watch

  to build the project, run:

  $ pnpm build

• Ensure that your changes don't break any tests, run:

  $ pnpm test

This project uses changesets to automatically create changelogs and releases.

Testing

Several tests need to be executed to be able to test the module. When adding a PR all tests must at least pass the local tests. Each PR is automatically tested against Sauce Labs, see our GitHub Actions pipeline. Before approving a PR the core contributors will test the PR against emulators/simulators / real devices.

Local Testing

First, a local baseline needs to be created. This can be done with:

// With the webdriver protocol
$ npm run test.local.init

This command will create a folder called localBaseline that will hold all the baseline images.

Then run:

// With the webdriver protocol
npm run test.local.desktop

This will run all tests on a local machine on Chrome.

Local Storybook Runner Testing (Beta)

First, a local baseline needs to be created. This can be done with:

npm run test.local.desktop.storybook

This will Storybook tests with Chrome in headless mode against a Demo Storybook repo located at https://govuk-react.github.io/govuk-react/.

To run the tests with more browsers you can run

npm run test.local.desktop.storybook -- --browsers=chrome,firefox,edge,safari

[!NOTE] Make sure you have the browsers you want to run on installed on your local machine

CI testing with Sauce Labs (not needed for a PR)

The command below is used to test the build on GitHub Actions, it can only be used there and not for local development.

$ npm run test.saucelabs

It will test against a lot of configurations that can be found here. All PRs are automatically checked against Sauce Labs.

Releasing

To release a version of any of the packages listed above, do the following:

• trigger the release pipeline
• a release PR is generated, have this be reviewed and approved by another WebdriverIO member
• merge the PR
• trigger the release pipeline again
• a new version should be released 🎉

Credits

@wdio/visual-testing uses an open-source license from Sauce Labs.