Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eBay/visual-html

Visual regression testing without the flakiness.
https://github.com/eBay/visual-html

css dom snapshot testing visual-regression

Last synced: 3 months ago
JSON representation

Visual regression testing without the flakiness.

Host: GitHub
URL: https://github.com/eBay/visual-html
Owner: eBay
License: mit
Created: 2019-08-19T21:37:25.000Z (about 5 years ago)
Default Branch: main
Last Pushed: 2023-07-19T21:12:36.000Z (over 1 year ago)
Last Synced: 2024-07-16T23:12:57.964Z (4 months ago)
Topics: css, dom, snapshot, testing, visual-regression
Language: TypeScript
Size: 941 KB
Stars: 28
Watchers: 10
Forks: 8
Open Issues: 5
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

Blazing fast visual regression testing without the flakiness.

# Installation

```console
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](./src/__tests__/index.ts) for some examples.

## API

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

```javascript
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 `` 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.

```html

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

.my-component span {
color: #333;
}

Hello!

Username:

Password:

Remember Me:

```

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

```javascript
import visualHTML from "visual-html";

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

```html

Hello!

Username:

Password:

Remember Me:

Sign in

```

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.

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

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

```javascript
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

"
`);
});
```

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](http://ebay.github.io/codeofconduct). 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.