# WebdriverIO v10 documentation: Testing Types > 28 pages. Index of all sections: https://webdriver.io/llms.txt --- Source: https://webdriver.io/docs/visual-testing.md # Visual Testing ## What can it do?[​](#what-can-it-do "Direct link to What can it do?") WebdriverIO provides image comparisons on screens, elements or a full-page for * πŸ–₯️ Desktop browsers (Chrome / Firefox / Safari / Microsoft Edge) * πŸ“± Mobile / Tablet browsers (Chrome on Android emulators / Safari on iOS Simulators / Simulators / real devices) via Appium * πŸ“± Native Apps (Android emulators / iOS Simulators / real devices) via Appium (🌟 **NEW** 🌟) * πŸ“³ Hybrid apps via Appium through the [`@wdio/visual-service`](https://www.npmjs.com/package/@wdio/visual-service) which is a lightweight WebdriverIO service. This allows you to: * save or compare **screens/elements/full-page** screens against a baseline * automatically **create a baseline** when no baseline is there * **block out custom regions** and even **automatically exclude** a status and or toolbars (mobile only) during a comparison * increase the element dimensions screenshots * **hide text** during website comparison to: * **improve stability** and prevent font rendering flakiness * only focus on the **layout** of a website * use **different comparison methods** and a set of **additional matchers** for better readable tests * verify how your website will **support tabbing with your keyboard)**, see also [Tabbing through a website](#tabbing-through-a-website) * and much more, see the [service](/docs/visual-testing/service-options.md) and [method](/docs/visual-testing/method-options.md) options The service is a lightweight module to retrieve the needed data and screenshots for all browsers/devices. The comparison power comes from [Pixelmatch](https://github.com/mapbox/pixelmatch), a fast and accurate perceptual image comparison library. Since v11, it measures color differences in the OKLab color space with the HyAB distance (pixelmatch 8), which is closer to how people see colors. Images are processed with [fast-png](https://github.com/image-js/fast-png), a zero-native-dependency PNG codec. NOTE For Native/Hybrid Apps The methods `saveScreen`, `saveElement`, `checkScreen`, `checkElement` and the matchers `toMatchScreenSnapshot` and `toMatchElementSnapshot` can be used for Native Apps/Context. Please use the property `isHybridApp:true` in your service settings when you want to use it for Hybrid Apps. Upgrading from v10? `@wdio/visual-service` **v11** supports only **WebdriverIO v10** (and Node.js 22.23.4+, 24.22.1+ or 26.12.1+). With WebdriverIO v9, stay on `@wdio/visual-service@10`. v11 compares colors with pixelmatch 8 (OKLab color space, HyAB distance) instead of YIQ. The threshold scale and the `ignore*` presets did not change, but **mismatch percentages can differ a little** from v10 for the same images. Your test code does not need to change. If a check depends on an exact mismatch percentage or a tight tolerance, check it again after the upgrade. Some fixes in v11 can also change a baseline once: * **iOS element screenshots of large elements:** for an element that is not fully inside the viewport, the image had the size of the whole element, but the part outside the viewport was black ([appium/appium#22939](https://github.com/appium/appium/issues/22939)). The image now has only the visible part of the element, as on Android. * **Element screenshots with `biDiOrigin: 'viewport'`:** in a WebDriver BiDi session, the screenshot now cuts the element itself, also when the page is scrolled. * **Scroll back:** element checks (with `autoElementScroll`) and full page checks now scroll the page back to where it was. A viewport check that runs right after them can give another image. See the [v11 migration guide](https://github.com/webdriverio/visual-testing/blob/main/docs/v11-migration.md) for all changes. Upgrading from v9 (or lower)? `@wdio/visual-service` **v10** changed the comparison engine from **ResembleJS** to **[Pixelmatch](https://github.com/mapbox/pixelmatch)**. Pixelmatch uses a perceptual (YIQ) color model instead of raw RGB, so mismatch percentages will differ from v9. This means: * **Your test code does not need to change.** All method names, option names, and matchers are identical. * **Your baseline images may need to be updated.** After upgrading, run your test suite and review any visual diffs. You can update individual failing baselines with `--update-visual-baseline`, or delete your entire baseline folder and let `autoSaveBaseline` recreate it from scratch. See the [FAQ](/docs/visual-testing/faq.md#my-visual-tests-fail-with-a-difference-how-can-i-update-my-baseline) for details. ## Installation[​](#installation "Direct link to Installation") The easiest way is to keep `@wdio/visual-service` as a dev-dependency in your `package.json`, via: ``` npm install --save-dev @wdio/visual-service ``` This installs v11, which needs WebdriverIO v10. For a WebdriverIO v9 project, install v10 of the service: ``` npm install --save-dev @wdio/visual-service@10 ``` ## Usage[​](#usage "Direct link to Usage") `@wdio/visual-service` can be used as a normal service. You can set it up in your configuration file with the following: ``` import path from "node:path"; // wdio.conf.ts export const config = { // ... // ===== // Setup // ===== services: [ [ "visual", { // Some options, see the docs for more baselineFolder: path.join(process.cwd(), "tests", "baseline"), formatImageName: "{tag}-{logName}-{width}x{height}", screenshotPath: path.join(process.cwd(), "tmp"), savePerInstance: true, // ... more options }, ], ], // ... }; ``` More service options can be found [here](/docs/visual-testing/service-options.md). Once set up in your WebdriverIO configuration, you can go ahead and add visual assertions to [your tests](/docs/visual-testing/writing-tests.md). ### Capabilities[​](#capabilities "Direct link to Capabilities") To use the Visual Testing module, **you don’t need to add any extra options to your capabilities**. However, in some cases, you may want to add additional metadata to your visual tests, such as a `logName`. The `logName` allows you to assign a custom name to each capability, which can then be included in the image filenames. This is particularly useful for distinguishing screenshots taken across different browsers, devices, or configurations. To enable this, you can define `logName` in the `capabilities` section and ensure the `formatImageName` option in the Visual Testing service references it. Here's how you can set it up: ``` import path from "node:path"; // wdio.conf.ts export const config = { // ... // ===== // Setup // ===== capabilities: [ { browserName: 'chrome', 'wdio-ics:options': { logName: 'chrome-mac-15', // Custom log name for Chrome }, } { browserName: 'firefox', 'wdio-ics:options': { logName: 'firefox-mac-15', // Custom log name for Firefox }, } ], services: [ [ "visual", { // Some options, see the docs for more baselineFolder: path.join(process.cwd(), "tests", "baseline"), screenshotPath: path.join(process.cwd(), "tmp"), // The format below will use the `logName` from capabilities formatImageName: "{tag}-{logName}-{width}x{height}", // ... more options }, ], ], // ... }; ``` #### How it works[​](#how-it-works "Direct link to How it works") 1. Setting Up the `logName`: * In the `capabilities` section, assign a unique `logName` to each browser or device. For example, `chrome-mac-15` identifies tests running on Chrome on macOS version 15. 2. Custom Image Naming: * The `formatImageName` option integrates the `logName` into the screenshot filenames. For example, if the `tag` is homepage and the resolution is `1920x1080`, the resulting filename might look like this: `homepage-chrome-mac-15-1920x1080.png` 3. Benefits of Custom Naming: * Distinguishing between screenshots from different browsers or devices becomes much easier, especially when managing baselines and debugging discrepancies. 4. Note on Defaults: -If `logName` is not set in the capabilities, the `formatImageName` option will show it as an empty string in the filenames (`homepage--15-1920x1080.png`) ### WebdriverIO multi-remote[​](#webdriverio-multi-remote "Direct link to WebdriverIO multi-remote") We also support [multi-remote](https://webdriver.io/docs/multiremote/). To make this work properly make sure that you add `wdio-ics:options` to your capabilities as you can see below. This will make sure that each screenshot will have its own unique name. [Writing your tests](/docs/visual-testing/writing-tests.md) will not be any different in comparison to using the [testrunner](https://webdriver.io/docs/testrunner) ``` // wdio.conf.js export const config = { capabilities: { chromeBrowserOne: { capabilities: { browserName: "chrome", "goog:chromeOptions": { args: ["disable-infobars"], }, // THIS!!! "wdio-ics:options": { logName: "chrome-latest-one", }, }, }, chromeBrowserTwo: { capabilities: { browserName: "chrome", "goog:chromeOptions": { args: ["disable-infobars"], }, // THIS!!! "wdio-ics:options": { logName: "chrome-latest-two", }, }, }, }, }; ``` ### Running Programmatically[​](#running-programmatically "Direct link to Running Programmatically") Here is a minimal example of how to use `@wdio/visual-service` via `remote` options: ``` import { remote } from "webdriverio"; import VisualService from "@wdio/visual-service"; let visualService = new VisualService({ autoSaveBaseline: true, }); const browser = await remote({ logLevel: "silent", capabilities: { browserName: "chrome", }, }); // "Start" the service to add the custom commands to the `browser` visualService.remoteSetup(browser); await browser.url("https://webdriver.io/"); // or use this for ONLY saving a screenshot await browser.saveFullPageScreen("examplePaged", {}); // or use this for validating. Both methods don't need to be combined, see the FAQ await browser.checkFullPageScreen("examplePaged", {}); await browser.deleteSession(); ``` ### Tabbing through a website[​](#tabbing-through-a-website "Direct link to Tabbing through a website") You can check if a website is accessible by using the keyboard `TAB`-key. Testing this part of accessibility has always been a time-consuming (manual) job and pretty hard to do through automation. With the methods `saveTabbablePage` and `checkTabbablePage`, you can now draw lines and dots on your website to verify the tabbing order. Be aware of the fact that this is only useful for desktop browsers and **NOT\*\*** for mobile devices. All desktop browsers support this feature. note The work is inspired by [Viv Richards](https://github.com/vivrichards600) his blog post about ["AUTOMATING PAGE TABABILITY (IS THAT A WORD?) WITH VISUAL TESTING"](https://vivrichards.co.uk/accessibility/automating-page-tab-flows-using-visual-testing-and-javascript). The way tabbable elements are selected is based on the module [tabbable](https://github.com/davidtheclark/tabbable). If there are any issues regarding the tabbing please check the [README.md](https://github.com/davidtheclark/tabbable/blob/master/README.md) and especially the [More ](https://github.com/davidtheclark/tabbable/blob/master/README.md#more-details)Details section. #### How does it work[​](#how-does-it-work "Direct link to How does it work") Both methods will create a `canvas` element on your website and draw lines and dots to show you where your TAB would go if an end-user would use it. After that, it will create a full-page screenshot to give you a good overview of the flow. important \*\*Use the `saveTabbablePage` only when you need to create a screenshot and DON'T want to compare it \*\*with a **baseline** image.\*\*\*\* When you want to compare the tabbing flow with a baseline, then you can use the `checkTabbablePage`-method. You **DON'T** need to use the two methods together. If there is already a baseline image created, which can automatically be done by providing `autoSaveBaseline: true` when you instantiate the service, the `checkTabbablePage` will first create the *actual* image and then compare it against the baseline. ##### Options[​](#options "Direct link to Options") Both methods use the same options as the `saveFullPageScreen` or the `compareFullPageScreen`. #### Example[​](#example "Direct link to Example") This is an example of how the tabbing works on our [guinea pig website](https://guinea-pig.webdriver.io/image-compare.html): ![WDIO tabbing example](/assets/images/tabbable-chrome-latest-1366x768-4ddae1ac2685061fd19ac1375cc02c3d.png) ### Automatically update failed Visual Snapshots[​](#automatically-update-failed-visual-snapshots "Direct link to Automatically update failed Visual Snapshots") Update the baseline images through the command line by adding the argument `--update-visual-baseline`. This will * automatically copy the actual take screenshot and put it in the baseline folder * if there are differences it will let the test pass because the baseline has been updated **Usage:** ``` npm run test.local.desktop --update-visual-baseline ``` When running logs info/debug mode you will see the following logs added ``` [0-0] .............. [0-0] ##################################################################################### [0-0] INFO: [0-0] Updated the actual image to [0-0] /Users/wswebcreation/Git/wdio/visual-testing/localBaseline/chromel/demo-chrome-1366x768.png [0-0] ##################################################################################### [0-0] .......... ``` ## Typescript support[​](#typescript-support "Direct link to Typescript support") This module includes TypeScript support, allowing you to benefit from auto-completion, type safety, and improved developer experience when using the Visual Testing service. ### Step 1: Add Type Definitions[​](#step-1-add-type-definitions "Direct link to Step 1: Add Type Definitions") To ensure TypeScript recognizes the module types, add the following entry to the types field in your tsconfig.json: ``` { "compilerOptions": { "types": ["@wdio/visual-service"] } } ``` ### Step 2: Enable Type Safety for Service Options[​](#step-2-enable-type-safety-for-service-options "Direct link to Step 2: Enable Type Safety for Service Options") To enforce type checking on the service options, update your WebdriverIO configuration: ``` // wdio.conf.ts import { join } from 'node:path'; // Import the type definition import type { VisualServiceOptions } from '@wdio/visual-service'; export const config = { // ... // ===== // Setup // ===== services: [ [ "visual", { // Service options baselineFolder: join(process.cwd(), './__snapshots__/'), formatImageName: '{tag}-{logName}-{width}x{height}', screenshotPath: join(process.cwd(), '.tmp/'), } satisfies VisualServiceOptions, // Ensures type safety ], ], // ... }; ``` ## System Requirements[​](#system-requirements "Direct link to System Requirements") ### Version 10 and up (current)[​](#version-10-and-up-current "Direct link to Version 10 and up (current)") For version 10 and up, this module has no additional system dependencies beyond the general [project requirements](/docs/gettingstarted.md#system-requirements). It uses [Pixelmatch](https://github.com/mapbox/pixelmatch) for perceptual image comparison and [fast-png](https://github.com/image-js/fast-png) for image encoding/decoding. Both are pure JavaScript with zero native dependencies. Version 11 needs WebdriverIO v10 and Node.js 22.23.4+, 24.22.1+ or 26.12.1+. Version 10 works with WebdriverIO v9 (9.29.1 or later) and v10. ### Version 5 to 9 (legacy)[​](#version-5-to-9-legacy "Direct link to Version 5 to 9 (legacy)") Versions 5 through 9 used [Jimp](https://github.com/jimp-dev/jimp), an image processing library for Node written entirely in JavaScript, with zero native dependencies. No additional system dependencies were required. ### Version 4 and Lower[​](#version-4-and-lower "Direct link to Version 4 and Lower") For version 4 and lower, this module relies on [Canvas](https://github.com/Automattic/node-canvas), a canvas implementation for Node.js. Canvas depends on [Cairo](https://cairographics.org/). #### Installation Details[​](#installation-details "Direct link to Installation Details") By default, binaries for macOS, Linux and Windows will be downloaded during your project's `npm install`. If you don't have a supported OS or processor architecture, the module will be compiled on your system. This requires several dependencies, including Cairo and Pango. For detailed installation information, see the [node-canvas wiki](https://github.com/Automattic/node-canvas/wiki/_pages). Below are one-line installation instructions for common operating systems. Note that `libgif/giflib`, `librsvg`, and `libjpeg` are optional and only needed for GIF, SVG, and JPEG support, respectively. Cairo v1.10.0 or later is required. * OS * Ubuntu * Fedora * Solaris * OpenBSD * Window * Others Using [Homebrew](https://brew.sh/): ``` brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman ``` **Mac OS X v10.11+:** If you have recently updated to Mac OS X v10.11+ and are experiencing trouble when compiling, run the following command: `xcode-select --install`. Read more about the problem [on Stack Overflow](http://stackoverflow.com/a/32929012/148072). If you have Xcode 10.0 or higher installed, to build from source you need NPM 6.4.1 or higher. ``` sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev ``` ``` sudo yum install gcc-c++ cairo-devel pango-devel libjpeg-turbo-devel giflib-devel ``` ``` pkgin install cairo pango pkg-config xproto renderproto kbproto xextproto ``` ``` doas pkg_add cairo pango png jpeg giflib ``` See the [wiki](https://github.com/Automattic/node-canvas/wiki/Installation:-Windows) See the [wiki](https://github.com/Automattic/node-canvas/wiki) --- Source: https://webdriver.io/docs/visual-testing/writing-tests.md # Writing Tests ## Testrunner Framework Support[​](#testrunner-framework-support "Direct link to Testrunner Framework Support") `@wdio/visual-service` is test-runner framework agnostic, which means that you can use it with all the frameworks WebdriverIO supports like: * [`Mocha`](https://webdriver.io/docs/frameworks#using-mocha) * [`Jasmine`](https://webdriver.io/docs/frameworks#using-jasmine) * [`CucumberJS`](https://webdriver.io/docs/frameworks#using-cucumber) Within your tests, you can *save* screenshots or match the current visual state of your application under test with a baseline. For that, the service provides [custom matcher](/docs/api/expect-webdriverio.md#visual-matcher), as well as *check* methods: * Mocha * Jasmine * CucumberJS ``` describe('Mocha Example', () => { beforeEach(async () => { await browser.url('https://webdriver.io') }) it('using visual matchers to assert against baseline', async () => { // Check screen to exactly match with baseline await expect(browser).toMatchScreenSnapshot('partialPage') // check an element to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchScreenSnapshot('partialPage', 5) // check an element with options for `saveScreen` command await expect(browser).toMatchScreenSnapshot('partialPage', { /* some options */ }) // Check an element to exactly match with baseline await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement') // check an element to have a mismatch percentage of 5% with the baseline await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement', 5) // check an element with options for `saveElement` command await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement', { /* some options */ }) // Check a full page screenshot match with baseline await expect(browser).toMatchFullPageSnapshot('fullPage') // Check a full page screenshot to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchFullPageSnapshot('fullPage', 5) // Check a full page screenshot with options for `checkFullPageScreen` command await expect(browser).toMatchFullPageSnapshot('fullPage', { /* some options */ }) // Check a full page screenshot with all tab executions await expect(browser).toMatchTabbablePageSnapshot('check-tabbable') // Check a full page screenshot to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchTabbablePageSnapshot('check-tabbable', 5) // Check a full page screenshot with options for `checkTabbablePage` command await expect(browser).toMatchTabbablePageSnapshot('check-tabbable', { /* some options */ }) }) it('should save some screenshots', async () => { // Save a screen await browser.saveScreen('examplePage', { /* some options */ }) // Save an element await browser.saveElement( await $('#element-id'), 'firstButtonElement', { /* some options */ } ) // Save a full page screenshot await browser.saveFullPageScreen('fullPage', { /* some options */ }) // Save a full page screenshot with all tab executions await browser.saveTabbablePage('save-tabbable', { /* some options, use the same options as for saveFullPageScreen */ }) }) it('should compare successful with a baseline', async () => { // Check a screen await expect( await browser.checkScreen('examplePage', { /* some options */ }) ).toEqual(0) // Check an element await expect( await browser.checkElement( await $('#element-id'), 'firstButtonElement', { /* some options */ } ) ).toEqual(0) // Check a full page screenshot await expect( await browser.checkFullPageScreen('fullPage', { /* some options */ }) ).toEqual(0) // Check a full page screenshot with all tab executions await expect( await browser.checkTabbablePage('check-tabbable', { /* some options, use the same options as for checkFullPageScreen */ }) ).toEqual(0) }) }) ``` ``` describe('Jasmine Example', () => { beforeEach(async () => { await browser.url('https://webdriver.io') }) it('using visual matchers to assert against baseline', async () => { // Check screen to exactly match with baseline await expect(browser).toMatchScreenSnapshot('partialPage') // check an element to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchScreenSnapshot('partialPage', 5) // check an element with options for `saveScreen` command await expect(browser).toMatchScreenSnapshot('partialPage', { /* some options */ }) // Check an element to exactly match with baseline await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement') // check an element to have a mismatch percentage of 5% with the baseline await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement', 5) // check an element with options for `saveElement` command await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement', { /* some options */ }) // Check a full page screenshot match with baseline await expect(browser).toMatchFullPageSnapshot('fullPage') // Check a full page screenshot to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchFullPageSnapshot('fullPage', 5) // Check a full page screenshot with options for `checkFullPageScreen` command await expect(browser).toMatchFullPageSnapshot('fullPage', { /* some options */ }) // Check a full page screenshot with all tab executions await expect(browser).toMatchTabbablePageSnapshot('check-tabbable') // Check a full page screenshot to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchTabbablePageSnapshot('check-tabbable', 5) // Check a full page screenshot with options for `checkTabbablePage` command await expect(browser).toMatchTabbablePageSnapshot('check-tabbable', { /* some options */ }) }) it('should save some screenshots', async () => { // Save a screen await browser.saveScreen('examplePage', { /* some options */ }) // Save an element await browser.saveElement( await $('#element-id'), 'firstButtonElement', { /* some options */ } ) // Save a full page screenshot await browser.saveFullPageScreen('fullPage', { /* some options */ }) // Save a full page screenshot with all tab executions await browser.saveTabbablePage('save-tabbable', { /* some options, use the same options as for saveFullPageScreen */ }) }) it('should compare successful with a baseline', async () => { // Check a screen await expect( await browser.checkScreen('examplePage', { /* some options */ }) ).toEqual(0) // Check an element await expect( await browser.checkElement( await $('#element-id'), 'firstButtonElement', { /* some options */ } ) ).toEqual(0) // Check a full page screenshot await expect( await browser.checkFullPageScreen('fullPage', { /* some options */ }) ).toEqual(0) // Check a full page screenshot with all tab executions await expect( await browser.checkTabbablePage('check-tabbable', { /* some options, use the same options as for checkFullPageScreen */ }) ).toEqual(0) }) }) ``` ``` import { When, Then } from '@wdio/cucumber-framework' When('I save some screenshots', async function () { // Save a screen await browser.saveScreen('examplePage', { /* some options */ }) // Save an element await browser.saveElement(await $('#element-id'), 'firstButtonElement', { /* some options */ }) // Save a full page screenshot await browser.saveFullPageScreen('fullPage', { /* some options */ }) // Save a full page screenshot with all tab executions await browser.saveTabbablePage('save-tabbable', { /* some options, use the same options as for saveFullPageScreen */ }) }) Then('I should be able to match some screenshots with a baseline', async function () { // Check screen to exactly match with baseline await expect(browser).toMatchScreenSnapshot('partialPage') // check an element to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchScreenSnapshot('partialPage', 5) // check an element with options for `saveScreen` command await expect(browser).toMatchScreenSnapshot('partialPage', { /* some options */ }) // Check an element to exactly match with baseline await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement') // check an element to have a mismatch percentage of 5% with the baseline await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement', 5) // check an element with options for `saveElement` command await expect($('#element-id')).toMatchElementSnapshot('firstButtonElement', { /* some options */ }) // Check a full page screenshot match with baseline await expect(browser).toMatchFullPageSnapshot('fullPage') // Check a full page screenshot to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchFullPageSnapshot('fullPage', 5) // Check a full page screenshot with options for `checkFullPageScreen` command await expect(browser).toMatchFullPageSnapshot('fullPage', { /* some options */ }) // Check a full page screenshot with all tab executions await expect(browser).toMatchTabbablePageSnapshot('check-tabbable') // Check a full page screenshot to have a mismatch percentage of 5% with the baseline await expect(browser).toMatchTabbablePageSnapshot('check-tabbable', 5) // Check a full page screenshot with options for `checkTabbablePage` command await expect(browser).toMatchTabbablePageSnapshot('check-tabbable', { /* some options */ }) }) Then('I should be able to compare some screenshots with a baseline', async function () { // Check a screen await expect( await browser.checkScreen('examplePage', { /* some options */ }) ).toEqual(0) // Check an element await expect( await browser.checkElement( await $('#element-id'), 'firstButtonElement', { /* some options */ } ) ).toEqual(0) // Check a full page screenshot await expect( await browser.checkFullPageScreen('fullPage', { /* some options */ }) ).toEqual(0) // Check a full page screenshot with all tab executions await expect( await browser.checkTabbablePage('check-tabbable', { /* some options, use the same options as for checkFullPageScreen */ }) ).toEqual(0) }) ``` IMPORTANT This service provides `save` and `check` methods. If you run your tests for the first time you **SHOULD NOT** combine `save` and `compare` methods, the `check`-methods will automatically create a baseline image for you ``` ##################################################################################### INFO: Autosaved the image to /Users/wswebcreation/sample/baselineFolder/desktop_chrome/examplePage-chrome-latest-1366x768.png ##################################################################################### ``` When you've [disabled to automatically save baseline images](/docs/visual-testing/service-options.md#autosavebaseline), the Promise will be rejected with the following warning. ``` ##################################################################################### Baseline image not found, save the actual image manually to the baseline. The image can be found here: /Users/wswebcreation/sample/.tmp/actual/desktop_chrome/examplePage-chrome-latest-1366x768.png ##################################################################################### ``` This means that the current screenshot is saved in the actual folder and you **manually need to copy it to your baseline**. If you instantiate `@wdio/visual-service` with [`autoSaveBaseline: true`](/docs/visual-testing/service-options.md#autosavebaseline) the image will automatically be saved into the baseline folder. --- Source: https://webdriver.io/docs/visual-testing/methods.md # Methods The following methods are added to the global WebdriverIO [`browser`](/docs/api/browser.md)-object. ## Save Methods[​](#save-methods "Direct link to Save Methods") TIP Only use the Save Methods when you **don't** want to compare screens, but only want to have an element-/screenshot. ### `saveElement`[​](#saveelement "Direct link to saveelement") Saves an image of an element. #### Usage[​](#usage "Direct link to Usage") ``` await browser.saveElement( // element await $('#element-selector'), // tag 'your-reference', // saveElementOptions { // ... } ); ``` #### Support[​](#support "Direct link to Support") * Desktop Browsers * Mobile Browsers * Mobile Hybrid Apps * Mobile Native Apps #### Parameters[​](#parameters "Direct link to Parameters") * **`element`:** * **Mandatory:** Yes * **Type:** WebdriverIO Element * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`saveElementOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Save Options](/docs/visual-testing/method-options.md#save-options) #### Output:[​](#output "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#savescreenelementfullpagescreen) page. ### `saveScreen`[​](#savescreen "Direct link to savescreen") Saves an image of a viewport. #### Usage[​](#usage-1 "Direct link to Usage") ``` await browser.saveScreen( // tag 'your-reference', // saveScreenOptions { // ... } ); ``` #### Support[​](#support-1 "Direct link to Support") * Desktop Browsers * Mobile Browsers * Mobile Hybrid Apps * Mobile Native Apps #### Parameters[​](#parameters-1 "Direct link to Parameters") * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`saveScreenOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Save Options](/docs/visual-testing/method-options.md#save-options) #### Output:[​](#output-1 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#savescreenelementfullpagescreen) page. ### `saveFullPageScreen`[​](#savefullpagescreen "Direct link to savefullpagescreen") #### Usage[​](#usage-2 "Direct link to Usage") Saves an image of the complete screen. ``` await browser.saveFullPageScreen( // tag 'your-reference', // saveFullPageScreenOptions { // ... } ); ``` #### Support[​](#support-2 "Direct link to Support") * Desktop Browsers * Mobile Browsers #### Parameters[​](#parameters-2 "Direct link to Parameters") * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`saveFullPageScreenOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Save Options](/docs/visual-testing/method-options.md#save-options) #### Output:[​](#output-2 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#savescreenelementfullpagescreen) page. ### `saveTabbablePage`[​](#savetabbablepage "Direct link to savetabbablepage") Saves an image of the complete screen with the tabbable lines and dots. #### Usage[​](#usage-3 "Direct link to Usage") ``` await browser.saveTabbablePage( // tag 'your-reference', // saveTabbableOptions { // ... } ); ``` #### Support[​](#support-3 "Direct link to Support") * Desktop Browsers #### Parameters[​](#parameters-3 "Direct link to Parameters") * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`saveTabbableOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Save Options](/docs/visual-testing/method-options.md#save-options) #### Output:[​](#output-3 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#savescreenelementfullpagescreen) page. ## Check Methods[​](#check-methods "Direct link to Check Methods") TIP When the `check`-methods are used for the first time you will see the below warning in the logs. This means you don't need to combine the `save`- and `check`-methods if you want to create your baseline. ``` ##################################################################################### Baseline image not found, save the actual image manually to the baseline. The image can be found here: /Users/wswebcreation/project/.tmp/actual/desktop_chrome/examplePage-chrome-latest-1366x768.png If you want the module to auto save a non existing image to the baseline you can provide 'autoSaveBaseline: true' to the options. ##################################################################################### ``` ### `checkElement`[​](#checkelement "Direct link to checkelement") Compare an image of an element against a baseline image. #### Usage[​](#usage-4 "Direct link to Usage") ``` await browser.checkElement( // element '#element-selector', // tag 'your-reference', // checkElementOptions { // ... } ); ``` #### Support[​](#support-4 "Direct link to Support") * Desktop Browsers * Mobile Browsers * Mobile Hybrid Apps * Mobile Native Apps #### Parameters[​](#parameters-4 "Direct link to Parameters") * **`element`:** * **Mandatory:** Yes * **Type:** WebdriverIO Element * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`checkElementOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Compare/Check Options](/docs/visual-testing/method-options.md#compare-check-options) #### Output:[​](#output-4 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#checkscreenelementfullpagescreen) page. ### `checkScreen`[​](#checkscreen "Direct link to checkscreen") Compares an image of a viewport against a baseline image. #### Usage[​](#usage-5 "Direct link to Usage") ``` await browser.checkScreen( // tag 'your-reference', // checkScreenOptions { // ... } ); ``` #### Support[​](#support-5 "Direct link to Support") * Desktop Browsers * Mobile Browsers * Mobile Hybrid Apps * Mobile Native Apps #### Parameters[​](#parameters-5 "Direct link to Parameters") * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`checkScreenOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Compare/Check Options](/docs/visual-testing/method-options.md#compare-check-options) #### Output:[​](#output-5 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#checkscreenelementfullpagescreen) page. ### `checkFullPageScreen`[​](#checkfullpagescreen "Direct link to checkfullpagescreen") Compares an image of the complete screen against a baseline image. #### Usage[​](#usage-6 "Direct link to Usage") ``` await browser.checkFullPageScreen( // tag 'your-reference', // checkFullPageOptions { // ... } ); ``` #### Support[​](#support-6 "Direct link to Support") * Desktop Browsers * Mobile Browsers #### Parameters[​](#parameters-6 "Direct link to Parameters") * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`checkFullPageOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Compare/Check Options](/docs/visual-testing/method-options.md#compare-check-options) #### Output:[​](#output-6 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#checkscreenelementfullpagescreen) page. ### `checkTabbablePage`[​](#checktabbablepage "Direct link to checktabbablepage") Compares an image of the complete screen with the tabbable lines and dots against a baseline image. #### Usage[​](#usage-7 "Direct link to Usage") ``` await browser.checkTabbablePage( // tag 'your-reference', // checkTabbableOptions { // ... } ); ``` #### Support[​](#support-7 "Direct link to Support") * Desktop Browsers #### Parameters[​](#parameters-7 "Direct link to Parameters") * **`tag`:** * **Mandatory:** Yes * **Type:** string * **`checkTabbableOptions`:** * **Mandatory:** No * **Type:** an object of options, see [Compare/Check Options](/docs/visual-testing/method-options.md#compare-check-options) #### Output:[​](#output-7 "Direct link to Output:") See the [Test Output](/docs/visual-testing/test-output.md#checkscreenelementfullpagescreen) page. --- Source: https://webdriver.io/docs/visual-testing/test-output.md # Test Output info [This WebdriverIO](https://guinea-pig.webdriver.io/image-compare.html) demo site has been used for the example image output. ## `enableLayoutTesting`[​](#enablelayouttesting "Direct link to enablelayouttesting") This can be set on the [Service Options](/docs/visual-testing/service-options.md#enablelayouttesting) as well as on the [Method](/docs/visual-testing/method-options.md) level. ``` // wdio.conf.(js|ts) export const config = { // ... // ===== // Setup // ===== services: [ [ 'visual', { enableLayoutTesting: true } ] ] // ... } ``` The image output for the [Service Options](/docs/visual-testing/service-options.md#enablelayouttesting) is equal to the [Method](/docs/visual-testing/method-options.md), see below. ### Image Output[​](#image-output "Direct link to Image Output") * saveElement | checkElement * saveScreen | checkScreen * saveFullPageScreen | checkFullPageScreen * saveTabbablePage | checkTabbablePage ``` await browser.saveElement(".features_vqN4", "example-element-tag", {enableLayoutTesting: true}) // Or await browser.checkElement(".features_vqN4", "example-element-tag", {enableLayoutTesting: true}) ``` ![saveElement Desktop](data:image/png;base64,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) ``` await browser.saveScreen("example-page-tag") ``` ![saveScreen Desktop](/assets/images/layout-viewportScreenshot-chrome-latest-1366x768-13ec028af637ac764a6fb89debeec9df.png) ``` await browser.saveFullPageScreen("full-page-tag") // Or await browser.checkFullPageScreen("full-page-tag", {enableLayoutTesting: true}) ``` ![saveFullPageScreens Desktop](/assets/images/layout-fullPage-chrome-latest-1366x768-564e2a470367c7a53144b7e2cc08f55a.png) ``` await browser.saveTabbablePage("tabbable-page-tag") // Or await browser.checkTabbablePage("tabbable-page-tag", {enableLayoutTesting: true}) ``` ![saveFullPageScreens Desktop](/assets/images/layout-tabbable-chrome-latest-1366x768-84d04569800a5dd7101488003e053cdc.png) ## save(Screen/Element/FullPageScreen)[​](#savescreenelementfullpagescreen "Direct link to save(Screen/Element/FullPageScreen)") ### Console Output[​](#console-output "Direct link to Console Output") The `save(Screen/Element/FullPageScreen)` methods will provide the following information after the method has been executed: ``` const saveResult = await browser.saveFullPageScreen({ ... }) console.log(saveResults) /** * { * // The device pixel ratio of the instance that has run * devicePixelRatio: 1, * // The formatted filename, this depends on the options `formatImageName` * fileName: "examplePage-chrome-latest-1366x768.png", * // The path where the actual screenshot file can be found * path: "/path/to/project/.tmp/actual/desktop_chrome", * }; */ ``` ### Image Output[​](#image-output-1 "Direct link to Image Output") * saveElement * saveScreen * saveFullPageScreen ``` await browser.saveElement(".hero__title-logo", "example-element-tag") ``` * Desktop * Android * iOS ![saveElement Desktop](data:image/png;base64,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) ![saveElement Mobile Android](/assets/images/wdioLogo-EmulatorAndroidGoogleAPIPortraitNativeWebScreenshot14.0-384x640-a9f47229341f7ec2afda1f0da90b89b9.png) ![saveElement Mobile iOS](/assets/images/wdioLogo-Iphone12Portrait16-390x844-927c522afb859701d41f320515164d27.png) ``` await browser.saveScreen("example-page-tag") ``` * Desktop * Android ChromeDriver * Android nativeWebScreenshot * iOS ![saveScreen Desktop](/assets/images/examplePage-chrome-latest-1366x768-d23bc7fc45f4ba7a798f80cae506d8e7.png) ![saveScreen Mobile Android ChromeDriver](/assets/images/screenshot-EmulatorAndroidGoogleAPIPortraitChromeDriver14.0-384x640-bdc0d3b109d51ca65e3c2a781597f3a4.png) ![saveScreen Mobile Android nativeWebScreenshot](/assets/images/screenshot-EmulatorAndroidGoogleAPIPortraitNativeWebScreenshot14.0-384x640-8b3096ca82ac34005afbc1c3e9a828e5.png) TIP iOS `saveScreen` executions are by default not with the device bezel corners. To have this please add the `addIOSBezelCorners:true` option when instantiating the service, see [this](/docs/visual-testing/service-options.md#addiosbezelcorners) ![saveScreen Mobile iOS](/assets/images/screenshot-Iphone12Portrait15-390x844-3a8806e67ca28171228acdfe6b4d99ba.png) ``` await browser.saveFullPageScreen("full-page-tag") ``` * Desktop * Android * iOS ![saveFullPageScreens Desktop](/assets/images/fullPage-chrome-latest-1366x768-9aed8faf23d08427333e9a9e73bf2576.png) ![saveFullPageScreens Mobile Android](/assets/images/fullPage-EmulatorAndroidGoogleAPIPortraitChromeDriver14.0-384x640-90e60804aa58b17076e8fa444a856658.png) ![saveFullPageScreens Mobile iOS](/assets/images/fullPage-Iphone12Portrait16-390x844-4e78bbef8c1bd32ab8de76b89dc9481d.png) ## check(Screen/Element/FullPageScreen)[​](#checkscreenelementfullpagescreen "Direct link to check(Screen/Element/FullPageScreen)") ### Console Output[​](#console-output-1 "Direct link to Console Output") By default, the `check(Screen/Element/FullPageScreen)` methods will only provide a mismatch percentage like `1.23`, but when the plugin has the option `returnAllCompareData: true` the following information is provided after the method has been executed: ``` const checkResult = await browser.checkFullPageScreen({ ... }) console.log(checkResult) /** * { * // The formatted filename, this depends on the options `formatImageName` * fileName: "examplePage-chrome-headless-latest-1366x768.png", * folders: { * // The actual folder and the file name * actual: "/path/to/project/.tmp/actual/desktop_chrome/examplePage-chrome-headless-latest-1366x768.png", * // The baseline folder and the file name * baseline: * "/path/to/project/localBaseline/desktop_chrome/examplePage-chrome-headless-latest-1366x768.png", * // This following folder is optional and only if there is a mismatch * // The folder that holds the diffs and the file name * diff: "/path/to/project/.tmp/diff/desktop_chrome/examplePage-chrome-headless-latest-1366x768.png", * }, * // The mismatch percentage * misMatchPercentage: 2.34, * }; */ ``` ### Image Output[​](#image-output-2 "Direct link to Image Output") info The images below will only show differences as a result of running the check commands. Only the diff in a browser is shown, but the output for Android and iOS is the same. * checkElement * checkScreen * checkFullPageScreen ``` await browser.checkElement("#__docusaurus_skipToContent_fallback > header > div > div.buttons_pzbO > a:nth-child(1)", "example-element-tag") ``` info The button text has been changed from `Get Started` to `Getting Started!` and detected as a change. ![Button Check Result](data:image/png;base64,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) ``` await browser.checkScreen("example-page-tag") ``` info The button text has been changed from `Get Started` to `Getting Started!` and detected as a change. ![Button Check Result](/assets/images/screen-check-677f94ae964e7ce35f97156459538f3d.png) ``` await browser.checkFullPageScreen("full-page-tag") ``` info The button text has been changed from `Get Started` to `Getting Started!` and detected as a change. ![Button Check Result](/assets/images/fullpage-check-ea991871297282e92c7ec38a1491c7f7.png) ## Block-Outs[​](#block-outs "Direct link to Block-Outs") Here you will find an example output for block-outs in Android NativeWebScreenshot and iOS where the status+address and toolbar are blocked out. * Android nativeWebScreenshot * iOS ![Blockouts Android](/assets/images/android.blockouts-9b3bb491f9eed2d6538a5404ec54013a.png) ![Blockouts iOS](/assets/images/ios.blockouts-3936274fa0ec9a70e69ae38ce3c4c518.png) --- Source: https://webdriver.io/docs/visual-testing/visual-reporter.md The Visual Reporter is a new feature introduced in the `@wdio/visual-service`, starting from version [v5.2.0](https://github.com/webdriverio/visual-testing/releases/tag/%40wdio%2Fvisual-service%405.2.0). This reporter allows users to visualize the JSON diff reports generated by the Visual Testing service and transform them into a human-readable format. It helps teams better analyze and manage the visual testing results by providing a graphical interface for reviewing the output. To utilize this feature, ensure you have the required configuration to generate the necessary `output.json` file. This document will guide you through setting up, running, and understanding the Visual Reporter. # Prerequisites Before using the Visual Reporter, make sure you have configured the Visual Testing service to generate JSON report files: ``` export const config = { // ... services: [ [ "visual", { createJsonReportFiles: true, // Generates the output.json file }, ], ], }; ``` For more detailed setup instructions, refer to the WebdriverIO [Visual Testing Documentation](/docs/visual-testing.md) or the [`createJsonReportFiles`](/docs/visual-testing/service-options.md#createjsonreportfiles-new) # Installation To install the Visual Reporter, add it as a development dependency to your project using npm: ``` npm install @wdio/visual-reporter --save-dev ``` This will ensure the necessary files are available to generate reports from your visual tests. # Usage ## Building the Visual Report[​](#building-the-visual-report "Direct link to Building the Visual Report") Once you have run your Visual tests and they generated the `output.json` file, you can build the visual report using either the CLI or interactive prompts. ### CLI Usage[​](#cli-usage "Direct link to CLI Usage") You can use the CLI command to generate the report by running: ``` npx wdio-visual-reporter --jsonOutput= --reportFolder= --logLevel=debug ``` #### Required options:[​](#required-options "Direct link to Required options:") * `--jsonOutput`: The relative path to the `output.json` file generated by the Visual Testing service. This path is relative to the directory from which you execute the command. * `--reportFolder`: The relative directory where the generated report will be stored. This path is also relative to the directory from which you execute the command. #### Optional options:[​](#optional-options "Direct link to Optional options:") * `--logLevel`: Set to `debug` to get detailed logging, especially useful for troubleshooting. #### Example[​](#example "Direct link to Example") ``` npx wdio-visual-reporter --jsonOutput=/path/to/output.json --reportFolder=/path/to/report --logLevel=debug ``` This will generate the report in the specified folder and provide feedback in the console. For example: ``` βœ” Build output copied successfully to "/path/to/report". β ‹ Prepare report assets... βœ” Successfully generated the report assets. ``` #### Viewing the Report[​](#viewing-the-report "Direct link to Viewing the Report") warning Opening `path/to/report/index.html` directly in a browser **without serving it from a local server** will **NOT** work. To view the report, you need to use a simple server like [sirv-cli](https://www.npmjs.com/package/sirv-cli). You can start the server with the following command: ``` npx sirv-cli /path/to/report --single ``` This will produce logs similar to the example below. Note that the port number may vary: ``` Your application is ready~! πŸš€ - Local: http://localhost:8080 - Network: Add `--host` to expose ────────────────── LOGS ────────────────── ``` You can now view the report by opening the provided URL in your browser. ### Using Interactive Prompts[​](#using-interactive-prompts "Direct link to Using Interactive Prompts") Alternatively, you can run the following command and answer the prompts to generate the report: ``` npx @wdio/visual-reporter ``` The prompts will guide you through providing the required paths and options. In the end the interactive prompt will also ask if you want to start a server to view the report. If you choose to start the server, the tool will launch a simple server and display a URL in the logs. You can open this URL in your browser to view the report. ![Visual Reporter CLI](/assets/images/cli-screen-recording-087a04598142ef4336b1cf200893bfa8.gif) ![Visual Reporter](/assets/images/visual-reporter-b67348134a20902af8d8b3a97650f603.gif) #### Viewing the Report[​](#viewing-the-report-1 "Direct link to Viewing the Report") warning Opening `path/to/report/index.html` directly in a browser **without serving it from a local server** will **NOT** work. If you opted **not** to start the server via the interactive prompt, you can still view the report by running the following command manually: ``` npx sirv-cli /path/to/report --single ``` This will produce logs similar to the example below. Note that the port number may vary: ``` Your application is ready~! πŸš€ - Local: http://localhost:8080 - Network: Add `--host` to expose ────────────────── LOGS ────────────────── ``` You can now view the report by opening the provided URL in your browser. # Report Demo To see an example of how the report looks, visit our [GitHub Pages demo](https://webdriverio.github.io/visual-testing/). # Understanding the Visual Report The Visual Reporter provides an organized view of your visual test results. For each test run, you will be able to: * Easily navigate between test cases and see aggregated results. * Review metadata such as test names, browsers used, and comparison results. * View diff images showing where visual differences were detected. This visual representation simplifies the analysis of your test results, making it easier to identify and address visual regressions. # CI Integrations We are working on supporting different CI tools like Jenkins, GitHub Actions and so on. If you like to help us then please contact us on [Discord - Visual Testing](https://discord.com/channels/1097401827202445382/1186908940286574642). --- Source: https://webdriver.io/docs/visual-testing/considerations.md # Key Considerations for Optimal Use Before diving into the powerful features of the `@wdio/visual-service`, it's crucial to understand some key considerations that ensure you get the most out of this tool. The following points are designed to guide you through best practices and common pitfalls, helping you achieve accurate and efficient visual testing results. These considerations are not just recommendations, but essential aspects to keep in mind for effectively utilizing the service in real-world scenarios. ## Nature of Comparison[​](#nature-of-comparison "Direct link to Nature of Comparison") * **Perceptual Comparison:** The module performs a perceptual pixel comparison of images using the YIQ color space, which aligns more closely with how humans perceive color differences. Certain aspects can be adjusted via [Comparison Options](/docs/visual-testing/compare-options.md). * **Impact of Browser Updates:** Be aware that updates to browsers, like Chrome, may affect font rendering, potentially necessitating an update to your baseline images. ## Consistency in Platforms[​](#consistency-in-platforms "Direct link to Consistency in Platforms") * **Comparing Identical Platforms:** Ensure screenshots are compared within the same platform. For instance, a screenshot from Chrome on a Mac should not be used to compare against one from Chrome on Ubuntu or Windows. * **Analogy:** To put it simply, compare *'Apples with Apples, not Apples with Androids'*. ## Caution with Mismatch Percentage[​](#caution-with-mismatch-percentage "Direct link to Caution with Mismatch Percentage") * **Risk of Accepting Mismatches:** Exercise caution when accepting a mismatch percentage. This is especially true for large screenshots, where accepting a mismatch might inadvertently overlook significant discrepancies, such as missing buttons or elements. ## Mobile Screen Simulation[​](#mobile-screen-simulation "Direct link to Mobile Screen Simulation") * **Avoid Browser Resizing for Mobile Simulation:** Do not attempt to simulate mobile screen sizes by resizing desktop browsers and treating them as mobile browsers. Desktop browsers, even when resized, do not accurately replicate the rendering of actual mobile browsers. * **Authenticity in Comparison:** This tool aims to compare visuals as they would appear to an end-user. A resized desktop browser does not reflect the true experience on a mobile device. ## Stance on Headless Browsers[​](#stance-on-headless-browsers "Direct link to Stance on Headless Browsers") * **Not Recommended for Headless Browsers:** The use of this module with headless browsers is not advised. The rationale is that end-users do not interact with headless browsers, and therefore issues arising from such use will not be supported. --- Source: https://webdriver.io/docs/visual-testing/integrate-with-smartui.md # SmartUI TestMu AI (Formerly LambdaTest) [SmartUI](https://www.testmuai.com/support/docs/smart-visual-testing/) provides AI-powered visual regression testing for your WebdriverIO tests. It captures screenshots, compares them against baselines, and highlights visual differences with intelligent comparison algorithms. ## Setup[​](#setup "Direct link to Setup") **Create a SmartUI project** [Sign in](https://accounts.lambdatest.com/register) to TestMu AI (Formerly LambdaTest) and navigate to [SmartUI Projects](https://smartui.lambdatest.com/) to create a new project. Select **Web** as the platform and configure your project name, approvers, and tags. **Set up credentials** Get your `LT_USERNAME` and `LT_ACCESS_KEY` from the TestMu AI (Formerly LambdaTest) dashboard and set them as environment variables: ``` export LT_USERNAME="" export LT_ACCESS_KEY="" ``` **Install SmartUI SDK** ``` npm install @lambdatest/wdio-driver ``` **Configure WebdriverIO** Update your `wdio.conf.js`: ``` exports.config = { user: process.env.LT_USERNAME, key: process.env.LT_ACCESS_KEY, capabilities: [{ browserName: 'chrome', browserVersion: 'latest', 'LT:Options': { platform: 'Windows 10', build: 'SmartUI Build', name: 'SmartUI Test', smartUI.project: '', smartUI.build: '', smartUI.baseline: false } }] } ``` ## Usage[​](#usage "Direct link to Usage") Use `browser.execute('smartui.takeScreenshot')` to capture screenshots: ``` describe('WebdriverIO SmartUI Test', () => { it('should capture screenshot for visual testing', async () => { await browser.url('https://webdriver.io'); await browser.execute('smartui.takeScreenshot', { screenshotName: 'Homepage Screenshot' }); await browser.execute('smartui.takeScreenshot', { screenshotName: 'Homepage with Options', ignoreDOM: { id: ['dynamic-element-id'], class: ['ad-banner'] } }); }); }); ``` **Run tests** ``` npx wdio wdio.conf.js ``` View results in the [SmartUI Dashboard](https://smartui.lambdatest.com/). ## Advanced Options[​](#advanced-options "Direct link to Advanced Options") **Ignore elements** ``` await browser.execute('smartui.takeScreenshot', { screenshotName: 'Ignore Dynamic Elements', ignoreDOM: { id: ['element-id'], class: ['dynamic-class'], xpath: ['//div[@class="ad"]'] } }); ``` **Select specific areas** ``` await browser.execute('smartui.takeScreenshot', { screenshotName: 'Compare Specific Area', selectDOM: { id: ['main-content'] } }); ``` ## Resources[​](#resources "Direct link to Resources") | Resource | Description | | --------------------------------------------------------------------------------- | --------------------------------------- | | [Official Documentation](https://www.testmuai.com/support/docs/smart-ui-cypress/) | SmartUI Documentation | | [SmartUI Dashboard](https://smartui.lambdatest.com/) | Access your SmartUI projects and builds | | [Advanced Settings](https://www.testmuai.com/support/docs/test-settings-options/) | Configure comparison sensitivity | | [Build Options](https://www.testmuai.com/support/docs/smart-ui-build-options/) | Advanced build configuration | --- Source: https://webdriver.io/docs/visual-testing/argos.md # Elevate Your Visual Testing with Argos ## Introduction[​](#introduction "Direct link to Introduction") [Argos](https://argos-ci.com/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) is a powerful open-source visual testing platform that seamlessly integrates with WebdriverIO, enhancing your ability to maintain a flawless user interface across updates. By integrating Argos into your WebdriverIO projects, you can easily identify visual changes introduced by pull requests, confirm intentional modifications, and prevent unexpected regressions in your application. ### Why Choose Argos over Standard Visual Testing?[​](#why-choose-argos-over-standard-visual-testing "Direct link to Why Choose Argos over Standard Visual Testing?") WebdriverIO's built-in visual testing is a great starting point, but Argos takes it to the next level by offering: * **Enhanced Collaboration**: With features like integrated review workflows and notifications on platforms like GitHub and Slack, Argos makes collaboration among developers, designers, and QA teams seamless and efficient. * **Scalability**: Whether you’re working on a small project or a large-scale application, Argos scales effortlessly, handling a wide range of visual tests across different environments. * **Simplified Review Process**: Argos’s intuitive interface groups visual changes, making it easy to review and approve differences, reducing noise and focusing your attention on critical changes. * **Comprehensive Reporting**: Gain deep insights with detailed reports that are easy to understand and share with your team, ensuring everyone is on the same page. ## How Does Argos Enhance Your Workflow?[​](#how-does-argos-enhance-your-workflow "Direct link to How Does Argos Enhance Your Workflow?") Argos integrates directly into your WebdriverIO testing process, enhancing your visual testing capabilities without adding complexity. Every time you run your WebdriverIO tests, Argos automatically captures and compares screenshots against your baseline, highlighting only the relevant visual changes. With Argos, you get more than just a visual diff tool: * **Intelligent Grouping**: Automatically groups related visual changes to help you quickly identify and address issues. * **Continuous Monitoring**: Argos keeps an eye on your UI with every commit, so you can catch and fix visual bugs before they become a problem. * **Customizable Thresholds**: Fine-tune the sensitivity of your visual tests to match the needs of your project, ensuring you only get alerted to the changes that matter. ## Quick Start Guide[​](#quick-start-guide "Direct link to Quick Start Guide") Integrating Argos with your WebdriverIO project is straightforward and quick. Start taking advantage of advanced visual testing today by following [the official Argos guide for WebdriverIO](https://argos-ci.com/docs/quickstart/webdriverio?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). ### In Just a Few Minutes, You Can:[​](#in-just-a-few-minutes-you-can "Direct link to In Just a Few Minutes, You Can:") * **Automate Visual Screenshots**: Capture detailed screenshots during your test runs without manual intervention. * **Identify and Review Changes**: Compare new screenshots against your baselines, quickly identifying any visual discrepancies. * **Streamline Approvals**: Use Argos’s intuitive review system to approve or reject changes, simplifying team collaboration and ensuring your UI stays consistent. Don’t just detect visual regressionsβ€”prevent them. [Start using Argos with WebdriverIO](https://argos-ci.com/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) and safeguard your UI today! --- Source: https://webdriver.io/docs/visual-testing/faq.md # FAQ ### Do I need to use a `save(Screen/Element/FullPageScreen)` methods when I want to run `check(Screen/Element/FullPageScreen)`?[​](#do-i-need-to-use-a-savescreenelementfullpagescreen-methods-when-i-want-to-run-checkscreenelementfullpagescreen "Direct link to do-i-need-to-use-a-savescreenelementfullpagescreen-methods-when-i-want-to-run-checkscreenelementfullpagescreen") No, you don't need to do this. The `check(Screen/Element/FullPageScreen)` will do this automatically for you. ### My visual tests fail with a difference, how can I update my baseline?[​](#my-visual-tests-fail-with-a-difference-how-can-i-update-my-baseline "Direct link to My visual tests fail with a difference, how can I update my baseline?") You can update the baseline images through the command line by adding the argument `--update-visual-baseline`. This will * automatically copy the actual take screenshot and put it in the baseline folder * if there are differences it will let the test pass because the baseline has been updated **Usage:** ``` npm run test.local.desktop --update-visual-baseline ``` When running logs info/debug mode you will see the following logs added ``` [0-0] .............. [0-0] ##################################################################################### [0-0] INFO: [0-0] Updated the actual image to [0-0] /Users/wswebcreation/Git/wdio/visual-testing/localBaseline/chromel/demo-chrome-1366x768.png [0-0] ##################################################################################### [0-0] .......... ``` ### Width and height cannot be negative[​](#width-and-height-cannot-be-negative "Direct link to Width and height cannot be negative") It could be that the error `Width and height cannot be negative` is thrown. 9 out of 10 times this is related to creating an image of an element that is not in the view. Please be sure you always make sure the element in is in the view before you try to make an image of the element. ### Installation of Canvas on Windows failed with Node-Gyp logs[​](#installation-of-canvas-on-windows-failed-with-node-gyp-logs "Direct link to Installation of Canvas on Windows failed with Node-Gyp logs") If you encounter issues with Canvas installation on Windows due to Node-Gyp errors, please note that this applies only to Version 4 and lower. To avoid these issues, consider updating to Version 5 or higher, which does not have these dependencies. Version 5 to 9 used [Jimp](https://github.com/jimp-dev/jimp) for image processing; Version 10 and up use [fast-png](https://github.com/image-js/fast-png) and [Pixelmatch](https://github.com/mapbox/pixelmatch) with no native dependencies. If you still need to resolve the issues with Version 4, please check: * the Node Canvas section in the [Getting Started](/docs/visual-testing.md#system-requirements) guide * [this post](https://spin.atomicobject.com/2019/03/27/node-gyp-windows/) for Fixing Node-Gyp Issues on Windows. (Thanks to [IgorSasovets](https://github.com/IgorSasovets)) ### I upgraded to v11, why did a mismatch percentage change?[​](#i-upgraded-to-v11-why-did-a-mismatch-percentage-change "Direct link to I upgraded to v11, why did a mismatch percentage change?") In v11 the comparison engine is pixelmatch 8, which measures color differences in the OKLab color space with the HyAB distance instead of YIQ. The threshold scale (`0` to `1`) and the `ignore*` presets did not change, but the number of different pixels can change a little for the same images (about βˆ’3 % to +3 % on real screenshots). If a check depends on an exact mismatch percentage or a tight tolerance, check it again, and update the baseline with `--update-visual-baseline` only when the new result is correct. Some fixes can also change a baseline once, for example iOS element screenshots of elements larger than the viewport, which no longer have a black area. See the [v11 migration guide](https://github.com/webdriverio/visual-testing/blob/main/docs/v11-migration.md). ### I upgraded to v10, why are my visual tests failing?[​](#i-upgraded-to-v10-why-are-my-visual-tests-failing "Direct link to I upgraded to v10, why are my visual tests failing?") The comparison engine changed from ResembleJS to [Pixelmatch](https://github.com/mapbox/pixelmatch) in v10. Pixelmatch uses a perceptual (YIQ) color model instead of raw RGB, so mismatch percentages differ from v9. Your tests haven't broken; the baselines just need to be regenerated once. Run your tests with `--update-visual-baseline` to accept the new values, or delete your baseline folder and let `autoSaveBaseline` recreate it. --- Source: https://webdriver.io/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 }, ], ], // ... }; ``` # Default Options ## Screenshot capture[​](#screenshot-capture "Direct link to Screenshot capture") *** ### `hideScrollBars`[​](#hidescrollbars "Direct link to hidescrollbars") * Type `boolean` * Default `true` * Required `No` * Contexts `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. ### `disableBlinkingCursor`[​](#disableblinkingcursor "Direct link to disableblinkingcursor") * Type `boolean` * Default `false` * Required `No` * Contexts `Web, Hybrid App (Webview)` En/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 ### `disableCSSAnimation`[​](#disablecssanimation "Direct link to disablecssanimation") * Type `boolean` * Default `false` * Required `No` * Contexts `Web, Hybrid App (Webview)` En/Disable all CSS animations in the application. If set to `true` all animations will be disabled before taking a screenshot and reset when done ### `enableLayoutTesting`[​](#enablelayouttesting "Direct link to enablelayouttesting") * Type `boolean` * Default `false` * Required `No` * Contexts `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](/docs/visual-testing/test-output.md#enablelayouttesting) 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. ### `ignoreRegionPadding`[​](#ignoreregionpadding "Direct link to ignoreregionpadding") * Type `number` * Default `1` * Required `No` * Contexts `Web, Hybrid App (Webview)` Padding in device pixels added to each side of ignore regions, making each region 2Γ— this value wider and taller. This helps avoid 1 px boundary differences that can appear on high-DPR displays or with the BiDi screenshot protocol. Set to `0` to disable. ### `waitForFontsLoaded`[​](#waitforfontsloaded "Direct link to waitforfontsloaded") * Type `boolean` * Default `true` * Required `No` * Contexts `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. ## Full-page screenshots[​](#full-page-screenshots "Direct link to Full-page screenshots") *** ### `userBasedFullPageScreenshot`[​](#userbasedfullpagescreenshot "Direct link to userbasedfullpagescreenshot") * Type `boolean` * Default `false` * Required `No` * Contexts `Web, Hybrid App (Webview) **Introduced in visual-service@7.0.0` By 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. ### `fullPageScrollTimeout`[​](#fullpagescrolltimeout "Direct link to fullpagescrolltimeout") * Type `number` * Default `1500` * Required `No` * Contexts `Web` The 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`](/docs/visual-testing/service-options.md#userbasedfullpagescreenshot) ## Mobile & device[​](#mobile--device "Direct link to Mobile & device") *** ### `isHybridApp`[​](#ishybridapp "Direct link to ishybridapp") * Type `boolean` * Default `false` * Required `No` * Contexts `Hybrid App (Webview)` Set this to `true` when testing a hybrid app (a native shell with one or more embedded webviews). This adjusts how the module handles status bar and address bar cutouts for webview-based screens, falling back to safe defaults when native device rectangle data is unavailable. ### `addIOSBezelCorners`[​](#addiosbezelcorners "Direct link to addiosbezelcorners") * Type `boolean` * Default `false` * Required `No` * Contexts `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` ### `addressBarShadowPadding`[​](#addressbarshadowpadding "Direct link to addressbarshadowpadding") * Type `number` * Default `6` * Required `No` * Contexts `Web` The padding needs to be added to the address bar on iOS and Android to do a proper cutout of the viewport. ### `toolBarShadowPadding`[​](#toolbarshadowpadding "Direct link to toolbarshadowpadding") * Type `number` * 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)`` * Required `No` * Contexts `Web` The padding which needs to be added to the toolbar bar on iOS and Android to do a proper cutout of the viewport. ## File & folder management[​](#file--folder-management "Direct link to File & folder management") *** ### `baselineFolder`[​](#baselinefolder "Direct link to baselinefolder") * Type `string|()=> string` * Default `.path/to/testfile/__snapshots__/` * Required `No` * Contexts `Web, Hybrid App (Webview), Native App` 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'); } } ``` ### `screenshotPath`[​](#screenshotpath "Direct link to screenshotpath") * Type `string | () => string` * Default `.tmp/` * Required `no` * Contexts `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 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'); } } ``` ### `clearRuntimeFolder`[​](#clearruntimefolder "Direct link to clearruntimefolder") * Type `boolean` * Default `false` * Required `No` * Contexts `Web, Hybrid App (Webview), Native App` Delete runtime folder (`actual` & \`diff) on initialization NOTE This will only work when the [`screenshotPath`](#screenshotpath) is set through the plugin options, and **WILL NOT WORK** when you set the folders in the methods ### `savePerInstance`[​](#saveperinstance "Direct link to saveperinstance") * Type `boolean` * Default `false` * Required `no` * Contexts `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`. ### `formatImageName`[​](#formatimagename "Direct link to formatimagename") * Type `string` * Default `{tag}-{browserName}-{width}x{height}-dpr-{dpr}` * Required `No` * Contexts `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 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: * [`baselineFolder`](/docs/visual-testing/service-options.md#baselinefolder) * [`screenshotPath`](/docs/visual-testing/service-options.md#screenshotpath) * [`folderOptions`](/docs/visual-testing/method-options.md#folder-options) per method ## Baseline & save behavior[​](#baseline--save-behavior "Direct link to Baseline & save behavior") *** ### `autoSaveBaseline`[​](#autosavebaseline "Direct link to autosavebaseline") * Type `boolean` * Default `true` * Required `No` * Contexts `Web, Hybrid App (Webview), Native App` If no baseline image is found during the comparison the image is automatically copied to the baseline folder. ### `autoElementScroll`[​](#autoelementscroll "Direct link to autoelementscroll") * Type `boolean` * Default `true` * Required `No` * Contexts `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. ### `alwaysSaveActualImage`[​](#alwayssaveactualimage "Direct link to alwayssaveactualimage") * Type `boolean` * Default `true` * Required `No` * Contexts `All` When setting this option to `false` it will: * not save the actual image when there is **no** difference * not store the jsonreport file when `createJsonReportFiles` is set to `true`. It will also show a warning in the logs that `createJsonReportFiles` is disabled This 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. ## Reporting[​](#reporting "Direct link to Reporting") *** ### `createJsonReportFiles` **(NEW)**[​](#createjsonreportfiles-new "Direct link to createjsonreportfiles-new") * Type `boolean` * Default `false` * Required `No` 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 ### `diffPixelBoundingBoxProximity`[​](#diffpixelboundingboxproximity "Direct link to diffpixelboundingboxproximity") * Type `number` * Default `5` * Required `No` * Contexts `Web, Hybrid App (Webview), Native App` The pixel proximity used to group diff pixels together in the JSON report generated by [`createJsonReportFiles`](#createjsonreportfiles). Higher values group more pixels into fewer bounding boxes; lower values produce more accurate but more numerous boxes. ## General[​](#general "Direct link to General") *** ### `logLevel`[​](#loglevel "Direct link to loglevel") * Type `string` * Default `info` * Required `No` * Contexts `Web, Hybrid App (Webview), Native App` Adds extra logs, options are `debug | info | warn | silent` Errors are always logged to the console. ## Tabbable Options[​](#tabbable-options "Direct link to 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](https://github.com/vivrichards600) his blog post about ["AUTOMATING PAGE TABABILITY (IS THAT A WORD?) WITH VISUAL TESTING"](https://vivrichards.co.uk/accessibility/automating-page-tab-flows-using-visual-testing-and-javascript).
The way tabbable elements are selected is based on the module [tabbable](https://github.com/davidtheclark/tabbable). If there are any issues regarding the tabbing please check the [README.md](https://github.com/davidtheclark/tabbable/blob/master/README.md) and especially the [More details section](https://github.com/davidtheclark/tabbable/blob/master/README.md#more-details). ### `tabbableOptions`[​](#tabbableoptions "Direct link to tabbableoptions") * Type `object` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `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`[​](#tabbableoptionscircle "Direct link to tabbableoptionscircle") * Type `object` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The options to change the circle. ##### `tabbableOptions.circle.backgroundColor`[​](#tabbableoptionscirclebackgroundcolor "Direct link to tabbableoptionscirclebackgroundcolor") * Type `string` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The background color of the circle. ##### `tabbableOptions.circle.borderColor`[​](#tabbableoptionscirclebordercolor "Direct link to tabbableoptionscirclebordercolor") * Type `string` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The border color of the circle. ##### `tabbableOptions.circle.borderWidth`[​](#tabbableoptionscircleborderwidth "Direct link to tabbableoptionscircleborderwidth") * Type `number` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The border width of the circle. ##### `tabbableOptions.circle.fontColor`[​](#tabbableoptionscirclefontcolor "Direct link to tabbableoptionscirclefontcolor") * Type `string` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The color of the font of the text in the circle. This will only be shown if [`showNumber`](/docs/visual-testing.md#tabbableoptionscircleshownumber) is set to `true`. ##### `tabbableOptions.circle.fontFamily`[​](#tabbableoptionscirclefontfamily "Direct link to tabbableoptionscirclefontfamily") * Type `string` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The family of the font of the text in the circle. This will only be shown if [`showNumber`](/docs/visual-testing.md#tabbableoptionscircleshownumber) is set to `true`. Make sure to set fonts that are supported by the browsers. ##### `tabbableOptions.circle.fontSize`[​](#tabbableoptionscirclefontsize "Direct link to tabbableoptionscirclefontsize") * Type `number` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The size of the font of the text in the circle. This will only be shown if [`showNumber`](/docs/visual-testing.md#tabbableoptionscircleshownumber) is set to `true`. ##### `tabbableOptions.circle.size`[​](#tabbableoptionscirclesize "Direct link to tabbableoptionscirclesize") * Type `number` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The size of the circle. ##### `tabbableOptions.circle.showNumber`[​](#tabbableoptionscircleshownumber "Direct link to tabbableoptionscircleshownumber") * Type `showNumber` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` Show the tab sequence number in the circle. #### `tabbableOptions.line`[​](#tabbableoptionsline "Direct link to tabbableoptionsline") * Type `object` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The options to change the line. ##### `tabbableOptions.line.color`[​](#tabbableoptionslinecolor "Direct link to tabbableoptionslinecolor") * Type `string` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The color of the line. ##### `tabbableOptions.line.width`[​](#tabbableoptionslinewidth "Direct link to tabbableoptionslinewidth") * Type `number` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/%40wdio/image-comparison-core%402.0.0/packages/image-comparison-core/src/helpers/options.ts#L27-L86) for all default values` * Required `No` * Contexts `Web` The width of the line. ## Compare options[​](#compare-options "Direct link to Compare options") ### `compareOptions`[​](#compareoptions "Direct link to compareoptions") * Type `object` * Default `See [here](https://github.com/webdriverio/visual-testing/blob/6a988808c9adc58f58c5a66cd74296ae5c1ad6dc/packages/webdriver-image-comparison/src/helpers/options.ts#L46-L60) for all default values` * Required `No` * Contexts `Web, Hybrid App (Webview), Native App (See [Method Compare options](./method-options#compare-check-options) for more information)` The compare options can also be set as service options, they are described in the [Method Compare options](/docs/visual-testing/method-options.md#compare-check-options) --- Source: https://webdriver.io/docs/visual-testing/method-options.md Methods options are the options that can be set per [method](/docs/visual-testing/methods.md). If the option has the same key as an option that has been set during the instantiation of the plugin, this method option will override the plugin option value. NOTE * All options from the [Save Options](#save-options) can be used for the [Compare](#compare-check-options) methods * All compare options can be used during service instantiation **or** for every single check method. If a method option has the same key as an option that has been set during the instantiation of the service, then the method compare option will override the service compare option value. * All options can be used for the below application contexts unless mentioned otherwise: * Web * Hybrid App * Native App * The below samples are with the `save*`-methods, but can also be used with the `check*`-methods # Save Options ## Display & rendering[​](#display--rendering "Direct link to Display & rendering") *** ### `hideScrollBars`[​](#hidescrollbars "Direct link to hidescrollbars") * Type `boolean` * Default `true` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) Hide scrollbar(s) in the application. If set to true all scrollbar(s) will be disabled before taking a screenshot. This is set to default `true` to prevent extra issues. ``` await browser.saveScreen( 'sample-tag', { hideScrollBars: false } ) ``` ### `disableBlinkingCursor`[​](#disableblinkingcursor "Direct link to disableblinkingcursor") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) En/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. ``` await browser.saveScreen( 'sample-tag', { disableBlinkingCursor: true } ) ``` ### `disableCSSAnimation`[​](#disablecssanimation "Direct link to disablecssanimation") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) En/Disable all CSS animations in the application. If set to `true` all animations will be disabled before taking a screenshot and reset when done ``` await browser.saveScreen( 'sample-tag', { disableCSSAnimation: true } ) ``` ### `enableLayoutTesting`[​](#enablelayouttesting "Direct link to enablelayouttesting") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) 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](/docs/visual-testing/test-output.md#enablelayouttesting). 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. ``` await browser.saveScreen( 'sample-tag', { enableLayoutTesting: true } ) ``` ### `enableLegacyScreenshotMethod`[​](#enablelegacyscreenshotmethod "Direct link to enablelegacyscreenshotmethod") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) Use this option to switch back to the "older" screenshot method based on the W3C-WebDriver protocol. This can be helpful if your tests rely on existing baseline images or if you're running in environments that don't fully support the newer BiDi-based screenshots. Note that enabling this may produce screenshots with slightly different resolution or quality. ``` await browser.saveScreen( 'sample-tag', { enableLegacyScreenshotMethod: true } ) ``` ### `ignoreRegionPadding`[​](#ignoreregionpadding "Direct link to ignoreregionpadding") * Type `number` * Default `1` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) Padding in device pixels added to each side of ignore regions, making each region 2Γ— this value wider and taller. This helps avoid 1 px boundary differences that can appear on high-DPR displays or with the BiDi screenshot protocol. Set to `0` to disable. ``` await browser.saveScreen( 'sample-tag', { ignoreRegionPadding: 0 } ) ``` ### `waitForFontsLoaded`[​](#waitforfontsloaded "Direct link to waitforfontsloaded") * Type `boolean` * Default `true` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** 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. ``` await browser.saveScreen( 'sample-tag', { waitForFontsLoaded: true } ) ``` ## Element visibility[​](#element-visibility "Direct link to Element visibility") *** ### `hideElements`[​](#hideelements "Direct link to hideelements") * Type `array` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) This method can hide 1 or multiple elements by adding the property `visibility: hidden` to them by providing an array of elements. ``` await browser.saveScreen( 'sample-tag', { hideElements: [ await $('#element-1'), await $('#element-2'), ] } ) ``` ### `removeElements`[​](#removeelements "Direct link to removeelements") * Type `array` * Required `No` - **Used with:** All [methods](/docs/visual-testing/methods.md) - **Supported Application Contexts:** Web, Hybrid App (Webview) This method can *remove* 1 or multiple elements by adding the property `display: none` to them by providing an array of elements. ``` await browser.saveScreen( 'sample-tag', { removeElements: [ await $('#element-1'), await $('#element-2'), ] } ) ``` ## Element-specific[​](#element-specific "Direct link to Element-specific") *** ### `resizeDimensions`[​](#resizedimensions "Direct link to resizedimensions") * Type `object` * Default `{ top: 0, right: 0, bottom: 0, left: 0}` * Required `No` - **Used with:** Only for [`saveElement`](/docs/visual-testing/methods.md#saveelement) or [`checkElement`](/docs/visual-testing/methods.md#checkelement) - **Supported Application Contexts:** Web, Hybrid App (Webview), Native App An object that needs to hold a `top`, `right`, `bottom` and `left` amount of pixels that need to make the element cutout bigger. ``` await browser.saveElement( 'sample-tag', { resizeDimensions: { top: 50, left: 100, right: 10, bottom: 90, }, } ) ``` ### `biDiOrigin`[​](#bidiorigin "Direct link to bidiorigin") * Type `'document' | 'viewport'` * Default `'document'` * Required `No` - **Used with:** Only for [`saveElement`](/docs/visual-testing/methods.md#saveelement) or [`checkElement`](/docs/visual-testing/methods.md#checkelement) - **Supported Application Contexts:** Web, Hybrid App (Webview) BiDi-only option that controls which coordinate origin is used when capturing element screenshots via the WebDriver BiDi protocol. * `'document'` *(default)*: renders the document layout. Works for any element position but does **not** capture composited layers (e.g. scrollbars, fixed/sticky overlays, `will-change` elements). * `'viewport'`: captures the composited frame as painted, including scrollbars and overlays. Requires the element to be **fully visible** in the viewport, throws a descriptive error when the element is outside or larger than the viewport. ``` await browser.saveElement( await $('#my-element'), 'sample-tag', { biDiOrigin: 'viewport' } ) ``` ## Full-page specific[​](#full-page-specific "Direct link to Full-page specific") *** ### `userBasedFullPageScreenshot`[​](#userbasedfullpagescreenshot "Direct link to userbasedfullpagescreenshot") * Type `boolean` * Default `false` * Required `No` - **Used with:** Only for [`saveFullPageScreen`](/docs/visual-testing/methods.md#savefullpagescreen), [`saveTabbablePage`](/docs/visual-testing/methods.md#savetabbablepage), [`checkFullPageScreen`](/docs/visual-testing/methods.md#checkfullpagescreen) or [`checkTabbablePage`](/docs/visual-testing/methods.md#checktabbablepage) - **Supported Application Contexts:** Web, Hybrid App (Webview) When set to `true`, this option enables the **scroll-and-stitch strategy** to capture full-page screenshots. Instead of using the browser's native screenshot capabilities, it scrolls through the page manually and stitches multiple screenshots together. This method is especially useful for pages with **lazy-loaded content** or complex layouts that require scrolling to fully render. ``` await browser.saveScreen( 'sample-tag', { userBasedFullPageScreenshot: true } ) ``` ### `fullPageScrollTimeout`[​](#fullpagescrolltimeout "Direct link to fullpagescrolltimeout") * Type `number` * Default `1500` * Required `No` - **Used with:** Only for [`saveFullPageScreen`](/docs/visual-testing/methods.md#savefullpagescreen) or [`saveTabbablePage`](/docs/visual-testing/methods.md#savetabbablepage) - **Supported Application Contexts:** Web, Hybrid App (Webview) The timeout in milliseconds to wait after a scroll. This might help identify pages with lazy loading. > **NOTE:** This only works when `userBasedFullPageScreenshot` is set to `true` ``` await browser.saveFullPageScreen( 'sample-tag', { fullPageScrollTimeout: 3 * 1000 } ) ``` ### `hideAfterFirstScroll`[​](#hideafterfirstscroll "Direct link to hideafterfirstscroll") * Type `array` * Required `No` - **Used with:** Only for [`saveFullPageScreen`](/docs/visual-testing/methods.md#savefullpagescreen) or [`saveTabbablePage`](/docs/visual-testing/methods.md#savetabbablepage) - **Supported Application Contexts:** Web, Hybrid App (Webview) This method will hide one or multiple elements by adding the property `visibility: hidden` to them by providing an array of elements. This will be handy when a page for example holds sticky elements that will scroll with the page if the page is scrolled but will give an annoying effect when a full-page screenshot is made > **NOTE:** This only works when `userBasedFullPageScreenshot` is set to `true` ``` await browser.saveFullPageScreen( 'sample-tag', { hideAfterFirstScroll: [ await $('#element-1'), await $('#element-2'), ] } ) ``` # Compare (Check) Options Compare options are options that influence the way the comparison is being executed. ## Visual sensitivity[​](#visual-sensitivity "Direct link to Visual sensitivity") *** Version history for `ignore*` options These presets changed behavior once, as a breaking change, when the comparison engine switched from ResembleJS (v9 and below) to Pixelmatch (v10 and up). See the [version history table](/docs/visual-testing/compare-options.md#visual-sensitivity) on the Compare Options page for details. Anything since v10.0.0 is called out with a "Since" note on the relevant option below. **Last-wins ordering:** when more than one `ignore*` flag is enabled at the same time, only one preset is applied, following this order (later wins): `ignoreAlpha` β†’ `ignoreAntialiasing` β†’ `ignoreColors` β†’ `ignoreLess` β†’ `ignoreNothing`. As of `v10.1.0` a warning is logged naming which preset won. ### `ignoreColors`[​](#ignorecolors "Direct link to ignorecolors") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All - **Since:** `v10.1.0`: brightness-only comparison using resemble luma weights (`0.3/0.59/0.11`). Compares brightness only (resemble luma weights `0.3/0.59/0.11`), ignoring hue/color differences. Use this when color itself is expected to vary but you still want to catch layout or brightness changes. ``` await browser.checkScreen( 'sample-tag', { ignoreColors: true } ) ``` ### `ignoreAlpha`[​](#ignorealpha "Direct link to ignorealpha") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All - **Since:** `v10.1.0`: applies its own threshold/AA rule independently of other `ignore*` flags. Compare images and discard alpha-channel differences. Use this when transparency/opacity rendering is flaky but the pixel colors underneath matter. ``` await browser.checkScreen( 'sample-tag', { ignoreAlpha: true } ) ``` ### `ignoreAntialiasing`[​](#ignoreantialiasing "Direct link to ignoreantialiasing") * Type `boolean` * Default `true` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All - **Since:** `v10`: default changed to `true` (was `false` in v9 and below). Forgives anti-aliased pixels during comparison. Set to `false` for strict comparison where anti-aliased pixels should count as mismatches. This solves the most common source of visual-test flakiness: text/shape edges rendering with slightly different anti-aliasing across machines even though nothing changed. ``` await browser.checkScreen( 'sample-tag', { ignoreAntialiasing: true } ) ``` ### `ignoreLess`[​](#ignoreless "Direct link to ignoreless") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All - **Since:** `v10.1.0`: applies its own threshold/AA rule independently of other `ignore*` flags. Compare images using a relaxed RGB tolerance (\~16/255 per channel in YIQ space). Anti-aliasing is not forgiven. Use this for a little breathing room on rendering noise (compression artifacts, color rounding) without forgiving anti-aliasing. ``` await browser.checkScreen( 'sample-tag', { ignoreLess: true } ) ``` ### `ignoreNothing`[​](#ignorenothing "Direct link to ignorenothing") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All - **Since:** `v10.1.0`: applies its own threshold/AA rule independently of other `ignore*` flags. Use zero tolerance: any pixel difference counts as a mismatch, including anti-aliasing. Use this when you need pixel-perfect proof nothing changed at all. ``` await browser.checkScreen( 'sample-tag', { ignoreNothing: true } ) ``` ### `pixelmatch`[​](#pixelmatch "Direct link to pixelmatch") * Type `object` * Default `undefined` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All - **Added in:** `v10.1.0` Overrides the compare mode for a single `check*` call with direct [pixelmatch](https://github.com/mapbox/pixelmatch) settings (`threshold`, `includeAA`, `diffColor`, `aaColor`, `diffColorAlt`, `alpha`, `diffMask`, `checkerboard`), instead of an `ignore*` preset. Use this when the presets are too coarse for one specific test, e.g. it needs its own threshold value, or a diff color that actually stands out in your report. See [Direct pixelmatch control](/docs/visual-testing/compare-options.md#direct-pixelmatch-control) for the full field reference and what each field solves. Cannot be combined with `ignore*` options in the same call's options object: that throws `CompareOptionsConflictError`. It can, however, override a service config that uses `ignore*` presets (or vice versa); a warning is logged when a method call switches the compare mode this way. ``` await browser.checkScreen( 'sample-tag', { pixelmatch: { threshold: 0.05 } } ) ``` ### `scaleImagesToSameSize`[​](#scaleimagestosamesize "Direct link to scaleimagestosamesize") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All Scales 2 images to the same size before execution of comparison. Highly recommended to enable `ignoreAntialiasing` and `ignoreAlpha` ``` await browser.checkScreen( 'sample-tag', { scaleImagesToSameSize: true } ) ``` ## Mobile block-outs[​](#mobile-block-outs "Direct link to Mobile block-outs") *** ### `blockOutStatusBar`[​](#blockoutstatusbar "Direct link to blockoutstatusbar") * Type `boolean` * Default `true` * Required `No` - **Used with:** *This is **Mobile only*** - **Supported Application Contexts:** Hybrid (native part) and Native Apps Automatically block out the status and address bar during comparisons. This prevents failures on time, wifi or battery status. ``` await browser.checkScreen( 'sample-tag', { blockOutStatusBar: true } ) ``` ### `blockOutToolBar`[​](#blockouttoolbar "Direct link to blockouttoolbar") * Type `boolean` * Default `true` * Required `No` - **Used with:** *This is **Mobile only*** - **Supported Application Contexts:** Hybrid (native part) and Native Apps Automatically block out the toolbar. ``` await browser.checkScreen( 'sample-tag', { blockOutToolBar: true } ) ``` ### `blockOutSideBar`[​](#blockoutsidebar "Direct link to blockoutsidebar") * Type `boolean` * Default `true` * Required `No` - **Used with:** *Can only be used for `checkScreen()`. This is **iPad only*** - **Supported Application Contexts:** All Automatically block out the sidebar for iPads in landscape mode during comparisons. This prevents failures on the tab/private/bookmark native component. ``` await browser.checkScreen( 'sample-tag', { blockOutSideBar: true } ) ``` ## Region handling[​](#region-handling "Direct link to Region handling") *** ### `blockOut`[​](#blockout "Direct link to blockout") * Type `array` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All An array of rectangular areas to block out before comparison. Each entry must be an object with `x`, `y`, `width`, and `height` values (in pixels). The blocked-out areas are painted over before the diff is calculated, preventing those regions from contributing to the mismatch percentage. ``` await browser.checkScreen( 'sample-tag', { blockOut: [ { x: 0, y: 0, width: 100, height: 50 }, { x: 300, y: 200, width: 80, height: 80 }, ] } ) ``` ### `ignore`[​](#ignore "Direct link to ignore") * Type `array` * Required `No` - **Used with:** Only with the `checkScreen`-method, **NOT** with the `checkElement`-method - **Supported Application Contexts:** Native App This method will automatically blockout elements or an area on a screen based on an array of elements or an object of `x|y|width|height`. ``` await browser.checkScreen( 'sample-tag', { ignore: [ $('~element-1'), await $('~element-2'), { x: 150, y: 250, width: 100, height: 100, } ] } ) ``` ## Results & reporting[​](#results--reporting "Direct link to Results & reporting") *** ### `rawMisMatchPercentage`[​](#rawmismatchpercentage "Direct link to rawmismatchpercentage") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All If true the return percentage will be like `0.12345678`, default is `0.12` ``` await browser.checkScreen( 'sample-tag', { rawMisMatchPercentage: true } ) ``` ### `returnAllCompareData`[​](#returnallcomparedata "Direct link to returnallcomparedata") * Type `boolean` * Default `false` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All This will return all compare data, not only the mismatch percentage, see also [Console Output](/docs/visual-testing/test-output.md#console-output-1) ``` await browser.checkScreen( 'sample-tag', { returnAllCompareData: true } ) ``` ### `saveAboveTolerance`[​](#saveabovetolerance "Direct link to saveabovetolerance") * Type `number` * Default `0` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All Allowable value of `misMatchPercentage` that prevents saving images with differences ``` await browser.checkScreen( 'sample-tag', { saveAboveTolerance: 0.25 } ) ``` ### `diffPixelBoundingBoxProximity`[​](#diffpixelboundingboxproximity "Direct link to diffpixelboundingboxproximity") * Type `number` * Default `5` * Required `No` - **Used with:** All [Check methods](/docs/visual-testing/methods.md#check-methods) - **Supported Application Contexts:** All The pixel proximity used to group diff pixels together in JSON reports. Higher values group more pixels into fewer bounding boxes; lower values produce more accurate but more numerous boxes. Only relevant when [`createJsonReportFiles`](/docs/visual-testing/service-options.md#createjsonreportfiles) is enabled. ``` await browser.checkScreen( 'sample-tag', { diffPixelBoundingBoxProximity: 10 } ) ``` # Folder options *** The baseline folder and screenshot folders(actual, diff) are options that can be set during the instantiation of the plugin or method. To set the folder options on a particular method, pass in folder options to the methods option object. This can be used for: * Web * Hybrid App * Native App ``` import path from 'node:path' const methodOptions = { actualFolder: path.join(process.cwd(), 'customActual'), baselineFolder: path.join(process.cwd(), 'customBaseline'), diffFolder: path.join(process.cwd(), 'customDiff'), } // You can use this for all methods await expect( await browser.checkFullPageScreen("checkFullPage", methodOptions) ).toEqual(0) ``` ### `actualFolder`[​](#actualfolder "Direct link to actualfolder") * Type `string` * Required `No` * Contexts `All` Folder for the snapshot that has been captured in the test. ### `baselineFolder`[​](#baselinefolder "Direct link to baselinefolder") * Type `string` * Required `No` * Contexts `All` Folder for the baseline image that is being used to compare against. ### `diffFolder`[​](#difffolder "Direct link to difffolder") * Type `string` * Required `No` * Contexts `All` Folder for the image difference rendered during comparison. --- Source: https://webdriver.io/docs/visual-testing/compare-options.md # Compare Options Compare options are options that influence the way the comparison is being executed. NOTE All compare options can be used during service instantiation or for each single `checkElement`,`checkScreen` and `checkFullPageScreen`. If a method option has the same key as an option that has been set during the instantiation of the service, then the method compare option will override the service compare option value. ## Visual sensitivity[​](#visual-sensitivity "Direct link to Visual sensitivity") *** Version history for `ignore*` options The `ignore*` presets changed behavior once, as a breaking change, when the comparison engine switched from ResembleJS to Pixelmatch: | Version | Engine | Notes | | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | v9 and below | ResembleJS | Original `ignore*` semantics (RGB/brightness-based, resemble's own preset ordering). | | v10 and above | Pixelmatch | `ignore*` presets map to pixelmatch threshold/AA settings. Current defaults and behavior are documented per option below; new features/fixes on top of this are called out with a "Since" note on the relevant option. | | v11 and above | Pixelmatch 8 | Colors are compared in the OKLab color space with the HyAB distance (before: YIQ). The threshold scale and the `ignore*` presets did not change, but mismatch percentages can differ a little from v10. | **Last-wins ordering:** when more than one `ignore*` flag is enabled at the same time, only one preset is actually applied, following this order (later wins): `ignoreAlpha` β†’ `ignoreAntialiasing` β†’ `ignoreColors` β†’ `ignoreLess` β†’ `ignoreNothing`. A warning is logged naming which preset won. ### `ignoreColors`[​](#ignorecolors "Direct link to ignorecolors") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* - **Since:** `v10.1.0`: brightness-only comparison using resemble luma weights (`0.3/0.59/0.11`). Compares brightness only, ignoring hue/color differences. Preset: strict threshold (\~16/255), anti-aliasing not forgiven. **Use this when** color itself is expected to vary (e.g. themeable UI, images that recolor per environment) but you still want to catch layout or brightness changes. ### `ignoreAlpha`[​](#ignorealpha "Direct link to ignorealpha") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* - **Since:** `v10.1.0`: applies its own threshold/AA rule independently of other `ignore*` flags. Compare images and discard alpha-channel differences. Preset: strict threshold (\~16/255), anti-aliasing not forgiven. **Use this when** transparency/opacity rendering is flaky (e.g. overlays, semi-transparent elements) but the actual pixel colors underneath matter. ### `ignoreAntialiasing`[​](#ignoreantialiasing "Direct link to ignoreantialiasing") * Type `boolean` * Default `true` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* - **Since:** `v10`: default changed to `true` (was `false` in v9 and below). Forgives anti-aliased pixels during comparison (relaxed threshold \~32/255). This is the only preset that forgives anti-aliasing, and is enabled by default so sub-pixel rendering noise doesn't fail comparisons out of the box. Set to `false` for strict comparison where anti-aliased pixels should count as mismatches. **Use this to** solve the most common source of visual-test flakiness: text and shape edges that render with slightly different anti-aliasing between machines/browsers even though nothing actually changed. ### `ignoreLess`[​](#ignoreless "Direct link to ignoreless") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* - **Since:** `v10.1.0`: applies its own threshold/AA rule independently of other `ignore*` flags. Compare images using a relaxed RGB tolerance (\~16/255 per channel in YIQ space). Preset: strict threshold, anti-aliasing not forgiven. **Use this when** you want a little breathing room for minor rendering noise (JPEG-style compression artifacts, slight color rounding) without forgiving anti-aliasing. ### `ignoreNothing`[​](#ignorenothing "Direct link to ignorenothing") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* - **Since:** `v10.1.0`: applies its own threshold/AA rule independently of other `ignore*` flags. Use zero tolerance: any pixel difference counts as a mismatch, including anti-aliasing. **Use this when** you need pixel-perfect proof nothing changed at all, e.g. verifying a fix didn't introduce any regression, however small. ### `scaleImagesToSameSize`[​](#scaleimagestosamesize "Direct link to scaleimagestosamesize") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* Scales 2 images to the same size before execution of comparison. Highly recommended to enable `ignoreAntialiasing` and `ignoreAlpha` ## Direct pixelmatch control[​](#direct-pixelmatch-control "Direct link to Direct pixelmatch control") *** Added in v10.1.0 `compareOptions.pixelmatch` has no equivalent in v9 (ResembleJS). It's a net-new way to control the comparison engine directly, instead of using an `ignore*` preset. ### `compareOptions.pixelmatch`[​](#compareoptionspixelmatch "Direct link to compareoptionspixelmatch") * Type `object` * Default `undefined` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting for that specific used method* - **Added in:** `v10.1.0` Passes settings directly to [pixelmatch](https://github.com/mapbox/pixelmatch) instead of using an `ignore*` preset. **Use this when the five `ignore*` presets are too coarse:** you need a specific threshold value the presets don't offer, or a diff image that's actually readable in your reports/CI output instead of the default magenta highlight. Mutually exclusive within the same options object Putting any `ignore*` key and `pixelmatch` in the **same** options object throws `CompareOptionsConflictError`, even when the `ignore*` value is `false` (see the invalid example below). Pick one mode per object: `ignore*` presets or `pixelmatch`, never both. This only applies within one object. Service config and a method call's options are separate objects, so a `check*` call **is allowed** to use a different mode than the service config, for example the service uses `ignore*` presets but one call passes `pixelmatch` instead (or vice versa). No error in that case, just a warning logged noting the compare mode switch. | Field | Type | Default | What it's for | | -------------- | -------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `threshold` | `number` | `0.1` | Sensitivity from 0 (any pixel difference fails) to 1 (almost nothing fails). Use this to dial in one exact sensitivity value instead of picking the closest `ignore*` preset. | | `includeAA` | `boolean` | `false` | `true` counts anti-aliased edge pixels as mismatches; `false` forgives them. Turn this off if font/shape edge rendering differences are causing flaky failures. | | `diffColor` | `[number, number, number]` | `[255, 0, 255]` (magenta) | RGB color for mismatched pixels in the diff image. Change it if magenta blends into your UI (e.g. a pink/purple theme) and mismatches are hard to spot. | | `aaColor` | `[number, number, number]` | `[255, 0, 255]` (magenta) | RGB color for anti-aliased pixels, kept visually separate from real mismatches so you can tell "rendering noise" apart from "actual bug" at a glance. | | `diffColorAlt` | `[number, number, number]` | `[255, 0, 255]` (magenta) | RGB color for pixels that were added or removed (not just recolored), useful for spotting layout shifts vs. color changes. | | `alpha` | `number` | `0.1` | Opacity of the diff overlay on top of the actual screenshot. Raise it to make diffs pop more in reports; lower it to still see the underlying UI clearly. Not related to the `ignoreAlpha` preset. | | `diffMask` | `boolean` | `false` | Set `true` to output just the raw diff (transparent background) instead of the diff drawn over your screenshot, useful for building your own custom diff viewer/report. | | `checkerboard` | `boolean` | `true` | Controls how semi-transparent pixels are rendered in the diff. Turn off if the checkerboard pattern is easy to confuse with real content in your screenshots. | **Service config:** ``` // wdio.conf.js export const config = { // ... services: [ ['visual', { compareOptions: { pixelmatch: { threshold: 0.063, includeAA: true, }, }, }], ], } ``` **Method override when the service uses `ignore*` presets:** ``` await browser.checkScreen('homepage', { pixelmatch: { threshold: 0.05 }, }) ``` **Method override when the service uses `pixelmatch`:** ``` await browser.checkScreen('homepage', { ignoreLess: true, }) ``` **Invalid: throws `CompareOptionsConflictError`** ``` compareOptions: { ignoreLess: false, pixelmatch: { threshold: 0.063 }, } ``` See the [pixelmatch documentation](https://github.com/mapbox/pixelmatch) for full option semantics. ## Mobile block-outs[​](#mobile-block-outs "Direct link to Mobile block-outs") *** ### `blockOutStatusBar`[​](#blockoutstatusbar "Direct link to blockoutstatusbar") * Type `boolean` * Default `true` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting. This is **Mobile only*** Automatically block out the status and address bar during comparisons. This prevents failures on time, wifi or battery status. ### `blockOutToolBar`[​](#blockouttoolbar "Direct link to blockouttoolbar") * Type `boolean` * Default `true` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting. This is **Mobile only*** Automatically block out the toolbar. ### `blockOutSideBar`[​](#blockoutsidebar "Direct link to blockoutsidebar") * Type `boolean` * Default `true` * Required `no` - **Remark:** *Can only be used for `checkScreen()`. It will override the plugin setting. This is **iPad only*** Automatically block out the sidebar for iPads in landscape mode during comparisons. This prevents failures on the tab/private/bookmark native component. ## Results & reporting[​](#results--reporting "Direct link to Results & reporting") *** ### `rawMisMatchPercentage`[​](#rawmismatchpercentage "Direct link to rawmismatchpercentage") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* If true the return percentage will be like `0.12345678`, default is `0.12` ### `returnAllCompareData`[​](#returnallcomparedata "Direct link to returnallcomparedata") * Type `boolean` * Default `false` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* This will return all compare data, not only the mismatch percentage ### `saveAboveTolerance`[​](#saveabovetolerance "Direct link to saveabovetolerance") * Type `number` * Default `0` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. It will override the plugin setting* Allowable value of `misMatchPercentage` that prevents saving images with differences ### `diffPixelBoundingBoxProximity`[​](#diffpixelboundingboxproximity "Direct link to diffpixelboundingboxproximity") * Type `number` * Default `5` * Required `no` - **Remark:** *Can also be used for `checkElement`, `checkScreen()` and `checkFullPageScreen()`. Only relevant when [`createJsonReportFiles`](/docs/visual-testing/service-options.md#createjsonreportfiles) is enabled.* The pixel proximity used to group diff pixels together in JSON reports. Higher values group more pixels into fewer bounding boxes; lower values produce more accurate but more numerous boxes. --- Source: https://webdriver.io/docs/percy-overview.md # Unlocking Percy - An Overview ## Introduction[​](#introduction "Direct link to Introduction") [Percy](https://percy.io/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) is an all-in-one visual testing and review platform. It captures screenshots, compares them against the baseline, and highlights visual changes. With increased visual coverage, teams can deploy code changes with confidence with every commit. WebdriverIO supports cross-browser visual testing natively using Percy and App Percy. You can use Percy for visual testing of website and native mobile applications. The benefits of utilizing Percy for visual testing include the following: * Consistency: Promotes consistent user experience by identifying visual discrepancies early in the development process. * Efficiency: Improves efficiency by reducing the time and effort required to manually spot visual regressions. * Integrations: Percy integrates with popular tools and services like GitHub, GitLab, Bitbucket, and more. * Collaboration: Improves collaboration between developers, designers, and QA teams by providing a visual representation of changes. * Prevent regression: Prevents you from experiencing unintended visual regressions. ## How does Percy work?[​](#how-does-percy-work "Direct link to How does Percy work?") Percy compares new snapshots against relevant baselines to detect visual changes. Percy manages baseline selection across branches so your tests are always relevant. If visual changes are detected, Percy highlights and groups the resulting differences for you to review. ## Next steps[​](#next-steps "Direct link to Next steps") * [Use Percy for web applications](https://webdriver.io/docs/visual-testing/integrate-with-percy) * [Use App Percy for mobile applications](https://webdriver.io/docs/visual-testing/integrate-with-app-percy) --- Source: https://webdriver.io/docs/visual-testing/integrate-with-percy.md # For Web Application ## Integrate your WebdriverIO tests with Percy[​](#integrate-your-webdriverio-tests-with-percy "Direct link to Integrate your WebdriverIO tests with Percy") Before integration, you can explore [Percy’s sample build tutorial for WebdriverIO](https://www.browserstack.com/docs/percy/sample-build/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). Integrate your WebdriverIO automated tests with BrowserStack Percy and here's an overview of the integration steps: ### Step 1: Create a Percy project[​](#step-1-create-a-percy-project "Direct link to Step 1: Create a Percy project") [Sign in](https://percy.io/signup/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it to set your environment variable in the next step. For details on creating a project, see [Create a Percy project](https://www.browserstack.com/docs/percy/get-started/create-project/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). ### Step 2: Set the project token as an environment variable[​](#step-2-set-the-project-token-as-an-environment-variable "Direct link to Step 2: Set the project token as an environment variable") Run the given command to set PERCY\_TOKEN as an environment variable: ``` export PERCY_TOKEN="" // macOS or Linux $Env:PERCY_TOKEN="" // Windows PowerShell set PERCY_TOKEN="" // Windows CMD ``` ### Step 3: Install Percy dependencies[​](#step-3-install-percy-dependencies "Direct link to Step 3: Install Percy dependencies") Install the components required to establish the integration environment for your test suite. To install the dependencies, run the following command: ``` npm install --save-dev @percy/cli @percy/webdriverio ``` ### Step 4: Update your test script[​](#step-4-update-your-test-script "Direct link to Step 4: Update your test script") Import the Percy library to use the method and attributes required to take screenshots. The following example uses the percySnapshot() function in the async mode: ``` import percySnapshot from '@percy/webdriverio'; describe('webdriver.io page', () => { it('should have the right title', async () => { await browser.url('https://webdriver.io'); await expect(browser).toHaveTitle('WebdriverIO Β· Next-gen browser and mobile automation test framework for Node.js'); await percySnapshot('webdriver.io page'); }); }); ``` When using WebdriverIO in the [standalone mode](https://webdriver.io/docs/setuptypes.html/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation), provide the browser object as the first argument to the `percySnapshot` function: ``` import { remote } from 'webdriverio' import percySnapshot from '@percy/webdriverio'; const browser = await remote({ logLevel: 'trace', capabilities: { browserName: 'chrome' } }); await browser.url('https://duckduckgo.com'); const inputElem = await browser.$('#search_form_input_homepage'); await inputElem.setValue('WebdriverIO'); const submitBtn = await browser.$('#search_button_homepage'); await submitBtn.click(); // the browser object is required in standalone mode percySnapshot(browser, 'WebdriverIO at DuckDuckGo'); await browser.deleteSession(); ``` The snapshot method arguments are: ``` percySnapshot(name[, options]) ``` ### Standalone mode[​](#standalone-mode "Direct link to Standalone mode") ``` percySnapshot(browser, name[, options]) ``` * browser (required) - The WebdriverIO browser object * name (required) - The snapshot name; must be unique to each snapshot * options - See per-snapshot configuration options To learn more, see [Percy snapshot](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). ### Step 5: Run Percy[​](#step-5-run-percy "Direct link to Step 5: Run Percy") Run your tests using the `percy exec` command as shown below: If you are unable to use the `percy:exec` command or prefer to run your tests using IDE run options, you can use the `percy:exec:start` and `percy:exec:stop` commands. To learn more, visit [Run Percy](https://www.browserstack.com/docs/percy/integrate/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). ``` percy exec -- wdio wdio.conf.js ``` ``` [percy] Percy has started! [percy] Created build #1: https://percy.io/[your-project] [percy] Running "wdio wdio.conf.js" ... [...] webdriver.io page [percy] Snapshot taken "webdriver.io page" [...] βœ“ should have the right title ... [percy] Stopping percy... [percy] Finalized build #1: https://percy.io/[your-project] [percy] Done! ``` ## Visit the following pages for more details:[​](#visit-the-following-pages-for-more-details "Direct link to Visit the following pages for more details:") * [Integrate your WebdriverIO tests with Percy](https://www.browserstack.com/docs/percy/integrate/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) * [Environment variable page](https://www.browserstack.com/docs/percy/get-started/set-env-var/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) * [Integrate using BrowserStack SDK](https://www.browserstack.com/docs/percy/integrate-bstack-sdk/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) if you are using BrowserStack Automate. | Resource | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | [Official docs](https://www.browserstack.com/docs/percy/integrate/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | Percy's WebdriverIO documentation | | [Sample build - Tutorial](https://www.browserstack.com/docs/percy/sample-build/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | Percy's WebdriverIO tutorial | | [Official video](https://youtu.be/1Sr_h9_3MI0/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | Visual Testing with Percy | | [Blog](https://www.browserstack.com/blog/introducing-visual-reviews-2-0/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | Introducing Visual Reviews 2.0 | --- Source: https://webdriver.io/docs/visual-testing/integrate-with-app-percy.md # For Mobile Application ## Integrate your WebdriverIO tests with App Percy[​](#integrate-your-webdriverio-tests-with-app-percy "Direct link to Integrate your WebdriverIO tests with App Percy") Before integration, you can explore [App Percy’s sample build tutorial for WebdriverIO](https://www.browserstack.com/docs/app-percy/sample-build/webdriverio-javascript/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). Integrate your test suite with BrowserStack App Percy and here's an overview of the integration steps: ### Step 1: Create new app project on percy dashboard[​](#step-1-create-new-app-project-on-percy-dashboard "Direct link to Step 1: Create new app project on percy dashboard") [Sign in](https://percy.io/signup/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) to Percy and [create a new app type project](https://www.browserstack.com/docs/app-percy/get-started/create-project/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). After you’ve created the project, you’ll be shown a `PERCY_TOKEN` environment variable. Percy will use the `PERCY_TOKEN` to know which organisation and project to upload the screenshots to. You will need this `PERCY_TOKEN` in next steps. ### Step 2: Set the project token as an environment variable[​](#step-2-set-the-project-token-as-an-environment-variable "Direct link to Step 2: Set the project token as an environment variable") Run the given command to set PERCY\_TOKEN as an environment variable: ``` export PERCY_TOKEN="" // macOS or Linux $Env:PERCY_TOKEN="" // Windows PowerShell set PERCY_TOKEN="" // Windows CMD ``` ### Step 3: Install Percy packages[​](#step-3-install-percy-packages "Direct link to Step 3: Install Percy packages") Install the components required to establish the integration environment for your test suite. To install the dependencies, run the following command: ``` npm install --save-dev @percy/cli ``` ### Step 4: Install dependencies[​](#step-4-install-dependencies "Direct link to Step 4: Install dependencies") Install the Percy Appium app ``` npm install --save-dev @percy/appium-app ``` ### Step 5: Update test script[​](#step-5-update-test-script "Direct link to Step 5: Update test script") Make sure to import @percy/appium-app in your code. Below is an example test using the percyScreenshot function. Use this function wherever you have to take a screenshot. ``` import percyScreenshot from '@percy/appium-app'; describe('Appium webdriverio test example', function() { it('takes a screenshot', async () => { await percyScreenshot('Appium JS example'); }); }); ``` We are passing the required arguments.percyScreenshot method. The screenshot method arguments are: ``` percyScreenshot(driver, name[, options]) ``` ### Step 6: Run your test script[​](#step-6-run-your-test-script "Direct link to Step 6: Run your test script") Run your tests using `percy app:exec`. If you are unable to use the percy app:exec command or prefer to run your tests using IDE run options, you can use the percy app:exec:start and percy app:exec:stop commands. To learn more, visit [Run Percy](https://www.browserstack.com/docs/app-percy/references/commands/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). ``` $ percy app:exec -- appium test command ``` This command starts Percy, create a new Percy build, takes snapshots and uploads them to your project, and stops Percy: ``` [percy] Percy has started! [percy] Created build #1: https://percy.io/[your-project] [percy] Snapshot taken "Appium WebdriverIO Example" [percy] Stopping percy... [percy] Finalized build #1: https://percy.io/[your-project] [percy] Done! ``` ## Visit the following pages for more details:[​](#visit-the-following-pages-for-more-details "Direct link to Visit the following pages for more details:") * [Integrate your WebdriverIO tests with Percy](https://www.browserstack.com/docs/app-percy/integrate/webdriverio-javascript/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) * [Environment variable page](https://www.browserstack.com/docs/app-percy/get-started/set-env-var/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) * [Integrate using BrowserStack SDK](https://www.browserstack.com/docs/app-percy/integrate-bstack-sdk/webdriverio/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) if you are using BrowserStack Automate. | Resource | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | [Official docs](https://www.browserstack.com/docs/app-percy/integrate/webdriverio-javascript/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | App Percy's WebdriverIO documentation | | [Sample build - Tutorial](https://www.browserstack.com/docs/app-percy/sample-build/webdriverio-javascript/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | App Percy's WebdriverIO tutorial | | [Official video](https://youtu.be/a4I_RGFdwvc/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | Visual Testing with App Percy | | [Blog](https://www.browserstack.com/blog/product-launch-app-percy/?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation) | Meet App Percy: AI-powered automated visual testing platform for native apps | --- Source: https://webdriver.io/docs/accessibility-testing/axe-core.md # Axe Core You can include accessibility tests within your WebdriverIO test suite using the open-source accessibility tools [from Deque called Axe](https://www.deque.com/axe/). The setup is very easy, all you need to do is to install the WebdriverIO Axe adapter via: * npm * Yarn * pnpm * Bun ``` npm install -g @axe-core/webdriverio ``` ``` yarn global add @axe-core/webdriverio ``` ``` pnpm add -g @axe-core/webdriverio ``` ``` bun add --global @axe-core/webdriverio ``` The Axe adapter can be used either in [standalone or testrunner](/docs/setuptypes.md) mode by simply importing and initializing it with the [browser object](/docs/api/browser.md), e.g.: ``` import { browser } from '@wdio/globals' import AxeBuilder from '@axe-core/webdriverio' describe('Accessibility Test', () => { it('should get the accessibility results from a page', async () => { const builder = new AxeBuilder({ client: browser }) await browser.url('https://testingbot.com') const result = await builder.analyze() console.log('Acessibility Results:', result) }) }) ``` You can find more documentation on the Axe WebdriverIO adapter [on GitHub](https://github.com/dequelabs/axe-core-npm/tree/develop/packages/webdriverio#usage). --- Source: https://webdriver.io/docs/accessibility-testing/browserstack.md # BrowserStack Accessibility Testing You can easily integrate accessibility tests in your WebdriverIO test suites using the [Automated tests feature of BrowserStack Accessibility Testing](https://www.browserstack.com/docs/accessibility/automated-tests?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). ## Advantages of Automated Tests in BrowserStack Accessibility Testing[​](#advantages-of-automated-tests-in-browserstack-accessibility-testing "Direct link to Advantages of Automated Tests in BrowserStack Accessibility Testing") To use Automated tests in BrowserStack Accessibility Testing, your tests should be running on BrowserStack Automate. The following are the advantages of Automated tests: * Seamlessly integrates into your pre-existing automation test suite. * No code changes are required in test cases. * Requires zero additional maintenance for accessibility testing. * Understand historical trends and gain test-case insights. ## Get Started with BrowserStack Accessibility Testing[​](#get-started-with-browserstack-accessibility-testing "Direct link to Get Started with BrowserStack Accessibility Testing") Follow these steps to integrate your WebdriverIO test suites with BrowserStack's Accessibility Testing: 1. Install `@wdio/browserstack-service` npm package. * npm * Yarn * pnpm * Bun ``` npm install --save-dev @wdio/browserstack-service ``` ``` yarn add --dev @wdio/browserstack-service ``` ``` pnpm add --save-dev @wdio/browserstack-service ``` ``` bun add --dev @wdio/browserstack-service ``` 2. Update `wdio.conf.js` config file. ``` exports.config = { //... user: '' || process.env.BROWSERSTACK_USERNAME, key: '' || process.env.BROWSERSTACK_ACCESS_KEY, commonCapabilities: { 'bstack:options': { projectName: "Your static project name goes here", buildName: "Your static build/job name goes here" } }, services: [ ['browserstack', { accessibility: true, // Optional configuration options accessibilityOptions: { 'wcagVersion': 'wcag21a', 'includeIssueType': { 'bestPractice': false, 'needsReview': true }, 'includeTagsInTestingScope': ['Specify tags of test cases to be included'], 'excludeTagsInTestingScope': ['Specify tags of test cases to be excluded'] }, }] ], //... }; ``` You can view detailed instructions [here](https://www.browserstack.com/docs/accessibility/automated-tests/get-started/webdriverio?utm_source=webdriverio\&utm_medium=partnered\&utm_campaign=documentation). --- Source: https://webdriver.io/docs/accessibility-testing/testmuai.md # TestMu AI Accessibility Testing You can easily integrate accessibility tests in your WebdriverIO test suites using [TestMu AI Accessibility Testing](https://www.testmuai.com/support/docs/accessibility-automation-settings/). ## Advantages of TestMu AI Accessibility Testing[​](#advantages-of-testmu-ai-accessibility-testing "Direct link to Advantages of TestMu AI Accessibility Testing") TestMu AI Accessibility Testing helps you identify and fix accessibility issues in your web applications. The following are the key advantages: * Seamlessly integrates with your existing WebdriverIO test automation. * Automated accessibility scanning during test execution. * Comprehensive WCAG compliance reporting. * Detailed issue tracking with remediation guidance. * Support for multiple WCAG standards (WCAG 2.0, WCAG 2.1, WCAG 2.2). * Real-time accessibility insights in the TestMu AI dashboard. ## Get Started with TestMu AI Accessibility Testing[​](#get-started-with-testmu-ai-accessibility-testing "Direct link to Get Started with TestMu AI Accessibility Testing") Follow these steps to integrate your WebdriverIO test suites with TestMu AI's Accessibility Testing: 1. Install the TestMu AI WebdriverIO service package. * npm * Yarn * pnpm * Bun ``` npm install --save-dev @lambdatest/wdio-lambdatest-service ``` ``` yarn add --dev @lambdatest/wdio-lambdatest-service ``` ``` pnpm add --save-dev @lambdatest/wdio-lambdatest-service ``` ``` bun add --dev @lambdatest/wdio-lambdatest-service ``` 2. Update your `wdio.conf.js` configuration file. ``` exports.config = { //... user: process.env.LT_USERNAME || '', key: process.env.LT_ACCESS_KEY || '', capabilities: [{ browserName: 'chrome', 'LT:Options': { platform: 'Windows 10', version: 'latest', accessibility: true, // Enable accessibility testing accessibilityOptions: { wcagVersion: 'wcag21a', // WCAG version (wcag20, wcag21a, wcag21aa, wcag22aa) bestPractice: false, needsReview: true } } }], services: [ ['lambdatest', { tunnel: false }] ], //... }; ``` 3. Run your tests as usual. TestMu AI will automatically scan for accessibility issues during test execution. ``` npx wdio run wdio.conf.js ``` ## Configuration Options[​](#configuration-options "Direct link to Configuration Options") The `accessibilityOptions` object supports the following parameters: * **wcagVersion**: Specify the WCAG standard version to test against * `wcag20` - WCAG 2.0 Level A * `wcag21a` - WCAG 2.1 Level A * `wcag21aa` - WCAG 2.1 Level AA (default) * `wcag22aa` - WCAG 2.2 Level AA * **bestPractice**: Include best practice recommendations (default: `false`) * **needsReview**: Include issues that need manual review (default: `true`) ## Viewing Accessibility Reports[​](#viewing-accessibility-reports "Direct link to Viewing Accessibility Reports") After your tests complete, you can view detailed accessibility reports in the [TestMu AI Dashboard](https://automation.lambdatest.com/): 1. Navigate to your test execution 2. Click on the "Accessibility" tab 3. Review identified issues with severity levels 4. Get remediation guidance for each issue For more detailed information, visit the [TestMu AI Accessibility Automation documentation](https://www.testmuai.com/support/docs/accessibility-automation-settings/). --- Source: https://webdriver.io/docs/ocr-testing/ocr-testing.md # OCR Testing Automated testing on mobile native apps and desktop sites can be particularly challenging when dealing with elements that lack unique identifiers. Standard [WebdriverIO selectors](https://webdriver.io/docs/selectors) may not always help you. Enter the world of the `@wdio/ocr-service`, a powerful service that leverages OCR ([Optical Character Recognition](https://en.wikipedia.org/wiki/Optical_character_recognition)) to search, wait for, and interact with on-screen elements based on their **visible text**. The following custom commands will be provided and added to the `browser/driver` object so you will get the right toolset to do your job. * [`await browser.ocrGetText`](/docs/ocr-testing/ocr-get-text.md) * [`await browser.ocrGetElementPositionByText`](/docs/ocr-testing/ocr-get-element-position-by-text.md) * [`await browser.ocrWaitForTextDisplayed`](/docs/ocr-testing/ocr-wait-for-text-displayed.md) * [`await browser.ocrClickOnText`](/docs/ocr-testing/ocr-click-on-text.md) * [`await browser.ocrSetValue`](/docs/ocr-testing/ocr-set-value.md) ### How does it work[​](#how-does-it-work "Direct link to How does it work") This service will 1. create a screenshot of your screen/device. (If needed you can provide a haystack, which can be an element or a rectangle object, to pinpoint a specific area. See the documentation for each command.) 2. optimize the result for OCR by turning the screenshot into black/white with a high contrast screenshot (the high contrast is needed to prevent a lot of image background noise. This can be customized per command.) 3. uses [Optical Character Recognition](https://en.wikipedia.org/wiki/Optical_character_recognition) from [Tesseract.js](https://github.com/naptha/tesseract.js)/[Tesseract](https://github.com/tesseract-ocr/tesseract) to get all text from the screen and highlight all found text on an image. It can support several languages which can be found [here.](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions.html) 4. uses Fuzzy Logic from [Fuse.js](https://fusejs.io/) to find strings that are *approximately equal* to a given pattern (rather than exactly). This means for example that the search value `Username` can also find the text `Usename` or vice versa. 5. Provide a cli wizzard (`npx ocr-service`) to validate your images and retrieve text through your terminal An example of steps 1, 2 and 3 can be found in this image ![Process steps](/assets/images/processing-steps-d18a7fd1fea653b0f74ef3c63cc63f2a.jpg) It works with **ZERO** system dependencies (besides what WebdriverIO uses), but if needed it can also work with a local installation from [Tesseract](https://tesseract-ocr.github.io/tessdoc/) which will reduce the execution time drastically! (See also the [Test Execution Optimization](#test-execution-optimization) on how to speed up your tests.) Enthusiastic? Start using it today by following the [Getting Started](/docs/ocr-testing/getting-started.md) guide. Important There are a variety of reasons you might not get good quality output from Tesseract. One of the biggest reasons that could be related to your app and this module could be the fact that there is no proper color distinction between the text that needs to be found and the background. For example, white text on a dark background can *easily* be found, but light text on a white background or dark text on a dark background can hardly be found. See also [this page](https://tesseract-ocr.github.io/tessdoc/ImproveQuality) for more information from Tesseract. Also don't forget to read the [FAQ](/docs/ocr-testing/ocr-faq.md). --- Source: https://webdriver.io/docs/ocr-testing/getting-started.md # Getting Started ## Installation[​](#installation "Direct link to Installation") The easiest way is to keep `@wdio/ocr-service` as a dependency in your `package.json` via. * npm * Yarn * pnpm * Bun ``` npm install @wdio/ocr-service --save-dev ``` ``` yarn add @wdio/ocr-service --dev ``` ``` pnpm add @wdio/ocr-service --save-dev ``` ``` bun add @wdio/ocr-service --dev ``` Instructions on how to install `WebdriverIO` can be found [here.](/docs/gettingstarted.md) note This module uses Tesseract as an OCR engine. By default, it will verify if you have a local installation of Tesseract installed on your system, if so, it will use that. If not, it will use the [Node.js Tesseract.js](https://github.com/naptha/tesseract.js) module which is automatically installed for you. If you want to speed up the image processing then the advice is to use a locally installed version of Tesseract. See also [Test execution time](/docs/ocr-testing/more-test-optimization.md#using-a-local-installation-of-tesseract). Instruction on how to install Tesseract as a system dependency on your local system can be found [here](https://tesseract-ocr.github.io/tessdoc/Installation.html). caution For installation questions/errors with Tesseract please refer to the [Tesseract](https://github.com/tesseract-ocr/tesseract) project. ## Typescript support[​](#typescript-support "Direct link to Typescript support") Ensure that you add `@wdio/ocr-service` to your `tsconfig.json` configuration file. tsconfig.json ``` { "compilerOptions": { "types": ["node", "@wdio/globals/types", "@wdio/ocr-service"] } } ``` ## Configuration[​](#configuration "Direct link to Configuration") To use the service you need to add `ocr` to your services array in `wdio.conf.ts` ``` // wdio.conf.js exports.config = { //... services: [ // your other services [ "ocr", { contrast: 0.25, imagesFolder: ".tmp/", language: "eng", }, ], ], }; ``` ### Configuration Options[​](#configuration-options "Direct link to Configuration Options") #### `contrast`[​](#contrast "Direct link to contrast") * Type `number` * Default `0.25` * Required `No` The higher the contrast, the darker the image and vice versa. This can help to find text in an image. It accepts values between `-1` and `1`. #### `imagesFolder`[​](#imagesfolder "Direct link to imagesfolder") * Type `string` * Default `{project-root}/.tmp/ocr` * Required `No` The folder where the OCR results are stored. note If you provide a custom `imagesFolder`, then the service will automatically add the subfolder `ocr` to it. #### `language`[​](#language "Direct link to language") * Type `string` * Default `eng` * Required `No` The language that Tesseract will recognize. More info can be found [here](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions) and the supported languages can be found [here](https://github.com/webdriverio/visual-testing/blob/main/packages/ocr-service/src/utils/constants.ts). ## Logs[​](#logs "Direct link to Logs") This module will automatically add extra logs to the WebdriverIO logs. It writes to the `INFO` and `WARN` logs with the name `@wdio/ocr-service`. Examples can be found below. ``` ............... [0-0] 2024-05-24T06:55:12.739Z INFO @wdio/ocr-service: Adding commands to global browser [0-0] 2024-05-24T06:55:12.750Z INFO @wdio/ocr-service: Adding browser command "ocrGetText" to browser object [0-0] 2024-05-24T06:55:12.751Z INFO @wdio/ocr-service: Adding browser command "ocrGetElementPositionByText" to browser object [0-0] 2024-05-24T06:55:12.751Z INFO @wdio/ocr-service: Adding browser command "ocrWaitForTextDisplayed" to browser object [0-0] 2024-05-24T06:55:12.751Z INFO @wdio/ocr-service: Adding browser command "ocrClickOnText" to browser object [0-0] 2024-05-24T06:55:12.751Z INFO @wdio/ocr-service: Adding browser command "ocrSetValue" to browser object ............... [0-0] 2024-05-24T06:55:13.667Z INFO @wdio/ocr-service:getData: Using system installed version of Tesseract [0-0] 2024-05-24T06:55:14.019Z INFO @wdio/ocr-service:getData: It took '0.351s' to process the image. [0-0] 2024-05-24T06:55:14.019Z INFO @wdio/ocr-service:getData: The following text was found through OCR: [0-0] [0-0] IQ Docs API Blog Contribute Community Sponsor Next-gen browser and mobile automation Welcome! How can | help? i test framework for Node.js Get Started Why WebdriverI0? View on GitHub Watch on YouTube [0-0] 2024-05-24T06:55:14.019Z INFO @wdio/ocr-service:getData: OCR Image with found text can be found here: [0-0] [0-0] .tmp/ocr/desktop-1716533713585.png [0-0] 2024-05-24T06:55:14.019Z INFO @wdio/ocr-service:ocrGetElementPositionByText: We searched for the word "Get Started" and found one match "Started" with score "63.64 ............... ``` --- Source: https://webdriver.io/docs/ocr-testing/cli-wizard.md # CLI Wizard You can validate which text can be found in an image without running a test by using the OCR CLI Wizard. The only thing that are needed are: * you have installed the `@wdio/ocr-service` as a dependency, see [Getting Started](/docs/ocr-testing/getting-started.md) * an image that you want to process Then run the following command to start the wizard ``` npx ocr-service ``` This will start a wizard that will guide you through the steps to select an image and use a haystack plus advanced mode. The following questions are asked ## How would you like to specify the file?[​](#how-would-you-like-to-specify-the-file "Direct link to How would you like to specify the file?") The following options can be selected * Use a "file explorer" * Type the file path manually ### Use a "file explorer"[​](#use-a-file-explorer "Direct link to Use a \"file explorer\"") The CLI wizard provides an option to use a "file explorer" to search for files on your system. It starts from the folder you call the command. After selecting an image (use your arrow keys and the ENTER key) you will proceed to the next question ### Type the file path manually[​](#type-the-file-path-manually "Direct link to Type the file path manually") This is a direct path to a file somewhere on your local machine ### Would you like to use a haystack?[​](#would-you-like-to-use-a-haystack "Direct link to Would you like to use a haystack?") Here you have the option to select an area that needs to be processed. This can speed up the process or reduce/narrow down the amount of text the OCR engine might find. You need to provide `x`, `y`, `width`, `height` data based on the following questions: * Enter the x coordinate: * Enter the y coordinate: * Enter the width: * Enter the height: ## Do you want to use the advanced mode?[​](#do-you-want-to-use-the-advanced-mode "Direct link to Do you want to use the advanced mode?") Advanced mode will hold extra features like: * setting the contrast * more to follow in the future ## Demo[​](#demo "Direct link to Demo") Here's a demo [](/img/ocr/ocr-service-cli.mp4) --- Source: https://webdriver.io/docs/ocr-testing/more-test-optimization.md # Test execution time By default, this module will check if you have a local installation of Tesseract on your machine/in your pipeline. If you don't have a local installation it will automatically use a [NodeJS](https://github.com/naptha/tesseract.js) version. This might cause some slowness because the image processing will be done by Node.js. NodeJS is not the best system to do heavy processing. **BUT....**, there are ways to optimize the execution time. Let's take the following test script ``` import { browser } from "@wdio/globals"; describe("Search", () => { it("be able to search for a value", async () => { await browser.url("https://webbrowser.io"); await browser.ocrClickOnText({ text: "Search", }); await browser.ocrSetValue({ text: "docs", value: "specfileretries", }); await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", }); }); }); ``` When you execute this for the first time you might see the following results where it took 5.9 seconds to finish the test. ``` npm run wdio -- --logLevel=silent > ocr-demo@1.0.0 wdio > wdio run ./wdio.conf.ts --logLevel=silent Execution of 1 workers started at 2024-05-26T04:52:53.405Z [0-0] RUNNING in chrome - file:///test/specs/test.e2e.ts [0-0] Estimating resolution as 182 [0-0] Estimating resolution as 124 [0-0] Estimating resolution as 126 [0-0] PASSED in chrome - file:///test/specs/test.e2e.ts "spec" Reporter: ------------------------------------------------------------------ [chrome 125.0.6422.78 mac #0-0] Running: chrome (v125.0.6422.78) on mac [chrome 125.0.6422.78 mac #0-0] Session ID: d281dcdc43962b95835aea8f64cab6c7 [chrome 125.0.6422.78 mac #0-0] [chrome 125.0.6422.78 mac #0-0] Β» /test/specs/test.e2e.ts [chrome 125.0.6422.78 mac #0-0] Search [chrome 125.0.6422.78 mac #0-0] βœ“ be able to search for a value [chrome 125.0.6422.78 mac #0-0] [chrome 125.0.6422.78 mac #0-0] 1 passing (5.9s) Spec Files: 1 passed, 1 total (100% completed) in 00:00:08 ``` ## Cropping the search area of a screen[​](#cropping-the-search-area-of-a-screen "Direct link to Cropping the search area of a screen") You can optimize the execution time by providing a cropped area to execute the OCR on. If you would then change the script to this: ``` import { browser } from "@wdio/globals"; describe("Search", () => { it("be able to search for a value", async () => { await browser.url("https://webdriver.io"); await driver.ocrClickOnText({ haystack: $(".DocSearch"), text: "Search", }); await driver.ocrSetValue({ haystack: $(".DocSearch-Form"), text: "docs", value: "specfileretries", }); await driver.ocrWaitForTextDisplayed({ haystack: $(".DocSearch-Dropdown"), text: "specFileRetries", }); }); }); ``` Then you will see a different execution time. ``` npm run wdio -- --logLevel=silent > ocr-demo@1.0.0 wdio > wdio run ./wdio.conf.ts --logLevel=silent Execution of 1 workers started at 2024-05-26T04:56:55.326Z [0-0] RUNNING in chrome - file:///test/specs/test.e2e.ts [0-0] Estimating resolution as 182 [0-0] Estimating resolution as 124 [0-0] Estimating resolution as 124 [0-0] PASSED in chrome - file:///test/specs/test.e2e.ts "spec" Reporter: ------------------------------------------------------------------ [chrome 125.0.6422.78 mac #0-0] Running: chrome (v125.0.6422.78) on mac [chrome 125.0.6422.78 mac #0-0] Session ID: c6cb1843535bda3ee3af07920ce232b8 [chrome 125.0.6422.78 mac #0-0] [chrome 125.0.6422.78 mac #0-0] Β» /test/specs/test.e2e.ts [chrome 125.0.6422.78 mac #0-0] Search [chrome 125.0.6422.78 mac #0-0] βœ“ be able to search for a value [chrome 125.0.6422.78 mac #0-0] [chrome 125.0.6422.78 mac #0-0] 1 passing (4.8s) Spec Files: 1 passed, 1 total (100% completed) in 00:00:08 ``` Cropping images This reduced the local execution time from **5.9** to **4.8 seconds**. This is a reduction of almost **19%**. Imagine what it can do for a larger script with more data on it. ## Using a local installation of Tesseract[​](#using-a-local-installation-of-tesseract "Direct link to Using a local installation of Tesseract") You can speed up your execution time to even less than a minute if you have a local installation of Tessarect on your local machine and or in your pipeline (more information about installing Tesseract on your local system can be found [here](https://tesseract-ocr.github.io/tessdoc/Installation.html)). You can find the execution time of the same script using a local installation of Tesseract below. ``` npm run wdio -- --logLevel=silent > ocr-demo@1.0.0 wdio > wdio run ./wdio.conf.ts --logLevel=silent Execution of 1 workers started at 2024-05-26T04:59:11.620Z [0-0] RUNNING in chrome - file:///test/specs/test.e2e.ts [0-0] PASSED in chrome - file:///test/specs/test.e2e.ts "spec" Reporter: ------------------------------------------------------------------ [chrome 125.0.6422.78 mac #0-0] Running: chrome (v125.0.6422.78) on mac [chrome 125.0.6422.78 mac #0-0] Session ID: 87f8c1e949e15a383b902e4d59b1f738 [chrome 125.0.6422.78 mac #0-0] [chrome 125.0.6422.78 mac #0-0] Β» /test/specs/test.e2e.ts [chrome 125.0.6422.78 mac #0-0] Search [chrome 125.0.6422.78 mac #0-0] βœ“ be able to search for a value [chrome 125.0.6422.78 mac #0-0] [chrome 125.0.6422.78 mac #0-0] 1 passing (3.9s) Spec Files: 1 passed, 1 total (100% completed) in 00:00:06 ``` Local installation This reduced the local execution time from **5.9** to **3.9 seconds**. This is a reduction of almost **34%**. Imagine what it can do for a larger script with more data on it. --- Source: https://webdriver.io/docs/ocr-testing/ocr-faq.md # Frequently Asked Questions ## My tests are very slow[​](#my-tests-are-very-slow "Direct link to My tests are very slow") When you are using this `@wdio/ocr-service` you are not using it to speed up your tests, you use it because you have a hard time locating elements in your web/mobile app, and you want an easier way to locate them. And we all hopefully know that when you want something, you lose something else. **But....**, there is a way to make the `@wdio/ocr-service` execute faster than normal. More information about that can be found [here](/docs/ocr-testing/more-test-optimization.md). ## Can I use the commands from this service with the default WebdriverIO commands/selectors?[​](#can-i-use-the-commands-from-this-service-with-the-default-webdriverio-commandsselectors "Direct link to Can I use the commands from this service with the default WebdriverIO commands/selectors?") Yes, you can combine the commands to make your script even more powerful! The advice is to use the default WebdriverIO commands/selectors as much as possible and only use this service when you can't find a unique selector, or your selector will become too brittle. ## My text isn't found, how is that possible?[​](#my-text-isnt-found-how-is-that-possible "Direct link to My text isn't found, how is that possible?") First, it's important to understand how the OCR process in this module works, so please read [this](/docs/ocr-testing/ocr-testing.md) page. If you still can't find your text, you might try the following things. ### The image area is too big[​](#the-image-area-is-too-big "Direct link to The image area is too big") When the module needs to process a large area of the screenshot it might not find the text. You can provide a smaller area by providing a haystack when you use a command. Please check the [commands](/docs/ocr-testing/ocr-click-on-text.md) which commands support providing a haystack. ### The contrast between the text and background is not correct[​](#the-contrast-between-the-text-and-background-is-not-correct "Direct link to The contrast between the text and background is not correct") This means that you might have light text on a white background or dark text on a dark background. This can result in not being able to find text. In the examples below you can see that the text `Why WebdriverIO?` is white and surrounded by a grey button. In this case, it will result in not finding the `Why WebdriverIO?` text. By increasing the contrast for the specific command it finds the text and can click on it, see the second image. ``` await driver.ocrClickOnText({ haystack: { height: 44, width: 1108, x: 129, y: 590 }, text: "WebdriverIO?", // // With the default contrast of 0.25, the text is not found contrast: 1, }); ``` ![Contrast issues](/assets/images/increased-contrast-4f754391895c21affa9a06514f21d3dc.jpg) ## Why is my element getting clicked but the keyboard on my mobile devices never pops up?[​](#why-is-my-element-getting-clicked-but-the-keyboard-on-my-mobile-devices-never-pops-up "Direct link to Why is my element getting clicked but the keyboard on my mobile devices never pops up?") This can happen on some text fields where the click is determined too long and considered a long tap. You can use the `clickDuration` option on [`ocrClickOnText`](/docs/ocr-testing/ocr-click-on-text.md) and [`ocrSetValue`](/docs/ocr-testing/ocr-set-value.md) to alleviate this. See [here](/docs/ocr-testing/ocr-click-on-text.md#options). ## Can this module provide multiple elements back like WebdriverIO normally can do?[​](#can-this-module-provide-multiple-elements-back-like-webdriverio-normally-can-do "Direct link to Can this module provide multiple elements back like WebdriverIO normally can do?") No, this is currently not possible. If the module finds multiple elements that match the provided selector it will automatically find the element that has the highest matching score. ## Can I fully automate my app with the OCR commands provided by this service?[​](#can-i-fully-automate-my-app-with-the-ocr-commands-provided-by-this-service "Direct link to Can I fully automate my app with the OCR commands provided by this service?") I've never done it, but in theory, it should be possible. Please let us know if you succeed with that ☺️. ## I see an extra file called `{languageCode}.traineddata` being added, what is this?[​](#i-see-an-extra-file-called-languagecodetraineddata-being-added-what-is-this "Direct link to i-see-an-extra-file-called-languagecodetraineddata-being-added-what-is-this") `{languageCode}.traineddata` is a language data file used by Tesseract. It contains the training data for the selected language, which includes the necessary information for Tesseract to recognize English characters and words effectively. ### Contents of `{languageCode}.traineddata`[​](#contents-of-languagecodetraineddata "Direct link to contents-of-languagecodetraineddata") The file generally contains: 1. **Character Set Data:** Information about the characters in the English language. 2. **Language Model:** A statistical model of how characters form words and words form sentences. 3. **Feature Extractors:** Data on how to extract features from images for the recognition of characters. 4. **Training Data:** Data derived from training Tesseract on a large set of English text images. ### Why is the `{languageCode}.traineddata` Important?[​](#why-is-the-languagecodetraineddata-important "Direct link to why-is-the-languagecodetraineddata-important") 1. **Language Recognition:** Tesseract relies on these trained data files to accurately recognize and process text in a specific language. Without `{languageCode}.traineddata`, Tesseract would not be able to recognize English text. 2. **Performance:** The quality and accuracy of OCR are directly related to the quality of the training data. Using the correct trained data file ensures that the OCR process is as accurate as possible. 3. **Compatibility:** Ensuring that the `{languageCode}.traineddata` file is included in your project making it easier to replicate the OCR environment across different systems or team members' machines. ### Versioning `{languageCode}.traineddata`[​](#versioning-languagecodetraineddata "Direct link to versioning-languagecodetraineddata") Including `{languageCode}.traineddata` in your version control system is recommended for the following reasons: 1. **Consistency:** It ensures that all team members or deployment environments use the exact same version of the training data, leading to consistent OCR results across different environments. 2. **Reproducibility:** Storing this file in version control makes it easier to reproduce results when running the OCR process at a later date or on a different machine. 3. **Dependency Management:** Including it in the version control system helps in managing dependencies and ensures that any setup or environment configuration includes the necessary files for the project to run correctly. ## Is there an easy way to see which text is found on my screen without running a test?[​](#is-there-an-easy-way-to-see-which-text-is-found-on-my-screen-without-running-a-test "Direct link to Is there an easy way to see which text is found on my screen without running a test?") Yes, you can use our CLI wizard for that. Documentation can be found [here](/docs/ocr-testing/cli-wizard.md) --- Source: https://webdriver.io/docs/ocr-testing/ocr-click-on-text.md # ocrClickOnText Click on an element based on the provided texts. The command will search for the provided text and try to find a match based on Fuzzy Logic from [Fuse.js](https://fusejs.io/). This means that if you might provide a selector with a typo, or the found text might not be a 100% match it will still try to give you back an element. See the [logs](#logs) below. ## Usage[​](#usage "Direct link to Usage") ``` await browser.ocrClickOnText({ text: "Start3d" }); ``` ## Output[​](#output "Direct link to Output") ### Logs[​](#logs "Direct link to Logs") ``` # Still finding a match even though we searched for "Start3d" and the found text was "Started" [0-0] 2024-05-25T05:05:20.096Z INFO webdriver: COMMAND ocrClickOnText() ...................... [0-0] 2024-05-25T05:05:21.022Z INFO @wdio/ocr-service:ocrGetElementPositionByText: Multiple matches were found based on the word "Start3d". The match "Started" with score "85.71%" will be used. ``` ### Image[​](#image "Direct link to Image") You will find an image in your (default)[`imagesFolder`](/docs/ocr-testing/getting-started.md#imagesfolder) with a target to show you where the module has clicked. ![Process steps](/assets/images/ocr-click-on-text-target-2e82ea5eb99ee5c91dc780a79d6b4247.jpg) ## Options[​](#options "Direct link to Options") ### `text`[​](#text "Direct link to text") * Type `string` * Required `yes` The text you want to search for to click on. #### Example[​](#example "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO" }); ``` ### `clickDuration`[​](#clickduration "Direct link to clickduration") * Type `number` * Default `500 milliseconds` * Required `no` This is the duration of the click. If you want you can also create a "long click" by increasing the time. #### Example[​](#example-1 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", clickDuration: 3000, // This is 3 seconds }); ``` ### `contrast`[​](#contrast "Direct link to contrast") * Type `number` * Default `0.25` * Required `no` The higher the contrast, the darker the image and vice versa. This can help to find text in an image. It accepts values between `-1` and `1`. #### Example[​](#example-2 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", contrast: 0.5, }); ``` ### `haystack`[​](#haystack "Direct link to haystack") * Type `number` * Required `WebdriverIO.Element | ChainablePromiseElement | Rectangle` This is the search area in the screen where the OCR needs to look for text. This can be an element or a rectangle containing `x`, `y`, `width` and `height` #### Example[​](#example-3 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", haystack: $("elementSelector"), }); // OR await browser.ocrClickOnText({ text: "WebdriverIO", haystack: await $("elementSelector"), }); // OR await browser.ocrClickOnText({ text: "WebdriverIO", haystack: { x: 10, y: 50, width: 300, height: 75, }, }); ``` ### `language`[​](#language "Direct link to language") * Type `string` * Default `eng` * Required `No` The language that Tesseract will recognize. More info can be found [here](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions) and the supported languages can be found [here](https://github.com/webdriverio/visual-testing/blob/main/packages/ocr-service/src/utils/constants.ts). #### Example[​](#example-4 "Direct link to Example") ``` import { SUPPORTED_OCR_LANGUAGES } from "@wdio/ocr-service"; await browser.ocrClickOnText({ text: "WebdriverIO", // Use Dutch as a language language: SUPPORTED_OCR_LANGUAGES.DUTCH, }); ``` ### `relativePosition`[​](#relativeposition "Direct link to relativeposition") * Type `object` * Required `no` You can click on the screen relative to the matching element. This can be done based on relative pixels `above`, `right`, `below` or `left` from the matching element note The following combinations are allowed * single properties * `above` + `left` or `above` + `right` * `below` + `left` or `below` + `right` The following combinations are **NOT** allowed * `above` plus `below` * `left` plus `right` #### `relativePosition.above`[​](#relativepositionabove "Direct link to relativepositionabove") * Type `number` * Required `no` Click x pixels `above` the matching element. ##### Example[​](#example-5 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", relativePosition: { above: 100, }, }); ``` #### `relativePosition.right`[​](#relativepositionright "Direct link to relativepositionright") * Type `number` * Required `no` Click x pixels `right` from the matching element. ##### Example[​](#example-6 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", relativePosition: { right: 100, }, }); ``` #### `relativePosition.below`[​](#relativepositionbelow "Direct link to relativepositionbelow") * Type `number` * Required `no` Click x pixels `below` the matching element. ##### Example[​](#example-7 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", relativePosition: { below: 100, }, }); ``` #### `relativePosition.left`[​](#relativepositionleft "Direct link to relativepositionleft") * Type `number` * Required `no` Click x pixels `left` from the matching element. ##### Example[​](#example-8 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", relativePosition: { left: 100, }, }); ``` ### `fuzzyFindOptions`[​](#fuzzyfindoptions "Direct link to fuzzyfindoptions") You can alter the fuzzy logic to find text with the following options. This might help find a better match #### `fuzzyFindOptions.distance`[​](#fuzzyfindoptionsdistance "Direct link to fuzzyfindoptionsdistance") * Type `number` * Default `100` * Required `no` Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match to be at the exact location specified. A distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8. ##### Example[​](#example-9 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", fuzzyFindOptions: { distance: 20, }, }); ``` #### `fuzzyFindOptions.location`[​](#fuzzyfindoptionslocation "Direct link to fuzzyfindoptionslocation") * Type `number` * Default `0` * Required `no` Determines approximately where in the text is the pattern expected to be found. ##### Example[​](#example-10 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", fuzzyFindOptions: { location: 20, }, }); ``` #### `fuzzyFindOptions.threshold`[​](#fuzzyfindoptionsthreshold "Direct link to fuzzyfindoptionsthreshold") * Type `number` * Default `0.6` * Required `no` At what point does the matching algorithm give up. A threshold of 0 requires a perfect match (of both letters and location), a threshold of 1.0 would match anything. ##### Example[​](#example-11 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", fuzzyFindOptions: { threshold: 0.8, }, }); ``` #### `fuzzyFindOptions.isCaseSensitive`[​](#fuzzyfindoptionsiscasesensitive "Direct link to fuzzyfindoptionsiscasesensitive") * Type `boolean` * Default `false` * Required `no` Whether the search should be case sensitive. ##### Example[​](#example-12 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", fuzzyFindOptions: { isCaseSensitive: true, }, }); ``` #### `fuzzyFindOptions.minMatchCharLength`[​](#fuzzyfindoptionsminmatchcharlength "Direct link to fuzzyfindoptionsminmatchcharlength") * Type `number` * Default `2` * Required `no` Only the matches whose length exceeds this value will be returned. (For instance, if you want to ignore single character matches in the result, set it to 2) ##### Example[​](#example-13 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", fuzzyFindOptions: { minMatchCharLength: 5, }, }); ``` #### `fuzzyFindOptions.findAllMatches`[​](#fuzzyfindoptionsfindallmatches "Direct link to fuzzyfindoptionsfindallmatches") * Type `number` * Default `false` * Required `no` When `true`, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string. ##### Example[​](#example-14 "Direct link to Example") ``` await browser.ocrClickOnText({ text: "WebdriverIO", fuzzyFindOptions: { findAllMatches: 100, }, }); ``` --- Source: https://webdriver.io/docs/ocr-testing/ocr-get-element-position-by-text.md # ocrGetElementPositionByText Get the position of a text on the screen. The command will search for the provided text and try to find a match based on Fuzzy Logic from [Fuse.js](https://fusejs.io/). This means that if you might provide a selector with a typo, or the found text might not be a 100% match it will still try to give you back an element. See the [logs](#logs) below. ## Usage[​](#usage "Direct link to Usage") ``` const result = await browser.ocrGetElementPositionByText("Username"); console.log("result = ", JSON.stringify(result, null, 2)); ``` ## Output[​](#output "Direct link to Output") ### Result[​](#result "Direct link to Result") ``` result = { "dprPosition": { "left": 373, "top": 606, "right": 439, "bottom": 620 }, "filePath": ".tmp/ocr/desktop-1716658199410.png", "matchedString": "Started", "originalPosition": { "left": 373, "top": 606, "right": 439, "bottom": 620 }, "score": 85.71, "searchValue": "Start3d" } ``` ### Logs[​](#logs "Direct link to Logs") ``` # Still finding a match even though we searched for "Start3d" and the found text was "Started" [0-0] 2024-05-25T17:29:59.179Z INFO webdriver: COMMAND ocrGetElementPositionByText() ...................... [0-0] 2024-05-25T17:29:59.993Z INFO @wdio/ocr-service:ocrGetElementPositionByText: Multiple matches were found based on the word "Start3d". The match "Started" with score "85.71%" will be used. ``` ## Options[​](#options "Direct link to Options") ### `text`[​](#text "Direct link to text") * Type `string` * Required `yes` The text you want to search for to click on. #### Example[​](#example "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO" }); ``` ### `contrast`[​](#contrast "Direct link to contrast") * Type `number` * Default `0.25` * Required `no` The higher the contrast, the darker the image and vice versa. This can help to find text in an image. It accepts values between `-1` and `1`. #### Example[​](#example-1 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", contrast: 0.5, }); ``` ### `haystack`[​](#haystack "Direct link to haystack") * Type `number` * Required `WebdriverIO.Element | ChainablePromiseElement | Rectangle` This is the search area in the screen where the OCR needs to look for text. This can be an element or a rectangle containing `x`, `y`, `width` and `height` #### Example[​](#example-2 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", haystack: $("elementSelector"), }); // OR await browser.ocrGetElementPositionByText({ text: "WebdriverIO", haystack: await $("elementSelector"), }); // OR await browser.ocrGetElementPositionByText({ text: "WebdriverIO", haystack: { x: 10, y: 50, width: 300, height: 75, }, }); ``` ### `language`[​](#language "Direct link to language") * Type `string` * Default `eng` * Required `No` The language that Tesseract will recognize. More info can be found [here](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions) and the supported languages can be found [here](https://github.com/webdriverio/visual-testing/blob/main/packages/ocr-service/src/utils/constants.ts). #### Example[​](#example-3 "Direct link to Example") ``` import { SUPPORTED_OCR_LANGUAGES } from "@wdio/ocr-service"; await browser.ocrGetElementPositionByText({ text: "WebdriverIO", // Use Dutch as a language language: SUPPORTED_OCR_LANGUAGES.DUTCH, }); ``` ### `fuzzyFindOptions`[​](#fuzzyfindoptions "Direct link to fuzzyfindoptions") You can alter the fuzzy logic to find text with the following options. This might help find a better match #### `fuzzyFindOptions.distance`[​](#fuzzyfindoptionsdistance "Direct link to fuzzyfindoptionsdistance") * Type `number` * Default `100` * Required `no` Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match to be at the exact location specified. A distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8. ##### Example[​](#example-4 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", fuzzyFindOptions: { distance: 20, }, }); ``` #### `fuzzyFindOptions.location`[​](#fuzzyfindoptionslocation "Direct link to fuzzyfindoptionslocation") * Type `number` * Default `0` * Required `no` Determines approximately where in the text is the pattern expected to be found. ##### Example[​](#example-5 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", fuzzyFindOptions: { location: 20, }, }); ``` #### `fuzzyFindOptions.threshold`[​](#fuzzyfindoptionsthreshold "Direct link to fuzzyfindoptionsthreshold") * Type `number` * Default `0.6` * Required `no` At what point does the matching algorithm give up. A threshold of 0 requires a perfect match (of both letters and location), a threshold of 1.0 would match anything. ##### Example[​](#example-6 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", fuzzyFindOptions: { threshold: 0.8, }, }); ``` #### `fuzzyFindOptions.isCaseSensitive`[​](#fuzzyfindoptionsiscasesensitive "Direct link to fuzzyfindoptionsiscasesensitive") * Type `boolean` * Default `false` * Required `no` Whether the search should be case sensitive. ##### Example[​](#example-7 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", fuzzyFindOptions: { isCaseSensitive: true, }, }); ``` #### `fuzzyFindOptions.minMatchCharLength`[​](#fuzzyfindoptionsminmatchcharlength "Direct link to fuzzyfindoptionsminmatchcharlength") * Type `number` * Default `2` * Required `no` Only the matches whose length exceeds this value will be returned. (For instance, if you want to ignore single character matches in the result, set it to 2) ##### Example[​](#example-8 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", fuzzyFindOptions: { minMatchCharLength: 5, }, }); ``` #### `fuzzyFindOptions.findAllMatches`[​](#fuzzyfindoptionsfindallmatches "Direct link to fuzzyfindoptionsfindallmatches") * Type `number` * Default `false` * Required `no` When `true`, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string. ##### Example[​](#example-9 "Direct link to Example") ``` await browser.ocrGetElementPositionByText({ text: "WebdriverIO", fuzzyFindOptions: { findAllMatches: 100, }, }); ``` --- Source: https://webdriver.io/docs/ocr-testing/ocr-get-text.md # ocrGetText Get the text on an image. ### Usage[​](#usage "Direct link to Usage") ``` const result = await browser.ocrGetText(); console.log("result = ", JSON.stringify(result, null, 2)); ``` ## Output[​](#output "Direct link to Output") ### Result[​](#result "Direct link to Result") ``` result = "VS docs API Blog Contribute Community Sponsor v8 *Engishy CV} Q OQ G asearch Next-gen browser and mobile automation Welcome! How can | help? i test framework for Node.js Get Started Why WebdriverI0? View on GitHub Watch on YouTube" ``` ### Logs[​](#logs "Direct link to Logs") ``` [0-0] 2024-05-25T17:38:25.970Z INFO webdriver: COMMAND ocrGetText() ...................... [0-0] 2024-05-25T17:38:26.738Z INFO webdriver: RESULT VS docs API Blog Contribute Community Sponsor v8 *Engishy CV} Q OQ G asearch Next-gen browser and mobile automation Welcome! How can | help? i test framework for Node.js Get Started Why WebdriverI0? View on GitHub Watch on YouTube ``` ## Options[​](#options "Direct link to Options") ### `contrast`[​](#contrast "Direct link to contrast") * Type `number` * Default `0.25` * Required `no` The higher the contrast, the darker the image and vice versa. This can help to find text in an image. It accepts values between `-1` and `1`. #### Example[​](#example "Direct link to Example") ``` await browser.ocrGetText({ contrast: 0.5 }); ``` ### `haystack`[​](#haystack "Direct link to haystack") * Type `number` * Required `WebdriverIO.Element | ChainablePromiseElement | Rectangle` This is the search area in the screen where the OCR needs to look for text. This can be an element or a rectangle containing `x`, `y`, `width` and `height` #### Example[​](#example-1 "Direct link to Example") ``` await browser.ocrGetText({ haystack: $("elementSelector") }); // OR await browser.ocrGetText({ haystack: await $("elementSelector") }); // OR await browser.ocrGetText({ haystack: { x: 10, y: 50, width: 300, height: 75, }, }); ``` ### `language`[​](#language "Direct link to language") * Type `string` * Default `eng` * Required `No` The language that Tesseract will recognize. More info can be found [here](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions) and the supported languages can be found [here](https://github.com/webdriverio/visual-testing/blob/main/packages/ocr-service/src/utils/constants.ts). #### Example[​](#example-2 "Direct link to Example") ``` import { SUPPORTED_OCR_LANGUAGES } from "@wdio/ocr-service"; await browser.ocrGetText({ // Use Dutch as a language language: SUPPORTED_OCR_LANGUAGES.DUTCH, }); ``` --- Source: https://webdriver.io/docs/ocr-testing/ocr-set-value.md # ocrSetValue Send a sequence of key strokes to an element. It will: * automatically detect the element * put focus on the field by clicking on it * set the value in the field The command will search for the provided text and try to find a match based on Fuzzy Logic from [Fuse.js](https://fusejs.io/). This means that if you might provide a selector with a typo, or the found text might not be a 100% match it will still try to give you back an element. See the [logs](#logs) below. ## Usage[​](#usage "Direct link to Usage") ``` await brower.ocrSetValue({ text: "docs", value: "specfileretries", }); ``` ## Output[​](#output "Direct link to Output") ### Logs[​](#logs "Direct link to Logs") ``` [0-0] 2024-05-26T04:17:51.355Z INFO webdriver: COMMAND ocrSetValue() ...................... [0-0] 2024-05-26T04:17:52.356Z INFO @wdio/ocr-service:ocrGetElementPositionByText: We searched for the word "docs" and found one match "docs" with score "100%" ``` ## Options[​](#options "Direct link to Options") ### `text`[​](#text "Direct link to text") * Type `string` * Required `yes` The text you want to search for to click on. #### Example[​](#example "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", }); ``` ### `value`[​](#value "Direct link to value") * Type `string` * Required `yes` Value to be added. #### Example[​](#example-1 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", }); ``` ### `submitValue`[​](#submitvalue "Direct link to submitvalue") * Type `boolean` * Default `false` * Required `no` If the value also needs to be submitted into the input field. This means an "ENTER" will be send at the end of the string. #### Example[​](#example-2 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", submitValue: true, }); ``` ### `clickDuration`[​](#clickduration "Direct link to clickduration") * Type `number` * Default `500 milliseconds` * Required `no` This is the duration of the click. If you want you can also create a "long click" by increasing the time. #### Example[​](#example-3 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", clickDuration: 3000, // This is 3 seconds }); ``` ### `contrast`[​](#contrast "Direct link to contrast") * Type `number` * Default `0.25` * Required `no` The higher the contrast, the darker the image and vice versa. This can help to find text in an image. It accepts values between `-1` and `1`. #### Example[​](#example-4 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", contrast: 0.5, }); ``` ### `haystack`[​](#haystack "Direct link to haystack") * Type `number` * Required `WebdriverIO.Element | ChainablePromiseElement | Rectangle` This is the search area in the screen where the OCR needs to look for text. This can be an element or a rectangle containing `x`, `y`, `width` and `height` #### Example[​](#example-5 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", haystack: $("elementSelector"), }); // OR await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", haystack: await $("elementSelector"), }); // OR await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", haystack: { x: 10, y: 50, width: 300, height: 75, }, }); ``` ### `language`[​](#language "Direct link to language") * Type `string` * Default `eng` * Required `No` The language that Tesseract will recognize. More info can be found [here](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions) and the supported languages can be found [here](https://github.com/webdriverio/visual-testing/blob/main/packages/ocr-service/src/utils/constants.ts). #### Example[​](#example-6 "Direct link to Example") ``` import { SUPPORTED_OCR_LANGUAGES } from "@wdio/ocr-service"; await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", // Use Dutch as a language language: SUPPORTED_OCR_LANGUAGES.DUTCH, }); ``` ### `relativePosition`[​](#relativeposition "Direct link to relativeposition") * Type `object` * Required `no` You can click on the screen relative to the matching element. This can be done based on relative pixels `above`, `right`, `below` or `left` from the matching element note The following combinations are allowed * single properties * `above` + `left` or `above` + `right` * `below` + `left` or `below` + `right` The following combinations are **NOT** allowed * `above` plus `below` * `left` plus `right` #### `relativePosition.above`[​](#relativepositionabove "Direct link to relativepositionabove") * Type `number` * Required `no` Click x pixels `above` the matching element. ##### Example[​](#example-7 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", relativePosition: { above: 100, }, }); ``` #### `relativePosition.right`[​](#relativepositionright "Direct link to relativepositionright") * Type `number` * Required `no` Click x pixels `right` from the matching element. ##### Example[​](#example-8 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", relativePosition: { right: 100, }, }); ``` #### `relativePosition.below`[​](#relativepositionbelow "Direct link to relativepositionbelow") * Type `number` * Required `no` Click x pixels `below` the matching element. ##### Example[​](#example-9 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", relativePosition: { below: 100, }, }); ``` #### `relativePosition.left`[​](#relativepositionleft "Direct link to relativepositionleft") * Type `number` * Required `no` Click x pixels `left` from the matching element. ##### Example[​](#example-10 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", relativePosition: { left: 100, }, }); ``` ### `fuzzyFindOptions`[​](#fuzzyfindoptions "Direct link to fuzzyfindoptions") You can alter the fuzzy logic to find text with the following options. This might help find a better match #### `fuzzyFindOptions.distance`[​](#fuzzyfindoptionsdistance "Direct link to fuzzyfindoptionsdistance") * Type `number` * Default `100` * Required `no` Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match to be at the exact location specified. A distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8. ##### Example[​](#example-11 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", fuzzyFindOptions: { distance: 20, }, }); ``` #### `fuzzyFindOptions.location`[​](#fuzzyfindoptionslocation "Direct link to fuzzyfindoptionslocation") * Type `number` * Default `0` * Required `no` Determines approximately where in the text is the pattern expected to be found. ##### Example[​](#example-12 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", fuzzyFindOptions: { location: 20, }, }); ``` #### `fuzzyFindOptions.threshold`[​](#fuzzyfindoptionsthreshold "Direct link to fuzzyfindoptionsthreshold") * Type `number` * Default `0.6` * Required `no` At what point does the matching algorithm give up. A threshold of 0 requires a perfect match (of both letters and location), a threshold of 1.0 would match anything. ##### Example[​](#example-13 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", fuzzyFindOptions: { threshold: 0.8, }, }); ``` #### `fuzzyFindOptions.isCaseSensitive`[​](#fuzzyfindoptionsiscasesensitive "Direct link to fuzzyfindoptionsiscasesensitive") * Type `boolean` * Default `false` * Required `no` Whether the search should be case sensitive. ##### Example[​](#example-14 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", fuzzyFindOptions: { isCaseSensitive: true, }, }); ``` #### `fuzzyFindOptions.minMatchCharLength`[​](#fuzzyfindoptionsminmatchcharlength "Direct link to fuzzyfindoptionsminmatchcharlength") * Type `number` * Default `2` * Required `no` Only the matches whose length exceeds this value will be returned. (For instance, if you want to ignore single character matches in the result, set it to 2) ##### Example[​](#example-15 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", fuzzyFindOptions: { minMatchCharLength: 5, }, }); ``` #### `fuzzyFindOptions.findAllMatches`[​](#fuzzyfindoptionsfindallmatches "Direct link to fuzzyfindoptionsfindallmatches") * Type `number` * Default `false` * Required `no` When `true`, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string. ##### Example[​](#example-16 "Direct link to Example") ``` await browser.ocrSetValue({ text: "WebdriverIO", value: "The Value", fuzzyFindOptions: { findAllMatches: 100, }, }); ``` --- Source: https://webdriver.io/docs/ocr-testing/ocr-wait-for-text-displayed.md # ocrWaitForTextDisplayed Wait for a specific text to be displayed on the screen. ## Usage[​](#usage "Direct link to Usage") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", }); ``` ## Output[​](#output "Direct link to Output") ### Logs[​](#logs "Direct link to Logs") ``` [0-0] 2024-05-26T04:32:52.005Z INFO webdriver: COMMAND ocrWaitForTextDisplayed() ...................... # ocrWaitForTextDisplayed uses ocrGetElementPositionByText under the hood, that is why you see the command ocrGetElementPositionByText in the logs [0-0] 2024-05-26T04:32:52.735Z INFO @wdio/ocr-service:ocrGetElementPositionByText: Multiple matches were found based on the word "specFileRetries". The match "specFileRetries" with score "100%" will be used. ``` ## Options[​](#options "Direct link to Options") ### `text`[​](#text "Direct link to text") * Type `string` * Required `yes` The text you want to search for to click on. #### Example[​](#example "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries" }); ``` ### `timeout`[​](#timeout "Direct link to timeout") * Type `number` * Default `18000 (18 seconds)` * Required `no` Time in milliseconds. Be aware that the OCR process can take some time, so don't set it too low. #### Example[​](#example-1 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries" timeout: 25000 // wait for 25 seconds }); ``` ### `timeoutMsg`[​](#timeoutmsg "Direct link to timeoutmsg") * Type `string` * Default `Could not find the text "{selector}" within the requested time.` * Required `no` It overrides the default error message. #### Example[​](#example-2 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries" timeoutMsg: "My new timeout message." }); ``` ### `contrast`[​](#contrast "Direct link to contrast") * Type `number` * Default `0.25` * Required `no` The higher the contrast, the darker the image and vice versa. This can help to find text in an image. It accepts values between `-1` and `1`. #### Example[​](#example-3 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", contrast: 0.5, }); ``` ### `haystack`[​](#haystack "Direct link to haystack") * Type `number` * Required `WebdriverIO.Element | ChainablePromiseElement | Rectangle` This is the search area in the screen where the OCR needs to look for text. This can be an element or a rectangle containing `x`, `y`, `width` and `height` #### Example[​](#example-4 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", haystack: $("elementSelector"), }); // OR await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", haystack: await $("elementSelector"), }); // OR await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", haystack: { x: 10, y: 50, width: 300, height: 75, }, }); ``` ### `language`[​](#language "Direct link to language") * Type `string` * Default `eng` * Required `No` The language that Tesseract will recognize. More info can be found [here](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions) and the supported languages can be found [here](https://github.com/webdriverio/visual-testing/blob/main/packages/ocr-service/src/utils/constants.ts). #### Example[​](#example-5 "Direct link to Example") ``` import { SUPPORTED_OCR_LANGUAGES } from "@wdio/ocr-service"; await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", // Use Dutch as a language language: SUPPORTED_OCR_LANGUAGES.DUTCH, }); ``` ### `fuzzyFindOptions`[​](#fuzzyfindoptions "Direct link to fuzzyfindoptions") You can alter the fuzzy logic to find text with the following options. This might help find a better match #### `fuzzyFindOptions.distance`[​](#fuzzyfindoptionsdistance "Direct link to fuzzyfindoptionsdistance") * Type `number` * Default `100` * Required `no` Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match to be at the exact location specified. A distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8. ##### Example[​](#example-6 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", fuzzyFindOptions: { distance: 20, }, }); ``` #### `fuzzyFindOptions.location`[​](#fuzzyfindoptionslocation "Direct link to fuzzyfindoptionslocation") * Type `number` * Default `0` * Required `no` Determines approximately where in the text is the pattern expected to be found. ##### Example[​](#example-7 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", fuzzyFindOptions: { location: 20, }, }); ``` #### `fuzzyFindOptions.threshold`[​](#fuzzyfindoptionsthreshold "Direct link to fuzzyfindoptionsthreshold") * Type `number` * Default `0.6` * Required `no` At what point does the matching algorithm give up. A threshold of 0 requires a perfect match (of both letters and location), a threshold of 1.0 would match anything. ##### Example[​](#example-8 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", fuzzyFindOptions: { threshold: 0.8, }, }); ``` #### `fuzzyFindOptions.isCaseSensitive`[​](#fuzzyfindoptionsiscasesensitive "Direct link to fuzzyfindoptionsiscasesensitive") * Type `boolean` * Default `false` * Required `no` Whether the search should be case sensitive. ##### Example[​](#example-9 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", fuzzyFindOptions: { isCaseSensitive: true, }, }); ``` #### `fuzzyFindOptions.minMatchCharLength`[​](#fuzzyfindoptionsminmatchcharlength "Direct link to fuzzyfindoptionsminmatchcharlength") * Type `number` * Default `2` * Required `no` Only the matches whose length exceeds this value will be returned. (For instance, if you want to ignore single character matches in the result, set it to 2) ##### Example[​](#example-10 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", fuzzyFindOptions: { minMatchCharLength: 5, }, }); ``` #### `fuzzyFindOptions.findAllMatches`[​](#fuzzyfindoptionsfindallmatches "Direct link to fuzzyfindoptionsfindallmatches") * Type `number` * Default `false` * Required `no` When `true`, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string. ##### Example[​](#example-11 "Direct link to Example") ``` await browser.ocrWaitForTextDisplayed({ text: "specFileRetries", fuzzyFindOptions: { findAllMatches: 100, }, }); ```