Blazing fast visual regression testing without the flakiness.

Installation

npm install visual-html

Features

Works in modern browsers and JSDOM (assuming you are loading styles in your tests).
Snapshots are able to be rendered by a real browser, useful for debugging!
Easily test and mock @media and @supports styles (see tests folder).
Reduces implementation details in your snapshots.
Supports inline styles and stylesheets/blocks.
Supports CSS in JS or CSS in CSS!
Supports pseudo elements.

Check out the tests for some examples.

API

`visualHTML(div: Element, options?: { shallow?: boolean })`

visualHTML(document.body); // Returns the visual information of all nested elements in the body.
visualHTML(document.body, { shallow: true }); // Returns just visual information for the `<body>` element.

How it works

visual-html works by building up an HTML representation of the DOM including only attributes that account for the visual display of the element. It will scan through all style sheets and inline the applied styles for an element. Then it reads all properties that change the visuals of the element and includes the corresponding attribute in the HTML snapshot.

Lets look at an example.

<style>
  .my-component {
    width: 100px;
    height: 200px;
    background: red;
  }

  .my-component span {
    color: #333;
  }
</style>

<div
  class="my-component"
  data-testid="component-test-id"
  style="transform: translateX(-100px)"
>
  <span class="unused">Hello!</span>

  <form action="/login">
    <label>
      Username:
      <input type="text" name="username" />
    </label>

    <label>
      Password:
      <input type="password" name="password" />
    </label>

    <label>
      Remember Me:
      <input type="checkbox" name="remember" />
    </label>

    <button type="submit">Sign in</button>
  </form>
</div>

Passing the div element above to visual-html would yield the following:

import visualHTML from "visual-html";

visualHTML(div); // Returns the html below as string.

<div
  style="
  background: red;
  height: 200px;
  transform: translateX(-100px);
  width: 100px
"
>
  <span style="color: #333"> Hello! </span>
  <form>
    <label>
      Username:
      <input />
    </label>
    <label>
      Password:
      <input type="password" />
    </label>
    <label>
      Remember Me:
      <input type="checkbox" />
    </label>
    <button>Sign in</button>
  </form>
</div>

In the above output you can see that the majority of attributes have been removed, and styles are now included inline. The type="text" on the first input was removed since it is a default. All attributes and properties are also sorted alphabetically to be more stable.

How is this different than x!?

using an actual image based visual regression tool? (eg. puppeteer)

At the end of the day we are trying to test that our components display correctly, and to catch visual regressions, so why not use an image based visual regression tool? These tools require a real browser, and often can be slow and unreliable. Specifically browsers rely heavily on the operating system to render parts of the page such as fonts which can cause slight differences between screenshots taken from your local machine and your CI. You can get around this last part by having a CI or a local docker image but either way your compromising the speed of your tests and development workflow.

With this module we are not rendering actual pixels. Instead it pulls all visual information from the DOM and aggregates it into an HTML snapshot. You can build and compare these text based snapshots during your tests which is quick and repeatable. This allows you to have increased confidence in your tests without slowing down or complicating your work flow.

inlining styles and snapshoting the elements HTML directly?

The key with snapshots is to avoid allowing the implementation details of your tests to leak in. Snapshots are easy to update, but if too much is leaking in they can often be hard to review.

In an ideal world a snapshot would automatically include just the critical assertions for what you are testing so that you can confidently refactor your code without breaking your tests.

This is where visual-html comes in. It is a solution for testing the visual aspect of your components and works to create a snapshot containing only visually relevant information.

writing tests for classes on an element?

Testing the exact classes applied to an element often provides little value. A simple way to determine the value of a test is to think about when it would break, and in turn which issues it would catch.

In the example below the tests do not know anything about some-class, what it does, or if it even has a matching css selector.

Imagine that some-class is really just a utility to visually highlight our element, our tests do not capture that at all. By instead testing the applied styles you know that your CSS is actually hooked up properly, and you can have a better idea of how the element would be visually displayed to the user.

test("it has the right class", () => {
  const { container } = render(MyComponent);

  expect(container).not.toHaveClass("some-class");
  doThing();
  expect(container).toHaveClass("some-class");
});

import snapshotDiff from "snapshot-diff";

test("it is highlighted after the thing", () => {
  const { container } = render(MyComponent);
  const originalView = visualHTML(container);
  doThing();
  const updatedView = visualHTML(container);

  expect(snapshotDiff(originalView, updatedView)).toMatchInlineSnapshot(`
    "Snapshot Diff:
    - First value
    + Second value

    - <div/>
    + <div style=\\"border: 2px solid green\\"/>"
  `);
});

With the above you can refactor the way the element is highlighted (different class, inline styles, etc) and as long as the element is still ultimately displayed the same, your test will continue to pass.

Code of Conduct

This project adheres to the eBay Code of Conduct. By participating in this project you agree to abide by its terms.

License

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

eBay / visual-html

readme