Skip to main content
Version: v4.18

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:


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:


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 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.