@cake-hub/cake-screenshot_diffs/README.MD

A CAKE Screenshot diffing tool that includes a setup to comapre two given resources by screenshots taken from the available pages.

# Cake - Screenshot diffs

## Who we are

CAKE is a design system and frontend framework for the whole "[Schwarz Gruppe](https://jobs.schwarz/)". We offer some tools, guidelines and systems to develop faster products that match the CI.

Check out our project website <https://cake.schwarz>.

## What I am

A **CAKE Screenshot diffing tool** that includes a setup to comapre two given resources by screenshots taken from the available pages.

## Getting started

Install our package by running:

```
npm install --save @cake-hub/cake-screenshot_diffs
```

Afterwards the command `cake-screenshot_diffs` will be made avaiable in the context of your installation path.
So to compare two resources you only have to run the command:

```
npx cake-screenshot_diffs
```

This command assumes, that you have set up a valid configration file called `./cake-screenshot.yml` in the root of your project folder.
But you could also provide another location for your configuration file like in the following example:

```
npx cake-screenshot_diffs --config ./test/other-location.yml
```

## Commands

* `npx cake-screenshot_diffs [--config|--configurationPath|--version|--help]`

Run `npx cake-screenshot_diffs --help` to get a list of all command line options.

## Configuration file

The configuration file is required and it's default location will be `./cake-screenshot.yml`. It's structure looks like the following example:

```yml
referenceUrl: https://your.production.website/
url: https://your.test.environment/
reportPath: ./backstop_report
viewports:
- label: XS
  width: 320
  height: 568
- label: SM
  width: 600
  height: 960
- label: MD
  width: 960
  height: 600
- label: LG
  width: 1280
  height: 1024
scenarios:
  delay: 3000
  misMatchThreshold: 0.02
  selectors:
  - document
crawlers:
  maxDepthToFollow: 0
  maxConcurrentConnections: 10
  fileExtensions:
    - .html
  assetFileExtensions:
    - .png
    - .jpg
    - .jpeg
    - .gif
    - .mp4
    - .svg
backstop:
  asyncCaptureLimit: 10
  asyncCompareLimit: 20
  …
```

Most of the settings are optional but there are also mandatory properties as described in the list below:

* `referenceUrl` (`required`) – The reference URL with which the screenshots are compared
* `url` (`required`) – The URL which should be checked
* `reportPath` (`optional`) – The folder to which the report should be saved
* `viewports` (`required`) – a list of viewports that should be checked
  * `label` – The label of the screenshots and viewport
  * `width` – The width for the viewport
  * `height` – The height for the viewport
* `scenarios` (`optional`) – Settings for all of the scenarios. Please check out the [BackstopJs documentation](https://github.com/garris/BackstopJS#advanced-scenarios) for available settings
* `crawlers` (`optional`) – Settings for the crawler before screenshots are taken
  * `maxDepthToFollow` – The depth of links to follow
  * `maxConcurrentConnections` – Maximum of links to follow at once
  * `fileExtensions` – A list of url/file extensions that should be checked. If this list is empty, all links will be followed!
  * `assetFileExtensions` – A list of url/file extensions that should not be checked. If this property is omitted, we apply the default settings from the example above!
* `backstop` (`optional`) – Settings for [BackstopJS](https://github.com/garris/BackstopJS) comparison.

## Contact

You have questions or need help? Feel free to mail us <cake@lidl.com>