Service Options

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
            },
        ],
    ],
    // ...
};

Default Options

`addressBarShadowPadding`

Type: number
Mandatory: No
Default: 6
Supported: Web

The padding needs to be added to the address bar on iOS and Android to do a proper cutout of the viewport.

`autoElementScroll`

Type: boolean
Mandatory: No
Default: true
Supported: Web, Hybrid App (Webview)

This option allows you to disable the automatic scrolling of the element into the view when an element screenshot is created.

`addIOSBezelCorners`

Type: boolean
Mandatory: No
Default: false
Supported: Web, Hybrid App (Webview), Native App

Add bezel corners and notch/dynamic island to the screenshot for iOS devices.

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:

iPhone X: iphonex
iPhone XS: iphonexs
iPhone XS Max: iphonexsmax
iPhone XR: iphonexr
iPhone 11: iphone11
iPhone 11 Pro: iphone11pro
iPhone 11 Pro Max: iphone11promax
iPhone 12: iphone12
iPhone 12 Mini: iphone12mini
iPhone 12 Pro: iphone12pro
iPhone 12 Pro Max: iphone12promax
iPhone 13: iphone13
iPhone 13 Mini: iphone13mini
iPhone 13 Pro: iphone13pro
iPhone 13 Pro Max: iphone13promax
iPhone 14: iphone14
iPhone 14 Plus: iphone14plus
iPhone 14 Pro: iphone14pro
iPhone 14 Pro Max: iphone14promax iPads:
iPad Mini 6th Generation: ipadmini
iPad Air 4th Generation: ipadair
iPad Air 5th Generation: ipadair
iPad Pro (11-inch) 1st Generation: ipadpro11
iPad Pro (11-inch) 2nd Generation: ipadpro11
iPad Pro (11-inch) 3rd Generation: ipadpro11
iPad Pro (12.9-inch) 3rd Generation: ipadpro129
iPad Pro (12.9-inch) 4th Generation: ipadpro129
iPad Pro (12.9-inch) 5th Generation: ipadpro129

`autoSaveBaseline`

Type: boolean
Mandatory: No
Default: true
Supported: Web, Hybrid App (Webview), Native App

If no baseline image is found during the comparison the image is automatically copied to the baseline folder.

`baselineFolder`

Type: any
Mandatory: No
Default: .path/to/testfile/__snapshots__/
Supported: Web, Hybrid App (Webview), Native App

The directory 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 accepts an option object can also be used to set the baselineFolder value:

{
    baselineFolder: (options) => {
        const testFolder = path.dirname(options.specs[0]);
        return path.join(testFolder, "snapshots", type);
    };
}

`clearRuntimeFolder`

Type: boolean
Mandatory: No
Default: false
Supported: Web, Hybrid App (Webview), Native App

Delete runtime folder (actual & `diff) on initialization

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)

Type: boolean
Mandatory: No
Default: false

You 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 CucumberJS
it for Jasmine/Mocha or Scenario for CucumberJS and then sorted by:
commandName, which are the compare method names used to compare the images
instanceData, 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.

NOTE

You need to use @wdio/visual-testing version 5.2.0 or higher

`disableCSSAnimation`

Type: boolean
Mandatory: No
Default: false
Supported: Web, Hybrid App (Webview)

En/Disable all CSS animations and the input caret and the input caret in the application. If set to true all animations will be disabled before taking a screenshot and reset when done

`enableLayoutTesting`

Type: boolean
Mandatory: No
Default: false
Supported: Web

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

`formatImageName`

Type: string
Mandatory: No
Default: {tag}-{browserName}-{width}x{height}-dpr-{dpr}
Supported: Web, Hybrid App (Webview), Native App

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 capabilities
browserVersion: The version of the browser provided in the capabilities
deviceName: The device name from the capabilities
dpr: The device pixel ratio
height: The height of the screen
logName: The logName from capabilities
mobile: This will add _app, or the browser name after the deviceName to distinguish app screenshots from browser screenshots
platformName: The name of the platform in the provided capabilities
platformVersion: The version of the platform provided in the capabilities
tag: The tag that is provided in the methods that is being called
width: The width of the screen

`fullPageScrollTimeout`

Type: number
Mandatory: No
Default: 1500
Supported: Web

The timeout in milliseconds to wait after a scroll. This might help identify pages with lazy loading.

`hideScrollBars`

Type: boolean
Mandatory: No
Default: true
Supported: Web, Hybrid App (Webview)

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

`isHybridApp`

Type: boolean
Mandatory: No
Default: false
Supported: Hybrid App

Tell the module if the used app is a Hybrid app, this will not calculate the address bar height because it is not there.

`logLevel`

Type: string
Mandatory: No
Default: info
Supported: Web, Hybrid App (Webview), Native App

Adds extra logs, options are debug | info | warn | silent

Errors are always logged to the console.

`savePerInstance`

Type: boolean
Default: false
Mandatory: no
Supported: Web, Hybrid App (Webview), Native App

Save the images per instance in a separate folder so for example all Chrome screenshots will be saved in a Chrome folder like desktop_chrome.

`screenshotPath`

Type: any
Default: .tmp/
Mandatory: no
Supported: Web, Hybrid App (Webview), Native App

The directory that will hold all the actual/different screenshots. If not set, the default value will be used. A function that accepts an option object can also be used to set the screenshotPath value:

getFolder = type = (options) => {
    const testFolder = path.dirname(options.specs[0]);

    return path.join(testFolder, "snapshots", type);
};
{
    screenshotPath: getFolder(options);
}

`toolBarShadowPadding`

Type: number
Mandatory: No
Default: 6 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)
Supported: Web

The padding which needs to be added to the toolbar bar on iOS and Android to do a proper cutout of the viewport.

Tabbable Options

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.

`tabbableOptions`

Type: object
Mandatory: No
Default: See here for all default values
Supported: Web

The options that can be changed for the lines and dots if you use the {save|check}Tabbable-methods. The options are explained below.

`tabbableOptions.circle`

Type: object
Mandatory: No
Default: See here for all default values
Supported: Web

The options to change the circle.

`tabbableOptions.circle.backgroundColor`

Type: string
Mandatory: No
Default: See here for all default values
Supported: Web

The background color of the circle.

`tabbableOptions.circle.borderColor`

Type: string
Mandatory: No
Default: See here for all default values
Supported: Web

The border color of the circle.

`tabbableOptions.circle.borderWidth`

Type: number
Mandatory: No
Default: See here for all default values
Supported: Web

The border width of the circle.

`tabbableOptions.circle.fontColor`

Type: string
Mandatory: No
Default: See here for all default values
Supported: Web

The color of the font of the text in the circle. This will only be shown if showNumber is set to true.

`tabbableOptions.circle.fontFamily`

Type: string
Mandatory: No
Default: See here for all default values
Supported: Web

The 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.fontSize`

Type: number
Mandatory: No
Default: See here for all default values
Supported: Web

The size of the font of the text in the circle. This will only be shown if showNumber is set to true.

`tabbableOptions.circle.size`

Type: number
Mandatory: No
Default: See here for all default values
Supported: Web

The size of the circle.

`tabbableOptions.circle.showNumber`

Type: showNumber
Mandatory: No
Default: See here for all default values
Supported: Web

Show the tab sequence number in the circle.

`tabbableOptions.line`

Type: object
Mandatory: No
Default: See here for all default values
Supported: Web

The options to change the line.

`tabbableOptions.line.color`

Type: string
Mandatory: No
Default: See here for all default values
Supported: Web

The color of the line.

`tabbableOptions.line.width`

Type: number
Mandatory: No
Default: See here for all default values
Supported: Web

The width of the line.

`waitForFontsLoaded`

Type: boolean
Mandatory: No
Default: true
Supported: Web, Hybrid App (Webview)

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

Compare options

The compare options can also be set as service options, they are described in the Method Compare options

Default Options​

addressBarShadowPadding​

autoElementScroll​

addIOSBezelCorners​

autoSaveBaseline​

baselineFolder​

clearRuntimeFolder​

createJsonReportFiles (NEW)​

disableCSSAnimation​

enableLayoutTesting​

formatImageName​

fullPageScrollTimeout​

hideScrollBars​

isHybridApp​

logLevel​

savePerInstance​

screenshotPath​

toolBarShadowPadding​

Tabbable Options​

tabbableOptions​

tabbableOptions.circle​

tabbableOptions.circle.backgroundColor​

tabbableOptions.circle.borderColor​

tabbableOptions.circle.borderWidth​

tabbableOptions.circle.fontColor​

tabbableOptions.circle.fontFamily​

tabbableOptions.circle.fontSize​

tabbableOptions.circle.size​

tabbableOptions.circle.showNumber​

tabbableOptions.line​

tabbableOptions.line.color​

tabbableOptions.line.width​

waitForFontsLoaded​

Compare options​

Default Options

`addressBarShadowPadding`

`autoElementScroll`

`addIOSBezelCorners`

`autoSaveBaseline`

`baselineFolder`

`clearRuntimeFolder`

`createJsonReportFiles` (NEW)

`disableCSSAnimation`

`enableLayoutTesting`

`formatImageName`

`fullPageScrollTimeout`

`hideScrollBars`

`isHybridApp`

`logLevel`

`savePerInstance`

`screenshotPath`

`toolBarShadowPadding`

Tabbable Options

`tabbableOptions`

`tabbableOptions.circle`

`tabbableOptions.circle.backgroundColor`

`tabbableOptions.circle.borderColor`

`tabbableOptions.circle.borderWidth`

`tabbableOptions.circle.fontColor`

`tabbableOptions.circle.fontFamily`

`tabbableOptions.circle.fontSize`

`tabbableOptions.circle.size`

`tabbableOptions.circle.showNumber`

`tabbableOptions.line`

`tabbableOptions.line.color`

`tabbableOptions.line.width`

`waitForFontsLoaded`

Compare options