puppeteer-screenshot-tester: A JavaScript repository from burnpiro

puppeteer-screenshot-tester

Small library that allows us to compare screenshots generated by puppeteer in our tests.

Installation

To use Puppeteer Screenshot Tester in your project, run:

yarn add --dev puppeteer-screenshot-tester

npm install --save-dev puppeteer-screenshot-tester

Usage

Require the puppeteer-screenshot-tester library:

const ScreenshotTester = require('puppeteer-screenshot-tester')

Initialize Screenshot Tester

const tester = await ScreenshotTester()

Optional arguments:

const tester = await ScreenshotTester(
  [threshold = 0][, includeAA = false[, ignoreColors = false[, matchingBox = { ignoreRectangles = [], includeRectangle = [] } [, errorSettings = Object [, outputSettings = Object]]]]]
)

threshold <[number]> A threshold value <0,1> default set to 0, max ratio of difference between images
includeAA <[boolean]> Should include anti aliasing?
ignoreColors <[boolean]> Should ignore colors?
matchingBox <[Object]> Restrict what should be compared
matchingBox.ignoreRectangles <[Array<Array[x, y, width, height]>]> Should ignore rectangles? example: [[325,170,100,40], [10,10,200,200]], X and Y should be the coordinates of the top-left corner
matchingBox.includeRectangle <[Array<Array[x, y, width, height]>]> Compare only part of screen? example: [[325,170,100,40], [10,10,200,200]], X and Y should be the coordinates of the top-left corner
errorSettings <[Object]> change how to display errors (errorType: flat | movement | flatDifferenceIntensity | movementDifferenceIntensity | diffOnly):
```
{
  errorColor: {
    red: 255,
    green: 0,
    blue: 255
  },
  errorType: 'flat',
  transparency: 0.7
}
```

outputSettings <[Object]> change the output image settings:

{
  forceExt: 'jpeg' | 'png' | 'webp' | null,
  compressionLevel: 8 // 0-9 for .png, 0-100 otherwise
  overrides: {} // valid sharp options (see bellow)
}

returns: <[function]> resolves to function

overrides:

You can override options passed to sharp image processor. Just paste the overrides object that corresponds with sharp options:

.png Options
.webp Options
.jpeg/jpg Options

Run the test

const result = await tester(page)

Required arguments:

page <[BrowserPage]> BrowserPage returned by puppeteer when calling puppeteer.launch().newPage()

Optional arguments:

const result = await tester(page[, name = 'test'[, screenshotOptions = {}]])

name <[string]> name of created screenshot 'test' by default
screenshotOptions <[Object]> options passed to Puppeteer's screenshot method See the Puppeteer documentation for more info, plus the following keys:
- saveNewImageOnError: <[boolean]> saves the undiffed new image on error as ${saveFolder}/${name}-new${ext}
- overwriteImageOnChange: <[boolean]> overwrites the reference image (${saveFolder}/${name}${ext}) on error / change

Returns

<[boolean]> true if images are the same or there is no image to compare (first run)

Examples

const puppeteer = require('puppeteer')
const ScreenshotTester = require('puppeteer-screenshot-tester')

describe('google test', () => {
  let originalTimeout

  // extend default interval to 10s because some image processing might take some time
  // we can do it beforeEach or once per test suite it's up to you
  // if you're running that on fast computer/server probably won't need to do that
  beforeEach(function() {
    originalTimeout = jasmine.DEFAULT_TIMEOUT_INTERVAL
    jasmine.DEFAULT_TIMEOUT_INTERVAL = 10000
  })

  // set default interval timeout for jasmine
  afterEach(function() {
    jasmine.DEFAULT_TIMEOUT_INTERVAL = originalTimeout
  })

  it(`check if google exists`, async () => {
    // create ScreenshotTester with optional config
    const tester = await ScreenshotTester(0.8, false, false, [], {
      transparency: 0.5
    }, { compressionLevel: 8 })

    // setting up puppeteer
    const browser = await puppeteer.launch()
    const page = await browser.newPage()
    await page.setViewport({width: 1920, height: 1080})
    await page.goto('https://www.google.com', { waitUntil: 'networkidle0' })
    await page.type('input[title="Search"]', 'Hello', { delay: 100 })

    // call our tester with browser page returned by puppeteer browser
    // second parameter is optional it's just a test name if provide that's filename
    const result = await tester(page, 'test2', {
      fullPage: true,
    })
    await browser.close()

    // make assertion result is always boolean
    expect(result).toBe(true)
  })
})

Ignoring Rectangles and Including rectangles

const tester = await ScreenshotTester(
    0.1, // threshold
    false, // anti-aliasing
    false, // ignore colors
    { 
      ignoreRectangles: [[650, 300, 700, 200]], 
      includeRectangles: [[300, 200, 1100, 1100]]
    }, // rectangles 
    {
       transparency: 0.5
    }
)