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
- Yarn
- pnpm
npm install --save-dev @wdio/visual-service
yarn add --dev @wdio/visual-service
pnpm add --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
:
// 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 screentoMatchElementSnapshot
: captures and compares the visual difference within the element boundariestoMatchFullPageSnapshot
: captures and compares the whole documenttoMatchTabbablePageSnapshot
: same astoMatchFullPageSnapshot
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:
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:
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.