[![TypeScript version][ts-badge]][typescript-4-2]
[![Node.js version][nodejs-badge]][nodejs]

## Usage

### Take a single screenshot and validate it:

````js
import {​​​​​​​ createScreenshotsComparer, compareScreenshot }​​​​​​​ from 'devextreme-screenshot-comparer';
test('Full size pager', async (t) => {​​​​​​​​
    await t
        .expect(await compareScreenshot(t, 'pager-full-allpages.png'))
}​​
````
### Take and validate several screenshots without failing a test:
````js
// create comparer for collect results
const {​​​ takeScreenshot, compareResults }​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​ = createScreenshotsComparer(t);
await t
    ... // perform test actions and take the first screenshot
    .expect(await takeScreenshot('pager-1.png', pagerElement))
    ...// perform other actions and take the second one
    .expect(await takeScreenshot('pager-2.png', pagerElement))
    // check the result and show errors
    .expect(compareResults.isValid())
    .ok(compareResults.errorMessages());
````
## Files and folders structure

```
 .
 +- testing -- default root path
    +- tests
    |  +- etalons
    |  |  +- pager-screehshot1.png
    |  +- pager.ts -- testfile with takeScreenshot(t, 'screehshot1');
    +- screenshots
    |  +- pager-screehshot1.png
    |  +- pager-screehshot1.png
    |  +- pager-screehshot1_mask.png
    |  +- pager-screehshot1_text_mask.png
    +- artifacts
       +- compared-screenshots
       |  +- pager-screehshot1.png
       |  +- pager-screehshot1_etalon.png
       |  +- pager-screehshot1_mask.png
       +- pager-screehshot1 - generated only when `debug` mode enabled;
          +- ... -- step by step image transformations used for comparison;
          +- log.txt -- comparison logs 
         
```
## Configuration

 Default config:
````js
const screenshotComparerDefault = {
  path: './testing',
  screenshotsRelativePath: '/screenshots', 
  destinationRelativePath: '/artifacts/compared-screenshots',
  generatePatch: false,
  highlightColor: { r: 0xff, g: 0, b: 0xff },
  maskRadius: 5,
  attempts: 2,
  attemptTimeout: 500,
  looksSameComparisonOptions: {
    strict: false,
    tolerance: 5,
    ignoreAntialiasing: true,
    antialiasingTolerance: 5,
    ignoreCaret: true,
  },
  textComparisonOptions: {
    strict: false,
    ignoreAntialiasing: true,
    ignoreCaret: true,
  },
  enableTextMask: true,
  textMaskRadius: 2,
  textDiffTreshold: 0.05,
};
````

* Common options:
  * path - path to the screenshots root folder;
  * screenshotsRelativePath - a relative path for storing screenshots to compare (base part is the `path` property)
  * destinationRelativePath - a relative path for storing comparison results (base part is the `path` property)
  * generatePatch - save updated screenshots to the 'artifacts/screenshots' subfolder, keep etalon screenshots' tree hierarchy;
  * maskRadius - radius of ignored pixels when using a mask file;
  * attemps - count of attempts to get a valid screenshot;
  * attempTimeout - timeout between attemps;
  * ignoreSizeDifference - ignore the size difference between compared images
  * looksSameComparisonOptions - see [look-same] for more details;
* Text comparison options:
   * enableTextMask - if enabled, comparer generates a mask over text glyphs. Comparison inside the mask area ignores subpixel diffs;
   * textMaskRadius - radius of the mask area around text glyph;
   * textDiffTreshold - a value between `[0..1]`. `0` means that no diff allowed betwen original and current text glyphes, `1` ignores differences within the mask area at all;
   * textComparisonOptions - see [look-same] for more details;

You can override the default configuration using `.testcaferc.json`. For example, override the path:
````json
{
  "screenshots-comparer": {
    "path": "./testing/testcafe"
  }
}
````
or for any takeScreenshot call:
````js
.expect(await takeScreenshot('', null, { looksSameComparisonOptions: { tolerance: 30 } }));
````
 
## License

DevExtreme Screenshot Comparer is released as MIT-licensed

[ts-badge]: https://img.shields.io/badge/TypeScript-4.2-blue.svg
[nodejs-badge]: https://img.shields.io/badge/Node.js->=%2014.16-blue.svg
[nodejs]: https://nodejs.org/dist/latest-v14.x/docs/api/
[typescript]: https://www.typescriptlang.org/
[typescript-4-2]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-2.html
[jest]: https://facebook.github.io/jest/
[eslint]: https://github.com/eslint/eslint
[gh-actions]: https://github.com/features/actions
[look-same]:https://www.npmjs.com/package/looks-same