@knappi/addon-storyshots-selenium

Compare screenshots of your storybook with multiple browsers and multiple screen sizes

Overview / Purpose

"@knappi/addon-storyshots-selenium" is a plugin for Storybook's "storyshot" addons that allows you to visually compare your stories in multiple browsers and multiple screen sizes. What?

• Storybook helps you structure your UI components. You can develop components independently of the whole app, and describe them in "stories". Each story is small web-page that shows your component in a certain state. It's pretty cool...

• Storyshots is an add-on to storybook. It allows you to take snapshots of each of your stories and compare them to old versions. The test ensures that they do not change and if they do, you can verify if the change is wanted or not.

By default, StoryShots uses React Tree Snapshots. Using "@knappi/addon-storyshots-selenium", you can take screenshots of your components using browser remote controlled via Selenium. Those screenshots are visually compared to a baseline-screenshot using the package jest-image-snapshot. Differences lead to a failing test and the difference will be added as an image-file (which can be added to your CI's artifacts).

"@knappi/addon-storyshots-selenium" also allows you to test responsive components by specifying multiple screen sizes. It also allows you to specify multiple browsers.

You can setup a Selenium grid yourself, use a docker-image or rent services like BrowserStack or SauceLabs.

At this point, I should mention that BrowserStack provided a free account to me very quickly, so that I could automated tests for this component using BrowserStack. I am not anyhow affiliated with BrowserStack however.

Installation

npm install @knappi/addon-storyshots-selenium

Usage

The integration-tests in this repository are a good example for how to setup tests using this repository.

• The docker-selenium integration test uses the docker-image docker-image to start a selenium grid. It is based upon elgalu/docker-selenium but includes a "reverse-tunnel" that can be used to access the storybook-server on the host, or on the "build-container" in Gitlab-CI.
• The BrowerStack integration test uses BrowserStack-Automate to create screenshots. It starts a BrowserStackLocal-Tunnel to give BrowserStack access to your local server.
• You can also have a look at the Github-Actions configuration for running the tests, especially at the artifacts definition, that allows you to inspect test-results that have failed in CI.

I am planning to provide real example repositories at some point, also for "Gitlab-CI".

API documentation

The API-docs are generated with TypeDoc. The main entrypoints is

• The imageSnapshot-function

Some utilities can be used as well to facilitate configuration:

• doNothing
• waitMillis

How it works

Taking a screenshot of the correct size is not easy (as I had to find out), because decorations have different sizes in different browsers, and some browsers have a minimal window-size.

"@knappi/addon-storyshots-selenium" uses an iframe to simulate the browser window. The workflow for screenshots in multiple window sizes is the following:

• Open about:blank
• Insert an iframe, loading the storybook-story.
• Execute hook "beforeFirstScreenshot", which by default waits a couple of seconds to let the page load completely.
• Resize the iframe to the first specified width and height, execute "beforeEachScreenshot", take a screenshot and compare.
• Resize the iframe to the specified width and height, execute "beforeEachScreenshot", take a screenshot and compare.
• and so on...

This process is executed in parallel for each browser. The selenium-drivers are initialized before all tests and closed afterwards.

License

@knappi/addon-storyshots-selenium is published under the MIT-license.

See LICENSE.md for details.

Release-Notes

For release notes, see CHANGELOG.md

Contributing guidelines

See CONTRIBUTING.md.