# viz > Visual regression testing framework Latest version **3.0.1** (published 2022-05-15) · MIT license · 0 weekly downloads ## Install ```sh npm install viz pnpm add viz yarn add viz bun add viz ``` Provides the command `viz`. ## Health **Score 20/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 3.0.1 | | Published | 2022-05-15 | | First published | 2015-02-04 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 20 | | Unpacked size | 56.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Maintainers | slmt | | Keywords | visual, regression, puppeteer, react, angular, vue, svelte, jquery, html, css, javascript, typescript | ## Links - npm: https://www.npmjs.com/package/viz - Repository: https://github.com/steve-taylor/viz - Homepage: https://github.com/steve-taylor/viz#readme - Issues: https://github.com/steve-taylor/viz/issues - npm.io page: https://npm.io/package/viz ## Dependencies (20) - [yargs](https://npm.io/package/yargs.md) ^17.5.0 - [lodash](https://npm.io/package/lodash.md) ^4.17.21 - [log4js](https://npm.io/package/log4js.md) ^6.4.6 - [mkdirp](https://npm.io/package/mkdirp.md) ^1.0.4 - [core-js](https://npm.io/package/core-js.md) ^3.22.5 - [webpack](https://npm.io/package/webpack.md) ^5.72.1 - [fs-extra](https://npm.io/package/fs-extra.md) ^10.1.0 - [through2](https://npm.io/package/through2.md) ^4.0.2 - [watchify](https://npm.io/package/watchify.md) ^4.0.0 - [portfinder](https://npm.io/package/portfinder.md) ^1.0.28 - [@babel/core](https://npm.io/package/@babel/core.md) ^7.17.10 - [img-diff-js](https://npm.io/package/img-diff-js.md) ^0.5.2 - [npm-run-all](https://npm.io/package/npm-run-all.md) ^4.1.5 - [babel-loader](https://npm.io/package/babel-loader.md) ^8.2.5 - [serve-handler](https://npm.io/package/serve-handler.md) ^6.1.3 - [puppeteer-core](https://npm.io/package/puppeteer-core.md) ^14.1.0 - [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.17.10 - [recursive-readdir](https://npm.io/package/recursive-readdir.md) ^2.2.2 - [regenerator-runtime](https://npm.io/package/regenerator-runtime.md) ^0.13.9 - [junit-report-builder](https://npm.io/package/junit-report-builder.md) ^3.0.0 ## Alternatives - [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads - [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads - [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads - [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads - [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads ## Recent versions - 3.0.1 (latest) — 2022-05-15 - 3.0.1-alpha.2 (alpha) — 2022-05-14 - 3.0.1-alpha.1 — 2022-05-14 - 3.0.0 — 2021-08-29 - 3.0.0-alpha.1 — 2021-08-29 - 3.0.0-alpha.0 — 2021-08-29 - 2.4.0-alpha.0 — 2021-08-29 - 2.3.0 — 2021-08-05 - 2.3.0-alpha.1 — 2021-08-05 - 2.3.0-alpha.0 — 2021-08-05 - 2.2.0 — 2021-08-04 - 2.2.0-alpha.1 — 2021-08-04 - 2.1.0 — 2021-07-19 - 2.0.0 — 2021-07-17 - 2.0.0-alpha.9 — 2021-07-17 - … 14 more at https://npm.io/package/viz/versions ## README # Viz Visual regression testing framework. Works with all web frameworks. [![npm version](https://img.shields.io/npm/v/viz.svg?style=flat)](https://www.npmjs.com/package/viz) ![npm](https://img.shields.io/npm/dw/viz.svg) ## Quick start Install: ```bash npm i -D viz ``` Configure Babel in your [configuration file](#configuration), e.g. ```json { "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`): ```tsx // 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(resolve => { render( , target, resolve ) }) // Return the DOM node for Viz to screenshot return target.firstChild }) test('disabled', async target => { await new Promise(resolve => { render( , 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(resolve => { render( , target, async () => { // Trigger focus state await click('.MyComponent') resolve() } ) }) }) test('hover', async target => { await new Promise(resolve => { render( , 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: ```bash npx viz baseline ``` Test your UI: ```bash 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 | Command | Description | | --------------------------- | -------------------------------------------------------------------------- | | `viz compile [packageDir]` | Compile all test cases. | | `viz baseline [packageDir]` | Take baseline screenshots. | | `viz test [packageDir]` | Run viz tests, taking screenshots and comparing them against the baseline. | | `viz --help` | Get help. | If a package directory is specified, it must exist and contain a package.json file. ### `viz baseline` options | Option | Description | | --------------------------|------------------------------------------------------| | `--missing` | Only take baseline screenshots that don’t yet exist. | | `--suite SUITE-1 SUITE-2` | Only run specified suites. | | `--skip-compile` | Don’t compile test. (Assumes they’ve been compiled.) | ## 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: ```bash npx viz compile ``` 2. Start a web server (on port 8080, for example): ```bash 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. ```js 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: | Option | Description | Default | |---------------------------------|-------------------------------------------------------------------|----------------------------------------------------------------| | `chromeExecutablePath` | Path to external Chrome executable | | | `concurrentLimit` | Number of browsers to run in parallel | `1` | | `defaultViewportWidth` | Default viewport width in pixels | `1024` | | `defaultViewportHeight` | Default viewport height in pixels | `1080` | | `viewportScale ` | Viewport scale | `1` | | `outputPath` | Output path for screenshots | `.viz/out` | | `testReportOutputDir` | Path for test reports | `.viz/out/report` | | `testFilePath` | Path to search for test files | Current working directory | | `testFilePattern` | File extension (or array of file extensions) of test files | `[".viz.js", ".viz.jsx", ".viz.tsx"]` | | `testRunnerHtml` | Optional custom HTML page in which tests should be executed | | | `tmpDir` | Optional custom directory to store temporary files | `.viz/tmp` in the current working directory | | `threshold` | Image matching threshold from 0 to 1 (smaller is more sensitive) | `0` | | `includeAA` | Whether to disable detecting and ignoring anti-aliased pixels | `false` | | `babel` | Babel configuration | `{presets: ['@babel/preset-env', '@babel/preset-typescript']}` | | `sourceMaps` | Whether to include source maps in the build | `false` | 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](https://github.com/streamotion/vizard), by Streamotion. --- _Source: https://npm.io/package/viz · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._