website/docs/visual-testing/service-options.md
Service options are the options that can be set when the service is instantiated and will be used for each method call.
// wdio.conf.(js|ts)
export const config = {
// ...
// =====
// Setup
// =====
services: [
[
"visual",
{
// The options
},
],
],
// ...
};
addressBarShadowPaddingnumber6The padding needs to be added to the address bar on iOS and Android to do a proper cutout of the viewport.
autoElementScrollbooleantrueThis option allows you to disable the automatic scrolling of the element into the view when an element screenshot is created.
addIOSBezelCornersbooleanfalseAdd bezel corners and notch/dynamic island to the screenshot for iOS devices.
:::info NOTE This can only be done when the device name CAN automatically be determined and matches the following list of normalized device names. Normalizing will be done by this module. iPhone:
iphonexiphonexsiphonexsmaxiphonexriphone11iphone11proiphone11promaxiphone12iphone12miniiphone12proiphone12promaxiphone13iphone13miniiphone13proiphone13promaxiphone14iphone14plusiphone14proiphone14promax
iPads:ipadminiipadairipadairipadpro11ipadpro11ipadpro11ipadpro129ipadpro129ipadpro129
:::autoSaveBaselinebooleantrueIf no baseline image is found during the comparison the image is automatically copied to the baseline folder.
alwaysSaveActualImagebooleantrueWhen setting this option to false it will:
createJsonReportFiles is set to true. It will also show a warning in the logs that createJsonReportFiles is disabledThis should create a better performance because no files are writting to the system and should make sure that there's not a lot of noise in the actual folder.
baselineFolderstring|()=> string.path/to/testfile/__snapshots__/The directory that will hold all the baseline images that are used during the comparison. If not set, the default value will be used which will store the files in a __snapshots__/-folder next to the spec that executes the visual tests. A function that returns a string can also be used to set the baselineFolder value:
{
baselineFolder: path.join(process.cwd(), 'foo', 'bar', 'baseline')
},
// OR
{
baselineFolder: () => {
// Do some magic here
return path.join(process.cwd(), 'foo', 'bar', 'baseline');
}
}
clearRuntimeFolderbooleanfalseDelete runtime folder (actual & `diff) on initialization
:::info NOTE
This will only work when the screenshotPath is set through the plugin options, and WILL NOT WORK when you set the folders in the methods
:::
createJsonReportFiles (NEW)booleanfalseYou now have the option to export the compare results into a JSON report file. By providing the option createJsonReportFiles: true, each image that is compared will create a report stored in the actual folder, next to each actual image result. The output will look like this:
{
"parent": "check methods",
"test": "should fail comparing with a baseline",
"tag": "examplePageFail",
"instanceData": {
"browser": {
"name": "chrome-headless-shell",
"version": "126.0.6478.183"
},
"platform": {
"name": "mac",
"version": "not-known"
}
},
"commandName": "checkScreen",
"boundingBoxes": {
"diffBoundingBoxes": [
{
"left": 1088,
"top": 717,
"right": 1186,
"bottom": 730
}
//....
],
"ignoredBoxes": [
{
"left": 159,
"top": 652,
"right": 356,
"bottom": 703
}
//...
]
},
"fileData": {
"actualFilePath": "/Users/wdio/visual-testing/.tmp/actual/desktop_chrome-headless-shellexamplePageFail-local-chrome-latest-1366x768.png",
"baselineFilePath": "/Users/wdio/visual-testing/localBaseline/desktop_chrome-headless-shellexamplePageFail-local-chrome-latest-1366x768.png",
"diffFilePath": "/Users/wdio/visual-testing/.tmp/diff/desktop_chrome-headless-shell/examplePageFail-local-chrome-latest-1366x768png",
"fileName": "examplePageFail-local-chrome-latest-1366x768.png",
"size": {
"actual": {
"height": 768,
"width": 1366
},
"baseline": {
"height": 768,
"width": 1366
},
"diff": {
"height": 768,
"width": 1366
}
}
},
"misMatchPercentage": "12.90",
"rawMisMatchPercentage": 12.900729014153246
}
When all tests are executed, a new JSON file with the collection of the comparisons will be generated and can be found in the root of your actual folder. The data is grouped by:
describe for Jasmine/Mocha or Feature for CucumberJSit for Jasmine/Mocha or Scenario for CucumberJS
and then sorted by:commandName, which are the compare method names used to compare the imagesinstanceData, browser first, then device, then platform
it will look like this[
{
"description": "check methods",
"data": [
{
"test": "should fail comparing with a baseline",
"data": [
{
"tag": "examplePageFail",
"instanceData": {},
"commandName": "checkScreen",
"framework": "mocha",
"boundingBoxes": {
"diffBoundingBoxes": [],
"ignoredBoxes": []
},
"fileData": {},
"misMatchPercentage": "14.34",
"rawMisMatchPercentage": 14.335403703025868
},
{
"tag": "exampleElementFail",
"instanceData": {},
"commandName": "checkElement",
"framework": "mocha",
"boundingBoxes": {
"diffBoundingBoxes": [],
"ignoredBoxes": []
},
"fileData": {},
"misMatchPercentage": "1.34",
"rawMisMatchPercentage": 1.335403703025868
}
]
}
]
}
]
The report data will give you the opportunity to build your own visual report without doing all the magic and data collection yourself.
:::info NOTE
You need to use @wdio/visual-testing version 5.2.0 or higher
:::
disableBlinkingCursorbooleanfalseEn/Disable all input, textarea, [contenteditable] caret "blinking" in the application. If set to true the caret will be set to transparent before taking a screenshot
and reset when done
disableCSSAnimationbooleanfalseEn/Disable all CSS animations in the application. If set to true all animations will be disabled before taking a screenshot
and reset when done
enableLayoutTestingbooleanfalseThis will hide all text on a page so only the layout will be used for comparison. Hiding will be done by adding the style 'color': 'transparent !important' to each element.
For the output see Test Output
:::info
By using this flag each element that contains text (so not only p, h1, h2, h3, h4, h5, h6, span, a, li, but also div|button|..) will get this property. There is no option to tailor this.
:::
formatImageNamestring{tag}-{browserName}-{width}x{height}-dpr-{dpr}The name of the saved images can be customized by passing the parameter formatImageName with a format string like:
{tag}-{browserName}-{width}x{height}-dpr-{dpr}
The following variables can be passed to format the string and will automatically be read from the instance capabilities. If they can't be determined the defaults will be used.
browserName: The name of the browser in the provided capabilitiesbrowserVersion: The version of the browser provided in the capabilitiesdeviceName: The device name from the capabilitiesdpr: The device pixel ratioheight: The height of the screenlogName: The logName from capabilitiesmobile: This will add _app, or the browser name after the deviceName to distinguish app screenshots from browser screenshotsplatformName: The name of the platform in the provided capabilitiesplatformVersion: The version of the platform provided in the capabilitiestag: The tag that is provided in the methods that is being calledwidth: The width of the screen:::info
You can not provide custom paths/folders in the formatImageName. If you want to change the path then please check changing the following options:
baselineFolderscreenshotPathfolderOptions per method:::
fullPageScrollTimeoutnumber1500The timeout in milliseconds to wait after a scroll. This might help identify pages with lazy loading.
:::info
This will only work when the service/method option userBasedFullPageScreenshot is set to true, see also userBasedFullPageScreenshot
:::
hideScrollBarsbooleantrueHide scrollbars in the application. If set to true all scrollbars will be disabled before taking a screenshot. This is set to default true to prevent extra issues.
logLevelstringinfoAdds extra logs, options are debug | info | warn | silent
Errors are always logged to the console.
savePerInstancebooleanfalseSave the images per instance in a separate folder so for example all Chrome screenshots will be saved in a Chrome folder like desktop_chrome.
screenshotPathstring | () => string.tmp/The directory that will hold all the actual/different screenshots. If not set, the default value will be used. A function that returns a string can also be used to set the screenshotPath value:
{
screenshotPath: path.join(process.cwd(), 'foo', 'bar', 'screenshotPath')
},
// OR
{
screenshotPath: () => {
// Do some magic here
return path.join(process.cwd(), 'foo', 'bar', 'screenshotPath');
}
}
toolBarShadowPaddingnumber6 for Android and 15 for iOS (6 by default and 9 will be added automatically for the possible home bar on iPhones with a notch or iPads that have a home bar)The padding which needs to be added to the toolbar bar on iOS and Android to do a proper cutout of the viewport.
userBasedFullPageScreenshotbooleanfalseBy default, full-page screenshots on desktop web are captured using the WebDriver BiDi protocol, which enables fast, stable, and consistent screenshots without scrolling. When userBasedFullPageScreenshot is set to true, the screenshot process simulates a real user: scrolling through the page, capturing viewport-sized screenshots, and stitching them together. This method is useful for pages with lazy-loaded content or dynamic rendering that depends on scroll position.
Use this option if your page relies on content loading while scrolling or if you want to preserve the behavior of older screenshot methods.
waitForFontsLoadedbooleantrueFonts, including third-party fonts, can be loaded synchronously or asynchronously. Asynchronous loading means that fonts might load after WebdriverIO determines that a page has fully loaded. To prevent font rendering issues, this module, by default, will wait for all fonts to be loaded before taking a screenshot.
:::info NOTE
This module also supports drawing the way a user would use his keyboard to tab through the website by drawing lines and dots from tabbable element to tabbable element.
The work is inspired by Viv Richards his blog post about "AUTOMATING PAGE TABABILITY (IS THAT A WORD?) WITH VISUAL TESTING".
The way tabbable elements are selected is based on the module tabbable. If there are any issues regarding the tabbing please check the README.md and especially the More details section.
:::
tabbableOptionsobjectThe options that can be changed for the lines and dots if you use the {save|check}Tabbable-methods. The options are explained below.
tabbableOptions.circleobjectThe options to change the circle.
tabbableOptions.circle.backgroundColorstringThe background color of the circle.
tabbableOptions.circle.borderColorstringThe border color of the circle.
tabbableOptions.circle.borderWidthnumberThe border width of the circle.
tabbableOptions.circle.fontColorstringThe color of the font of the text in the circle. This will only be shown if showNumber is set to true.
tabbableOptions.circle.fontFamilystringThe family of the font of the text in the circle. This will only be shown if showNumber is set to true.
Make sure to set fonts that are supported by the browsers.
tabbableOptions.circle.fontSizenumberThe size of the font of the text in the circle. This will only be shown if showNumber is set to true.
tabbableOptions.circle.sizenumberThe size of the circle.
tabbableOptions.circle.showNumbershowNumberShow the tab sequence number in the circle.
tabbableOptions.lineobjectThe options to change the line.
tabbableOptions.line.colorstringThe color of the line.
tabbableOptions.line.widthnumberThe width of the line.
compareOptionsobjectThe compare options can also be set as service options, they are described in the Method Compare options