Install

npm i -D @wge/wg-testcafe-utils

Ensure the testcafe screenshots path is set (for canvas empty check) should be something like "-s screenshots"

Basic Usage

import {canvasIsEmpty} from 'wg-testcafe-utils'

// ...

test('Canvas is not empty', async t => {
    const isEmpty = await canvasIsEmpty(t, Selector('CANVAS_SELECTOR_PATH'));
    return t.expect(isEmpty).eql(false, 'canvas is empty');
});

getPlatform

Method is executed in the browser context, and returns object. Also, you can append this object into string, and it will be represented as OS--Browser instead of [Object object]

cosnt { os, browser, mobile, key } = await getPlatform(t);

getImagePath

Method returns absolute and relative paths to the tested image.

cosnt { absolute, relative } = await getImagePath(t, 'etalon', 'myImage');

Visual testing

Visual screenshots are saved to "visual" subdirectory inside the screenshots directory

• etalon - etalon screenshots, this directory should be stored in git
• work - the last run's screenshots
• diff - the last run's diff images

Testing is done in two separate phases: first etalon screenshots are generated and stored in git (a person should decide which of them are right), in the second phase work screenshots are created and are compared to appropriate etalon screenshots.

getting started

Create two scripts in package.json like

"visual-test": "testcafe chrome test-app/spec/*.js -s screenshots",
"visual-generate": "VIS_GENERATE=true testcafe chrome test-app/spec/*.js -s screenshots"

VIS_GENERATE - if set will generate screenshots without compare

VIS_GENERATE_NEW_ONLY - if set will generate screenshots only if they differ from existing ones. (files can be still marked as updated due to file permissions)

VIS_OS_NAME_OVERRIDE - override os name in getPlatform function

VIS_BROWSER_NAME_OVERRIDE - override browser name in getPlatform function

Inside test:

import { compareScreenshot } from "wg-testcafe-utils";

fixture `Visual compare`;

test('my test', async (t) => {
    await t.expect(await compareScreenshot(t, 'screenshot_name'))
        .contains({ match: true }))
})

compareScreenshot(t, name, compareParams)

• t - testcafe testController
• name - {String} screenshot name without extension (for "/" subdirectories will be created)
• compareParams - {Object}

  // defaults for compareParams
  {
      threshold: 0.1,           // How large percentage of pixels should be different for images to be considered different
      imageMatchOptions: {
          colorDistThreshold: 0.01,
          errColor: [255, 0, 255]
      },
      retry: 1                       // number of tryes if screenshots don't match
      etalonName: '',                     // Compare to other etalon screenshot
      element: undefined,                 // TestCafe selector to take screenshot from
      elementScreenshotOptions: undefined // options for TestCafe's t.takeElementScreenshot https://devexpress.github.io/testcafe/documentation/test-api/actions/take-screenshot.html#take-a-screenshot-of-a-page-element
  }

• returns

  {
      match, // true | false
      diff: {
          percentage, //how many pixels were considered mismatching
          count,      //how many pixels were considered mismatching
          isSameDimension,
          png,        //pngjs object with the diff image
      },
      paths: { etalon, work, diff }
  }

etalonName - on generate phase will not create etalon screenshot, but will create work and diff screenshots and try to compare with etalonName, so make sure that etalonName exist by that time.

compareRawImage(t, name, data, compareParams)

• t - testcafe testController
• name - {String} screenshot name without extension (for "/" subdirectories will be created)
• data - base64 encoded image data
• compareParams - {Object}

  // defaults for compareParams
  {
      threshold: 0.1,           // How large percentage of pixels should be different for images to be considered different
      imageMatchOptions: {
          colorDistThreshold: 0.01,
          errColor: [255, 0, 255]
      },
      etalonName: '',                     // Compare to other etalon screenshot
      element: undefined,                 // TestCafe selector to take screenshot from
      elementScreenshotOptions: undefined // options for TestCafe's t.takeElementScreenshot https://devexpress.github.io/testcafe/documentation/test-api/actions/take-screenshot.html#take-a-screenshot-of-a-page-element
  }

• returns

  {
      match, // true | false
      diff: {
          percentage, //how many pixels were considered mismatching
          count,      //how many pixels were considered mismatching
          isSameDimension,
          png,        //pngjs object with the diff image
      },
      paths: { etalon, work, diff }
  }

Advanced Usage

import { compareScreenshot, getPlatform } from "wg-testcafe-utils";

const visualCmp = async (t, name) => {
    const defaults = {
        threshold: 0.2
    };

    const res = await compareScreenshot(t, name, defaults);
    if (!res.match) {
        throw new Error(`Image "${name}" compare error: misMatchPercentage ${res.diff.misMatchPercentage}% (MAX ${defaults.threshold}%), sameDimensions: ${res.diff.isSameDimensions}`);
    }

    return res.match;
}

// approximate width, height of browser window
const visW = 600;
const visH = 600;

// needed for multibrowser test run for browser to be resized once
const browserResized = {};

fixture `Visual compare`
    .meta('vis', 'true')
    .beforeEach(async (t) => {
        const platform = await getPlatform(t);
        if (!browserResized[platform.key]) {
            // need for correct viewport setup once for browser
            await t.resizeWindow(visW, visH);
            await t.eval(() => window.location.reload(true));
            browserResized[platform.key] = true;
        }
    });

test('my test', async (t) => {
    await t.expect(await visualCmp(t, 'my_screenshot_name')).ok('Screenshot my_screenshot_name is not ok');
});