viz v3.0.1

Viz

Visual regression testing framework. Works with all web frameworks.

Quick start

Install:

npm i -D viz

Configure Babel in your configuration file, e.g.

{
    "babel": {
        "presets": [
            "@babel/preset-env",
            [
                "@babel/preset-react",
                {
                    "runtime": "automatic"
                }
            ],
            "@babel/preset-typescript"
        ]
    }
}

Create some tests using TypeScript (.viz.tsx) or JavaScript (.viz.js or .viz.jsx):

// my-component.viz.tsx

import {render, unmountComponentAtNode} from 'react-dom'
import {afterEach, beforeEach, click, describe, hover, test} from 'viz'
import MyComponent from './my-component'

describe('my-component', () => {
    beforeEach(async () => {
        // Setup before each my-component test...
    })

    afterEach(async (target) => {
        // Clean up after each my-component test
        unmountComponentAtNode(target)
    })

    test('basic', async target => {
        // Asynchronously render inside the target DOM node
        await new Promise<void>(resolve => {
            render(
                <MyComponent />,
                target,
                resolve
            )
        })

        // Return the DOM node for Viz to screenshot
        return target.firstChild
    })

    test('disabled', async target => {
        await new Promise<void>(resolve => {
            render(
                <MyComponent disabled/>,
                target,
                resolve
            )
        })

        // Return the DOM node for Viz to screenshot
        return target.firstChild

        // Override the screenshot viewports specified in describe()
    }, [[320, 568], [1024, 768]])

    test('focus', async target => {
        await new Promise<void>(resolve => {
            render(
                <MyComponent />,
                target,
                async () => {
                    // Trigger focus state
                    await click('.MyComponent')
                    resolve()
                }
            )
        })
    })

    test('hover', async target => {
        await new Promise<void>(resolve => {
            render(
                <MyComponent />,
                target,
                async () => {
                    // Trigger hover state
                    await hover('.MyComponent')
                    resolve()
                }
            )
        })
    })

    // Optional screenshot viewports [width, height] (defaults to [1280, 1024])
}, [[320, 568], [768, 1024], [1024, 768], [1280, 768]])

Generate baseline screenshots:

npx viz baseline

Test your UI:

npx viz test

About

Viz generates and compares screenshots of your UI components using Puppeteer. Integrated into your CI/CD workflow, this allows you to detect unexpected visual changes to your UI and prevent visual regressions making it to production.

CLI usage

If a package directory is specified, it must exist and contain a package.json file.

viz baseline options

Debugging tests in the browser

If any of your screenshots aren't being generated as expected, you can run them individually in a browser.

1. Compile the tests:

   npx viz compile

2. Start a web server (on port 8080, for example):

   npx serve -l 8080 node_modules/viz

3. Open http://localhost:8080/bin/runner.html in your browser.
4. Open your browser's JavaScript console.
5. Run the test by suite name and test name, e.g.

   viz.runTest('my-component', 'basic')

Viz will render your test and, from there, you can inspect it.

Configuration

Viz can be configured via the first of the following files found in your project's root:

• viz.json
• .vizrc
• .viz.js
• viz.js

Valid configuration options are as follows:

NOTE: If chromeExecutablePath isn't specified, Viz tries to find an installation of Chrome and may fail to do so.

Monorepo support

To run a Viz command in a single monorepo package, specify the packageDir positional parameter (see usage above).

When specified, packageDir overrides testFilePath and prefixes outputPath, testReportOutputDir and tmpDir in the config file, ensuring Viz generates output in the package's directory.

Additional features

Padding around screenshots

To add padding to a screenshot, wrap the target element in an element with padding. The screenshot will automatically inherit the parent element's padding without having to fill it horizontally.

Roadmap

• Tests
• Improve documentation
• Example repository

Acknowledgements

Viz is a permanent fork of Vizard, by Streamotion.