cypress-looks-same

A plugin to Cypress for visual regression testing, based on looks-same.

Getting Started

Start by installing the NPM package:

yarn add --dev cypress-looks-same

In your cypress/plugins/index.js file, add:

const addLooksSamePlugin = require('cypress-looks-same/plugin');

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

In your cypress/support/index.js file, add:

import addLooksSameCommands from 'cypress-looks-same/commands';

addLooksSameCommands();

Then in your tests, you can do this:

describe("stuff", () => {
    specify("element visuals", () => {
        cy.get('.my-element')
            .shouldLookSameAs('test image');
    });
});

The first time this runs, a cypress/snapshots/TestFile.spec.js/element visuals - test image.png file will be created. The next time it runs, another screenshot will be taken and compared to the existing snapshot.

If the screenshots look different, the assertion will fail and actual and diff files will be created next to the snapshot.

If the screenshots look the same, the assertion passes, and any actual and diff files are cleaned up. The original element is returned for chaining.

You can compare screenshots of the whole screen by not specifying a subject:

cy.shouldLookSameAs('whole screen');

Configuration

You can pass an options object in to shouldLookSameAs to customise the screenshot and image comparison:

cy.shouldLookSameAs('image', { /* ...options */ });

You can specify any of the options made available by the screenshot command or by looks-same.

Defaults

Rather than specifying the same options everywhere, you can set defaults by passing them in to the addLooksSameCommands() call in your support file.

Environment variables

Two environment variables are made available:

Extras

There is also a compareWithImageSnapshot command, which does the same thing as shouldLookSameAs, but returns the comparison results instead of asserting on them. The results have the following properties:

Caveats

To make shouldLookSameAs behave like a normal assertion, I've had to use undocumented Cypress features. Be aware that this plugin could stop working after any update to Cypress.