@visual-regression-tracker/agent-cypress

Native integration for Cypress with Visual Regression Tracker

Npm: https://www.npmjs.com/package/@visual-regression-tracker/agent-cypress

Installation

Add package

npm install @visual-regression-tracker/agent-cypress

Add command

<rootDir>/cypress/support/commands.js

import {
  addVrtTrackCommand,
  addVrtStartCommand,
  addVrtStopCommand,
  addVrtTrackBufferCommand,
  addVrtTrackBase64Command,
} from "@visual-regression-tracker/agent-cypress/dist/commands";

addVrtStartCommand();
addVrtStopCommand();
addVrtTrackCommand();
addVrtTrackBufferCommand();
addVrtTrackBase64Command();

Add plugin

<rootDir>/cypress/plugins/index.js

const {
  addVisualRegressionTrackerPlugin,
} = require("@visual-regression-tracker/agent-cypress/dist/plugin");

module.exports = (on, config) => {
  addVisualRegressionTrackerPlugin(on, config);
};

Configuration

Update cypress config

<rootDir>/cypress.json

{
  "env": {
    "visualRegressionTracker": {
      // URL where backend is running
      // Required
      "apiUrl": "http://localhost:4200",

      // Project name or ID
      // Required
      "project": "Default project",

      // User apiKey
      // Required
      "apiKey": "tXZVHX0EA4YQM1MGDD",

      // Current git branch
      // Required
      "branchName": "develop",

      // Branch with baseline
      // Optional - when not set, main branch from project settings is used
      "baselineBranchName": "release",

      // Log errors instead of throwing exceptions
      // Optional - default false
      "enableSoftAssert": true,

      // Unique ID related to one CI build
      // Optional - default null
      "ciBuildId": "SOME_UNIQUE_ID",
    }
  }
}

Or, as JSON config file vrt.json

Used only if not explicit config provided Is overriden if ENV variables are present

{
  "apiUrl": "http://localhost:4200",
  "project": "Default project",
  "apiKey": "tXZVHX0EA4YQM1MGDD",
  "ciBuildId": "commit_sha",
  "branchName": "develop",
  "enableSoftAssert": false
}

Or, as environment variables

Used only if not explicit config provided

VRT_APIURL="http://localhost:4200"
VRT_PROJECT="Default project"
VRT_APIKEY="tXZVHX0EA4YQM1MGDD"
VRT_CIBUILDID="commit_sha"
VRT_BRANCHNAME="develop"
VRT_BASELINEBRANCHNAME="release"
VRT_ENABLESOFTASSERT=true

Usage

Setup

cy.vrtStart();

Assert

cy.vrtTrack("Whole page with default params");

cy.get("#navbar").vrtTrack("Separate element with default params");

cy.vrtTrack(
  "Whole page with additional options",
  {
    viewport: "1920x1080",
    os: "MacOS",
    device: "Cloud agent",
    customTags: "Cloud, DarkTheme, Auth",
    diffTollerancePercent: 1,
    ignoreAreas: [{ x: 1, y: 2, width: 100, height: 200 }],
    retryLimit: 2,
    keepScreenshot: false, // Keep screenshot local copy, false by default
  },
  (err) => {
    console.log("Screenshot has diff with baseline", err);
    return true; // Skip failing test
  }
);

options (optional)

Allows to set options for taking screenshot. All options from screenshot command are also supported more details

Viewport is taken from Cypress.config(), if option is not set

Browser is taken from Cypress.browser.name

errorCallbak (optional)

Allows you to define a callback that receives the error for custom side-effects.

Also allows to override assertion policy. When callback returns true this acts similar to enableSoftAssertions option in config, but allows to enable soft assertion only for one specific screenshot.

Teadown

cy.vrtStop();

Examples

https://github.com/Visual-Regression-Tracker/examples-js