@visual-regression-tracker/agent-cypress 5.8.0 → 5.9.0

package/README.md

@@ -1,201 +1,175 @@
-# Native integration for [Cypress](https://www.cypress.io/) with [Visual Regression Tracker](https://github.com/Visual-Regression-Tracker/Visual-Regression-Tracker)
+# Cypress agent for [Visual Regression Tracker](https://github.com/Visual-Regression-Tracker/Visual-Regression-Tracker)
 
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/4ebb8d37b8f943548e992a7d063ac998)](https://www.codacy.com/gh/Visual-Regression-Tracker/agent-cypress?utm_source=github.com&utm_medium=referral&utm_content=Visual-Regression-Tracker/agent-cypress&utm_campaign=Badge_Grade)
+[![npm](https://img.shields.io/npm/v/@visual-regression-tracker/agent-cypress)](https://www.npmjs.com/package/@visual-regression-tracker/agent-cypress)
 
-Npm: https://www.npmjs.com/package/@visual-regression-tracker/agent-cypress
+Adds `cy.vrtStart()`, `cy.vrtTrack()` and `cy.vrtStop()` to [Cypress](https://www.cypress.io) tests. The agent is built on [sdk-js](https://github.com/Visual-Regression-Tracker/sdk-js).
 
-## Installation
+## Requirements
 
-Please note that the minimum supported Cypress version is [`12.17.1`, released in 10th July 2023](https://docs.cypress.io/guides/references/changelog#12-17-1).
+- Cypress 12.17.1 or later
+- Node.js 18 or later
+- Visual Regression Tracker server 5.0.8 or later; 6 is recommended
 
-### Add package
+## Install
 
-`npm install @visual-regression-tracker/agent-cypress`
-
-### Add commands
-
-`<rootDir>/cypress/support/e2e.js` or `<rootDir>/cypress/support/component.js`
-
-All available commands:
-
-```js
-import {
-  addVrtCommands,
-} from "@visual-regression-tracker/agent-cypress";
-
-addVrtCommands();
-```
-
-or one by one:
-
-```js
-import {
-  addVrtTrackCommand,
-  addVrtStartCommand,
-  addVrtStopCommand,
-  addVrtTrackBufferCommand,
-  addVrtTrackBase64Command,
-} from "@visual-regression-tracker/agent-cypress";
-
-addVrtStartCommand();
-addVrtStopCommand();
-addVrtTrackCommand();
-addVrtTrackBufferCommand();
-addVrtTrackBase64Command();
+```sh
+npm install --save-dev @visual-regression-tracker/agent-cypress
 ```
 
-### Add plugin
-
-`<rootDir>/cypress.config.js`
+Register the plugin in `cypress.config.js` (under `component` for component tests):
 
 ```js
-import { defineConfig } from 'cypress';
+import { defineConfig } from "cypress";
 import { addVisualRegressionTrackerPlugin } from "@visual-regression-tracker/agent-cypress";
 
 export default defineConfig({
-  // e2e or component, depending of testing style
   e2e: {
     setupNodeEvents(on, config) {
       addVisualRegressionTrackerPlugin(on, config);
-    }
-  }
+    },
+  },
 });
 ```
 
-### Configuration
+Add the commands in `cypress/support/e2e.js` (or `component.js`):
+
+```js
+import { addVrtCommands } from "@visual-regression-tracker/agent-cypress";
+
+addVrtCommands();
+```
 
-#### Update Cypress config
+To add only some of them, use `addVrtStartCommand`, `addVrtStopCommand`, `addVrtTrackCommand`, `addVrtTrackBufferCommand` and `addVrtTrackBase64Command`.
 
-`<rootDir>/cypress.config.js`
+## Configuration
+
+| Option | Environment variable | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `apiUrl` | `VRT_APIURL` | yes | | URL of the server API, e.g. `http://localhost:4200` |
+| `apiKey` | `VRT_APIKEY` | yes | | API key of a user with access to the project |
+| `project` | `VRT_PROJECT` | yes | | Project name or ID |
+| `branchName` | `VRT_BRANCHNAME` | yes | | Current git branch |
+| `sourceBranch` | `VRT_SOURCEBRANCH` | no | project's main branch | Branch to take baselines from while `branchName` has none of its own |
+| `ciBuildId` | `VRT_CIBUILDID` | no | | ID of one CI build; machines with the same ID share a build |
+| `enableSoftAssert` | `VRT_ENABLESOFTASSERT` | no | `false` | Log failed comparisons instead of failing the test |
+
+Set the options under `env.visualRegressionTracker` in the Cypress config:
 
 ```js
 export default defineConfig({
-
   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 to take baselines from instead of the project's main branch
-      // Optional - when not set, main branch from project settings is used
-      // Also read from VRT_SOURCEBRANCH when not set here
-      "sourceBranch": "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",
-    }
-  }
+    visualRegressionTracker: {
+      apiUrl: "http://localhost:4200",
+      apiKey: "tXZVHX0EA4YQM1MGDD",
+      project: "Default project",
+      branchName: "develop",
+    },
+  },
 });
 ```
 
-#### Or, as JSON config file `vrt.json`
-
-_Used only if not explicit config provided_
-_Is overriden if ENV variables are present_
+If `visualRegressionTracker` is not set, the options are read from `vrt.json` in the working directory, with the same keys:
 
 ```json
 {
   "apiUrl": "http://localhost:4200",
-  "project": "Default project",
   "apiKey": "tXZVHX0EA4YQM1MGDD",
-  "ciBuildId": "commit_sha",
+  "project": "Default project",
   "branchName": "develop",
   "sourceBranch": "release",
+  "ciBuildId": "commit_sha",
   "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_SOURCEBRANCH="release"
-VRT_ENABLESOFTASSERT=true
-```
+Environment variables override `vrt.json` key by key. When `visualRegressionTracker` is set, only `VRT_SOURCEBRANCH` is read from the environment.
 
-`sourceBranch` replaces `baselineBranchName` (`VRT_BASELINEBRANCHNAME`), which
-the server never read. The old name still works as an alias and logs a
-deprecation warning; like the other `VRT_*` variables, `VRT_BASELINEBRANCHNAME`
-is read only when `visualRegressionTracker` is not set in the Cypress config.
+`baselineBranchName` (`VRT_BASELINEBRANCHNAME`) is a deprecated alias of `sourceBranch`. It still works and logs a warning once.
 
 ## Usage
 
-### Setup
-
 ```js
-cy.vrtStart();
-```
-
-### Assert
+before(() => cy.vrtStart());
+after(() => cy.vrtStop());
 
-```js
-cy.vrtTrack("Whole page with default params");
+it("home page", () => {
+  cy.visit("/");
 
-cy.get("#navbar").vrtTrack("Separate element with default params");
+  cy.vrtTrack("Home page");
 
-cy.vrtTrack(
-  "Whole page with additional options",
-  {
-    viewport: "1920x1080",
-    os: "MacOS",
-    device: "Cloud agent",
-    customTags: "Cloud, DarkTheme, Auth",
+  cy.get("#navbar").vrtTrack("Navbar", {
+    os: "linux",
+    device: "desktop",
+    customTags: "smoke,dark",
+    comment: "Logged out",
     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
-  }
-);
+    keepScreenshot: false,
+  });
+});
 ```
 
-##### options (optional)
+`cy.vrtTrack(name, options, errorCallback)` takes a screenshot of the page, or of the element it is chained on, and uploads it as multipart. Every option is optional:
+
+| Option | Description |
+| --- | --- |
+| `os`, `device`, `customTags` | Tell baselines of the same name apart |
+| `viewport` | Defaults to `viewportWidth`x`viewportHeight` times the pixel ratio |
+| `diffTollerancePercent` | Allowed difference, in percent of all pixels (the spelling is the API's) |
+| `comment` | Shown with the test run |
+| `ignoreAreas` | `[{ x, y, width, height }]` in pixels, left out of the comparison |
+| `retryLimit` | Retries while the result is `unresolved`, default 2 |
+| `keepScreenshot` | Keep the local screenshot file, default `false` |
+| any [`cy.screenshot()` option](https://docs.cypress.io/api/commands/screenshot#Arguments) | Passed to the screenshot |
 
-Allows to set options for taking screenshot. All `options` from `screenshot` command are also supported [more details](https://docs.cypress.io/api/commands/screenshot.html#Arguments)
+The browser is taken from `Cypress.browser.name`.
 
-Viewport is taken from `Cypress.config()`, if option is not set
+`cy.vrtTrackBuffer(name, buffer, options)` and `cy.vrtTrackBase64(name, base64, options)` track an image you already have.
 
-Browser is taken from `Cypress.browser.name`
+## Results and statuses
 
-##### errorCallbak (optional)
+| Status | Outcome |
+| --- | --- |
+| `new` | No baseline yet: fails the test, or logs with `enableSoftAssert` |
+| `unresolved` | Differs from the baseline: fails the test, or logs with `enableSoftAssert` |
+| `ok`, `approved`, `autoApproved` | Passes |
+| `failed` | A reviewer rejected it: passes with a warning |
+| anything else | Passes with a warning |
 
-Allows you to define a callback that receives the error for custom side-effects.
+Logs and warnings appear in the terminal that runs Cypress, not in the browser.
 
-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.
+## Errors
 
-### Teadown
+A failed comparison or request fails the test with the server's message. Use `errorCallback` to handle it for one screenshot:
 
 ```js
-cy.vrtStop();
+cy.vrtTrack("Home page", {}, (err) => {
+  cy.log(err);
+  return true; // true: do not fail the test
+});
 ```
 
+Request errors name the HTTP status and add a hint for common causes, such as a wrong `apiKey` (401) or an image over the server's limits (413, 422). See [sdk-js](https://github.com/Visual-Regression-Tracker/sdk-js#errors).
+
 ## Examples
 
-https://github.com/Visual-Regression-Tracker/examples-js
+[examples-js](https://github.com/Visual-Regression-Tracker/examples-js)
+
+## Releasing
+
+Every push to `master` runs [semantic-release](https://semantic-release.gitbook.io). It reads the [Conventional Commits](https://www.conventionalcommits.org) since the last `v*` tag:
+
+| Commit | Release |
+| --- | --- |
+| `fix:` | patch |
+| `feat:` | minor |
+| `feat!:` or a `BREAKING CHANGE:` footer | major |
+| `chore:`, `ci:`, `docs:`, `test:` | none |
+
+It then publishes to npm through trusted publishing with provenance, tags `vX.Y.Z`, and writes the GitHub release.
+The `version` field in `package.json` is a placeholder. The released version lives in the tags and on npm.
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/types.d.ts

@@ -13,6 +13,7 @@ declare namespace Cypress {
          *       os: "MacOS",
          *       device: "Cloud agent",
          *       customTags: "Cloud, DarkTheme, Auth",
+         *       comment: "Logged out",
          *       diffTollerancePercent: 1.23,
          *       ignoreAreas: [
          *         {x: 1, y: 2, width: 100, height: 200}
@@ -40,6 +41,7 @@ declare namespace Cypress {
         os?: string;
         device?: string;
         customTags?: string;
+        comment?: string;
         diffTollerancePercent?: number;
         ignoreAreas?: IgnoreArea[];
         retryLimit?: number;

package/dist/utils.d.ts

@@ -23,6 +23,7 @@ export declare const toTestRunDto: ({ name, pixelRatio, options, }: {
     os: any;
     device: any;
     customTags: any;
+    comment: any;
     diffTollerancePercent: any;
     ignoreAreas: any;
     keepScreenshot: any;

package/dist/utils.js

@@ -37,6 +37,7 @@ const toTestRunDto = ({ name, pixelRatio = 1, options, }) => {
         os: options === null || options === void 0 ? void 0 : options.os,
         device: options === null || options === void 0 ? void 0 : options.device,
         customTags: options === null || options === void 0 ? void 0 : options.customTags,
+        comment: options === null || options === void 0 ? void 0 : options.comment,
         diffTollerancePercent: options === null || options === void 0 ? void 0 : options.diffTollerancePercent,
         ignoreAreas: options === null || options === void 0 ? void 0 : options.ignoreAreas,
         // next two properties actually do not belong to TestRunDto and ideally should be removed from this object

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@visual-regression-tracker/agent-cypress",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Visual Regression Tracker integration plugin for Cypress",
   "main": "dist/index.js",
   "types": "dist/",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "jest",
@@ -28,15 +31,14 @@
     "node": ">=16.16.0"
   },
   "dependencies": {
-    "@visual-regression-tracker/sdk-js": "^5.8.0"
+    "@visual-regression-tracker/sdk-js": "^5.8.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.5.2",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.20.5",
-    "cypress": "^16.2.0",
+    "cypress": "^16.2.1",
     "jest": "^30.5.2",
-    "semantic-release": "^25.0.9",
     "ts-jest": "^29.4.15",
     "typescript": "^6.0.3"
   },
@@ -45,5 +47,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "overrides": {
+    "glob": "^14.0.2",
+    "minimatch": "^11.0.1"
+  },
+  "release": {
+    "preset": "conventionalcommits"
   }
 }

package/.github/dependabot.yml

@@ -1,42 +0,0 @@
-version: 2
-updates:
-- package-ecosystem: npm
-  directory: "/"
-  schedule:
-    interval: daily
-  open-pull-requests-limit: 2
-  ignore:
-  - dependency-name: "@types/node"
-    versions:
-    - 14.14.22
-    - 14.14.24
-    - 14.14.25
-    - 14.14.26
-    - 14.14.28
-    - 14.14.30
-    - 14.14.31
-    - 14.14.33
-    - 14.14.34
-    - 14.14.35
-    - 14.14.36
-    - 14.14.37
-    - 14.14.39
-    - 14.14.41
-    - 15.0.0
-  - dependency-name: ssri
-    versions:
-    - 6.0.2
-  - dependency-name: y18n
-    versions:
-    - 4.0.1
-    - 4.0.2
-    - 4.0.3
-  - dependency-name: semantic-release
-    versions:
-    - 17.4.2
-  - dependency-name: cypress
-    versions:
-    - 6.3.0
-    - 6.4.0
-    - 6.5.0
-    - 6.6.0

package/.github/workflows/ci.yml

@@ -1,26 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [master]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v5
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v5
-        with:
-          node-version: 22
-
-      - name: Install npm dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Unit tests
-        run: npm test

package/.github/workflows/release.yml

@@ -1,37 +0,0 @@
-name: Release
-on:
-  push:
-    branches:
-      - master
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write # to publish a GitHub release
-      issues: write # to comment on released issues
-      pull-requests: write # to comment on released pull requests
-      id-token: write # to publish to npm with trusted publishing (OIDC) and provenance
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v5
-        with:
-          node-version: 22
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npx semantic-release

package/cypress.config.ts

@@ -1,30 +0,0 @@
-import { defineConfig } from 'cypress';
-import { addVisualRegressionTrackerPlugin } from "./lib/plugin";
-
-/**
- * @see https://docs.cypress.io/guides/references/configuration
- */
-export default defineConfig({
-    e2e: {
-        baseUrl: "https://example.cypress.io",
-        specPattern: 'cypress/integration/*.spec.ts',
-
-        setupNodeEvents(on, config) {
-            // `on` is used to hook into various events Cypress emits
-            // `config` is the resolved Cypress config
-            addVisualRegressionTrackerPlugin(on, config);
-        },
-    },
-    video: false,
-    screenshotOnRunFailure: false,
-    retries: 0,
-    env: {
-        "visualRegressionTracker": {
-          "apiUrl": "http://localhost:4200",
-          "apiKey": "5H90NFWM6BMWWDMWKG8T11DWW22Y",
-          "project": "fcf9ab05-4bed-40d6-a033-c178948c9897",
-          "branchName": "master",
-          "enableSoftAssert": false
-        }
-    }
-});