VisWiz.io Cypress Plugin

The official VisWiz.io Cypress plugin.

Welcome to the VisWiz.io Cypress plugin documentation.

Installation

Install the package:

$ npm install --save-dev viswiz-cypress

Then add it to your cypress/plugins/index.js (or the corresponding pluginsFile from your Cypress configuration):

module.exports = (on, config) => {
	require('viswiz-cypress')(on, config);
};

Configuration

The plugin requires a few options to be set, either via environment variables or with a configuration object.

Environment variables

We support popular CI services and some of the variables are detected automatically.

Environment variable	Purpose
VISWIZ_API_KEY	The VisWiz.io account API key
VISWIZ_PROJECT_ID	The VisWiz.io project ID
depending on CI	The branch name of the current build
depending on CI	The commit revision (SHA) of the current build
depending on CI*	The commit message of the current build

For the actual environment variables names for your CI, please refer to your CI's documentation.

Note: Not all CI systems expose an environment variable for the commit message, so the plugin uses a fallback variable: COMMIT_MESSAGE. If your CI system does not support such a variable, you will need to define this variable when you are running tests.

Configuration options

All these configuration options can be set via a configuration object when you initialize the plugin:

module.exports = (on, config) => {
	require('viswiz-cypress')(on, config, {
		apiKey: 'FILL-IN',
		branch: 'FILL-IN',
		name: 'FILL-IN',
		projectID: 'FILL-IN',
		revision: 'FILL-IN',
	});
};

Usage

Update your test files to capture a few screenshots of your application using cy.screenshot:

describe('my tests', () => {
	it('takes one screenshot', () => {
		cy.screenshot('first-screenshot');
	});

	it('takes another screenshot', () => {
		cy.screenshot('second-screenshot');
	});
});

That's all there is to it.

When all tests pass, the plugin creates a new VisWiz.io build and sends all screenshots for visual regression testing. A VisWiz.io report URL will be printed in the logs.

$ cypress run
  ...
  VisWiz: processing screenshots (1/2)
  VisWiz: processing screenshots (2/2)
  VisWiz: Build report will be available at: https://app.viswiz.io/projects/6SrRRmpuSpWDDBGGqjWSB9/build/vMUf2vUkaU5NuGsQqWz875/results

Changelog

The changelog can be found here: CHANGELOG.md.

Authors and license

Author: VisWiz.io.

MIT License, see the included LICENSE.md file.