Skip to main content
Version: v4.15

Visual Testing

WebdriverIO supports visual testing capabilities out of the box through a plugin called @wdio/visual-service. It uses ResembleJS under the hood to do pixel perfect comparisons.

Adding Visual Testing to your Setup

If you don't have a WebdriverIO project set up yet, please take a look at the set up instructions we provide on the WebdriverIO Overview page.

Once you are set up, add the visual plugin to your project via:

npm install --save-dev @wdio/visual-service

A plugin, also called service in WebdriverIO, has access to a variety of test lifecycle hooks to enable new functionality or integrate with another platform. To use a service, add it to your services list in your wdio.conf.ts:

wdio.conf.ts
// Test runner services
// Services take over a specific job you don't want to take care of. They enhance
// your test setup with almost no effort. Unlike plugins, they don't add new
// commands. Instead, they hook themselves up into the test process.
services: [['visual', {
baselineFolder: path.resolve(__dirname, '__snapshots__'),
screenshotPath: path.resolve(__dirname, '__snapshots__', '.tmp')
}]],

As shown in the Visual Testing WebdriverIO documentation, the service adds 4 new matchers to visually assert your application:

  • toMatchScreenSnapshot: captures and compares the whole browser screen
  • toMatchElementSnapshot: captures and compares the visual difference within the element boundaries
  • toMatchFullPageSnapshot: captures and compares the whole document
  • toMatchTabbablePageSnapshot: same as toMatchFullPageSnapshot with tab marks for accessibility testing

In the context of testing StencilJS components the best choice is to use toMatchElementSnapshot to verify a single component visually. Such a test may appear as follows:

src/components/my-component/my-component.test.tsx
it('looks visually perfect', async () => {
render({
components: [MyComponent],
template: () => <my-component first="looking" last="'visually perfect' 👌" />
});

const component = $('my-component')
await expect(component).toMatchElementSnapshot('MyComponent')
});

The screenshots will be generated locally and the baseline should be checked into your project, so that everyone running the tests visually, compare against the same assumptions. If a test is failing, e.g. we set the color of the text to a different color, WebdriverIO will let the test fail with the following message:

Expected image to have a mismatch percentage of 0%, but was 6.488%
Please compare the images manually and update the baseline if the new screenshot is correct.

Baseline: /stencil-project/__snapshots__/MyComponent-chrome-1200x1551-dpr-2.png
Actual Screenshot: /stencil-project/__snapshots__/.tmp/actual/MyComponent-chrome-1200x1551-dpr-2.png
Difference: /stencil-project/__snapshots__/.tmp/diff/MyComponent-chrome-1200x1551-dpr-2.png

See https://webdriver.io/docs/api/visual-regression.html for more information.

You can see the visual differences highlighted in /stencil-project/__snapshots__/.tmp/diff which can look as following:

Example of visual difference

If you believe the visual changes are correct, update the baseline by moving the image from stencil-project/__snapshots__/.tmp/actual into the baseline directory.

For further information on Visual Testing in WebdriverIO visit their documentation page.