From 0478125ae3601f17eaf5f6c16592806d2b50a8b4 Mon Sep 17 00:00:00 2001 From: igor-dv Date: Sun, 10 Jun 2018 14:34:45 +0300 Subject: [PATCH 1/6] Extract imageSnapshots to a separate package --- addons/storyshots/README.md | 486 +----------------- .../{ => storyshots-core}/.eslintrc.js | 0 .../{ => storyshots-core}/.npmignore | 0 .../.storybook/config.js | 0 addons/storyshots/storyshots-core/README.md | 334 ++++++++++++ .../docs/storyshots-fail.png | Bin .../{ => storyshots-core}/docs/storyshots.png | Bin .../{ => storyshots-core}/package.json | 3 - .../src/angular/app.component.ts | 0 .../src/angular/app.token.ts | 0 .../src/angular/helpers.ts | 0 .../src/angular/loader.js | 0 .../src/angular/renderTree.js | 0 .../src/angular/types.ts | 0 .../src/config-loader.js | 0 .../src/frameworkLoader.js | 0 .../src/getIntegrityOptions.js | 0 .../src/hasDependency.js | 0 .../{ => storyshots-core}/src/html/loader.js | 0 .../src/html/renderTree.js | 0 .../{ => storyshots-core}/src/index.js | 2 - .../{ => storyshots-core}/src/react/loader.js | 0 .../src/react/renderShallowTree.js | 0 .../src/react/renderTree.js | 0 .../src/require_context.js | 0 .../{ => storyshots-core}/src/rn/loader.js | 0 .../{ => storyshots-core}/src/test-bodies.js | 0 .../{ => storyshots-core}/src/utils.js | 0 .../{ => storyshots-core}/src/utils.test.js | 0 .../{ => storyshots-core}/src/vue/loader.js | 0 .../src/vue/renderTree.js | 0 .../storyshot.enzyme.test.js.snap | 0 .../storyshot.shallow.test.js.snap | 0 .../storyshot.shallowWithOptions.test.js.snap | 0 .../__snapshots__/index.storyshot | 0 .../stories/directly_required/index.js | 0 .../required_with_context/Button.stories.js | 0 .../required_with_context/Welcome.stories.js | 0 .../__snapshots__/Button.stories.storyshot | 0 .../__snapshots__/Welcome.stories.storyshot | 0 .../stories/storyshot.enzyme.test.js | 0 .../stories/storyshot.renderOnly.test.js | 0 .../storyshot.renderWithOptions.test.js | 0 .../stories/storyshot.shallow.test.js | 0 .../storyshot.shallowWithOptions.test.js | 0 .../stories/storyshot.test.js | 0 .../{ => storyshots-core}/tsconfig.json | 2 +- .../storyshots/storyshots-puppeteer/README.md | 154 ++++++ .../storyshots-puppeteer/package.json | 23 + .../src/index.js} | 0 .../storyshots-image.runner.js | 3 +- examples/official-storybook/package.json | 1 + package.json | 1 + 53 files changed, 519 insertions(+), 490 deletions(-) rename addons/storyshots/{ => storyshots-core}/.eslintrc.js (100%) rename addons/storyshots/{ => storyshots-core}/.npmignore (100%) rename addons/storyshots/{ => storyshots-core}/.storybook/config.js (100%) create mode 100644 addons/storyshots/storyshots-core/README.md rename addons/storyshots/{ => storyshots-core}/docs/storyshots-fail.png (100%) rename addons/storyshots/{ => storyshots-core}/docs/storyshots.png (100%) rename addons/storyshots/{ => storyshots-core}/package.json (90%) rename addons/storyshots/{ => storyshots-core}/src/angular/app.component.ts (100%) rename addons/storyshots/{ => storyshots-core}/src/angular/app.token.ts (100%) rename addons/storyshots/{ => storyshots-core}/src/angular/helpers.ts (100%) rename addons/storyshots/{ => storyshots-core}/src/angular/loader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/angular/renderTree.js (100%) rename addons/storyshots/{ => storyshots-core}/src/angular/types.ts (100%) rename addons/storyshots/{ => storyshots-core}/src/config-loader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/frameworkLoader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/getIntegrityOptions.js (100%) rename addons/storyshots/{ => storyshots-core}/src/hasDependency.js (100%) rename addons/storyshots/{ => storyshots-core}/src/html/loader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/html/renderTree.js (100%) rename addons/storyshots/{ => storyshots-core}/src/index.js (97%) rename addons/storyshots/{ => storyshots-core}/src/react/loader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/react/renderShallowTree.js (100%) rename addons/storyshots/{ => storyshots-core}/src/react/renderTree.js (100%) rename addons/storyshots/{ => storyshots-core}/src/require_context.js (100%) rename addons/storyshots/{ => storyshots-core}/src/rn/loader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/test-bodies.js (100%) rename addons/storyshots/{ => storyshots-core}/src/utils.js (100%) rename addons/storyshots/{ => storyshots-core}/src/utils.test.js (100%) rename addons/storyshots/{ => storyshots-core}/src/vue/loader.js (100%) rename addons/storyshots/{ => storyshots-core}/src/vue/renderTree.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/__snapshots__/storyshot.enzyme.test.js.snap (100%) rename addons/storyshots/{ => storyshots-core}/stories/__snapshots__/storyshot.shallow.test.js.snap (100%) rename addons/storyshots/{ => storyshots-core}/stories/__snapshots__/storyshot.shallowWithOptions.test.js.snap (100%) rename addons/storyshots/{ => storyshots-core}/stories/directly_required/__snapshots__/index.storyshot (100%) rename addons/storyshots/{ => storyshots-core}/stories/directly_required/index.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/required_with_context/Button.stories.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/required_with_context/Welcome.stories.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/required_with_context/__snapshots__/Button.stories.storyshot (100%) rename addons/storyshots/{ => storyshots-core}/stories/required_with_context/__snapshots__/Welcome.stories.storyshot (100%) rename addons/storyshots/{ => storyshots-core}/stories/storyshot.enzyme.test.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/storyshot.renderOnly.test.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/storyshot.renderWithOptions.test.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/storyshot.shallow.test.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/storyshot.shallowWithOptions.test.js (100%) rename addons/storyshots/{ => storyshots-core}/stories/storyshot.test.js (100%) rename addons/storyshots/{ => storyshots-core}/tsconfig.json (75%) create mode 100644 addons/storyshots/storyshots-puppeteer/README.md create mode 100644 addons/storyshots/storyshots-puppeteer/package.json rename addons/storyshots/{src/test-body-image-snapshot.js => storyshots-puppeteer/src/index.js} (100%) diff --git a/addons/storyshots/README.md b/addons/storyshots/README.md index 105e87ae03ed..d886a7ff693a 100644 --- a/addons/storyshots/README.md +++ b/addons/storyshots/README.md @@ -1,486 +1,6 @@ # StoryShots -[![Build Status on CircleCI](https://circleci.com/gh/storybooks/storybook.svg?style=shield)](https://circleci.com/gh/storybooks/storybook) -[![CodeFactor](https://www.codefactor.io/repository/github/storybooks/storybook/badge)](https://www.codefactor.io/repository/github/storybooks/storybook) -[![Known Vulnerabilities](https://snyk.io/test/github/storybooks/storybook/8f36abfd6697e58cd76df3526b52e4b9dc894847/badge.svg)](https://snyk.io/test/github/storybooks/storybook/8f36abfd6697e58cd76df3526b52e4b9dc894847) -[![BCH compliance](https://bettercodehub.com/edge/badge/storybooks/storybook)](https://bettercodehub.com/results/storybooks/storybook) [![codecov](https://codecov.io/gh/storybooks/storybook/branch/master/graph/badge.svg)](https://codecov.io/gh/storybooks/storybook) -[![Storybook Slack](https://now-examples-slackin-rrirkqohko.now.sh/badge.svg)](https://now-examples-slackin-rrirkqohko.now.sh/) -[![Backers on Open Collective](https://opencollective.com/storybook/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/storybook/sponsors/badge.svg)](#sponsors) +TBD -* * * - -StoryShots adds automatic Jest Snapshot Testing for [Storybook](https://storybook.js.org/). - -[Framework Support](https://github.com/storybooks/storybook/blob/master/ADDONS_SUPPORT.md) - -![StoryShots In Action](docs/storyshots-fail.png) - -To use StoryShots, you must use your existing Storybook stories as the input for Jest Snapshot Testing. - -## Getting Started - -Add the following module into your app. - -```sh -npm install --save-dev @storybook/addon-storyshots -``` - -## Configure your app for Jest - -Usually, you might already have completed this step. If not, here are some resources for you. - -If you are using Create React App, it's already configured for Jest. You just need to create a filename with the extension `.test.js`. - -If you aren't familiar with Jest, here are some resources: - -- [Getting Started - Jest Official Documentation](https://facebook.github.io/jest/docs/en/getting-started.html) -- [Javascript Testing with Jest - Egghead](https://egghead.io/lessons/javascript-test-javascript-with-jest). ***paid content*** - -> Note: If you use React 16, you'll need to follow [these additional instructions](https://github.com/facebook/react/issues/9102#issuecomment-283873039). - -### Configure Jest for React -StoryShots addon for React is dependent on [react-test-renderer](https://github.com/facebook/react/tree/master/packages/react-test-renderer), but -[doesn't](#deps-issue) install it, so you need to install it separately. - -```sh -npm install --save-dev react-test-renderer -``` - -### Configure Jest for Angular -StoryShots addon for Angular is dependent on [jest-preset-angular](https://github.com/thymikee/jest-preset-angular), but -[doesn't](#deps-issue) install it, so you need to install it separately. - -```sh -npm install --save-dev jest-preset-angular -``` - -If you already use Jest for testing your angular app - probably you already have the needed jest configuration. -Anyway you can add these lines to your jest config: -```js -module.exports = { - globals: { - __TRANSFORM_HTML__: true, - }, - transform: { - '^.+\\.jsx?$': 'babel-jest', - '^.+\\.(ts|html)$': '/node_modules/jest-preset-angular/preprocessor.js', - }, - moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node', '.html'], -}; -``` -### Configure Jest for Vue -StoryShots addon for Vue is dependent on [jest-vue-preprocessor](https://github.com/vire/jest-vue-preprocessor), but -[doesn't](#deps-issue) install it, so you need to install it separately. - - ```sh - npm install --save-dev jest-vue-preprocessor - ``` - -If you already use Jest for testing your vue app - probably you already have the needed jest configuration. -Anyway you can add these lines to your jest config: -```js -module.exports = { - transform: { - '^.+\\.jsx?$': 'babel-jest', - '.*\\.(vue)$': '/node_modules/jest-vue-preprocessor', - }, - transformIgnorePatterns: [ - '/node_modules/(?!(@storybook/.*\\.vue$))', - ], - moduleFileExtensions: ['vue', 'js', 'jsx', 'json', 'node'], -}; -``` - -### Why don't we install dependencies of each framework ? -Storyshots addon is currently supporting React, Angular and Vue. Each framework needs its own packages to be integrated with Jest. We don't want people that use only React will need to bring other dependencies that do not make sense for them. - -`dependencies` - will installed an exact version of the particular dep - Storyshots can work with different versions of the same framework (let's say React v16 and React v15), that have to be compatible with a version of its plugin (react-test-renderer). - -`optionalDependencies` - behaves like a regular dependency, but do not fail the installation in case there is a problem to bring the dep. - -`peerDependencies` - listing all the deps in peer will trigger warnings during the installation - we don't want users to install unneeded deps by hand. - -`optionalPeerDependencies` - unfortunately there is nothing like this =( - -For more information read npm [docs](https://docs.npmjs.com/files/package.json#dependencies) - -## Configure Storyshots for HTML snapshots - -Create a new test file with the name `Storyshots.test.js`. (Or whatever the name you prefer, as long as it matches Jest's config [`testMatch`](http://facebook.github.io/jest/docs/en/configuration.html#testmatch-array-string)). -Then add following content to it: - -```js -import initStoryshots from '@storybook/addon-storyshots'; - -initStoryshots(); -``` - -That's all. - -Now run your Jest test command. (Usually, `npm test`.) Then you can see all of your stories are converted as Jest snapshot tests. - -![Screenshot](docs/storyshots.png) - - -### Using `createNodeMock` to mock refs - -`react-test-renderer` doesn't provide refs for rendered components. By -default, it returns null when the refs are referenced. In order to mock -out elements that rely on refs, you will have to use the -`createNodeMock` option [added to React](https://reactjs.org/blog/2016/11/16/react-v15.4.0.html#mocking-refs-for-snapshot-testing) starting with version 15.4.0. - -Here is an example of how to specify the `createNodeMock` option in Storyshots: - -```js -import initStoryshots, { snapshotWithOptions } from '@storybook/addon-storyshots' -import TextareaThatUsesRefs from '../component/TextareaThatUsesRefs' - -initStoryshots({ - test: snapshotWithOptions({ - createNodeMock: (element) => { - if (element.type === TextareaThatUsesRefs) { - return document.createElement('textarea') - } - }, - }), -}) -``` - -## Configure Storyshots for image snapshots ( alpha ) - -/*\ **React-native** is **not supported** by this test function. - -Internally, it uses [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot). - -When willing to generate and compare image snapshots for your stories, you have two options: -- Have a storybook running (ie. accessible via http(s), for instance using `yarn run storybook`) -- Have a static build of the storybook (for instance, using `yarn run build-storybook`) - -Then you will need to reference the storybook URL (`file://...` if local, `http(s)://...` if served) - -### Using default values for _imageSnapshots_ - -Then you can either create a new Storyshots instance or edit the one you previously used: -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; - -initStoryshots({suite: 'Image storyshots', test: imageSnapshot()}); -``` -This will assume you have a storybook running on at __. -Internally here are the steps: -- Launches a Chrome headless using [puppeteer](https://github.com/GoogleChrome/puppeteer) -- Browses each stories (calling __ URL), -- Take screenshots & save all images under _\_image_snapshots\__ folder. - -### Specifying the storybook URL - -If you want to set specific storybook URL, you can specify via the `storybookUrl` parameter, see below: -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; - -initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://my-specific-domain.com:9010'})}); -``` -The above config will use __ for screenshots. - - -You may also use a local static build of storybook if you do not want to run the webpack dev-server: -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; - -initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'file:///path/to/my/storybook-static'})}); -``` - -### Specifying options to _jest-image-snapshots_ - -If you wish to customize [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot), then you can provide a `getMatchOptions` parameter that should return the options config object. Additionally, you can provide `beforeScreenshot` which is called before the screenshot is captured. -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; -const getMatchOptions = ({context : {kind, story}, url}) => { - return { - failureThreshold: 0.2, - failureThresholdType: 'percent', - } -} -const beforeScreenshot = (page, {context : {kind, story}, url}) => { - return new Promise(resolve => - setTimeout(() => { - resolve(); - }, 600) - ) -} -initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', getMatchOptions, beforeScreenshot})}); -``` -`getMatchOptions` receives an object: `{ context: {kind, story}, url}`. _kind_ is the kind of the story and the _story_ its name. _url_ is the URL the browser will use to screenshot. - -`beforeScreenshot` receives the [Puppeteer page instance](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-page) and an object: `{ context: {kind, story}, url}`. _kind_ is the kind of the story and the _story_ its name. _url_ is the URL the browser will use to screenshot. `beforeScreenshot` is part of the promise chain and is called after the browser navigation is completed but before the screenshot is taken. It allows for triggering events on the page elements and delaying the screenshot and can be used avoid regressions due to mounting animations. - -### Specifying options to _goto()_ (puppeteer API) - -You might use `getGotoOptions` to specify options when the storybook is navigating to a story (using the `goto` method). Will be passed to [Puppeteer .goto() fn](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options) - -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; -const getGotoOptions = ({context, url}) => { - return { - waitUntil: 'networkidle0', - } -} -initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', getGotoOptions})}); -``` -### Specifying options to _screenshot()_ (puppeteer API) - -You might use `getScreenshotOptions` to specify options for screenshot. Will be passed to [Puppeteer .screenshot() fn](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagescreenshotoptions) - -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; -const getScreenshotOptions = ({context, url}) { - return { - fullPage: false // Do not take the full page screenshot. Default is 'true' in Storyshots. - } -} -initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', getScreenshotOptions})}); -``` - -`getScreenshotOptions` receives an object `{ context: {kind, story}, url}`. _kind_ is the kind of the story and the _story_ its name. _url_ is the URL the browser will use to screenshot. - -### Specifying custom Chrome executable path (puppeteer API) - -You might use `chromeExecutablePath` to specify the path to a different version of Chrome, without downloading Chromium. Will be passed to [Runs a bundled version of Chromium](https://github.com/GoogleChrome/puppeteer#default-runtime-settings) - -```js -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; - -const chromeExecutablePath = '/usr/local/bin/chrome'; - -initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', chromeExecutablePath})}); -``` - -### Integrate image storyshots with regular app - -You may want to use another Jest project to run your image snapshots as they require more resources: Chrome and Storybook built/served. -You can find a working example of this in the [official-storybook](https://github.com/storybooks/storybook/tree/master/examples/official-storybook) example. - -### Integrate image storyshots with [Create React App](https://github.com/facebookincubator/create-react-app) - -You have two options here, you can either: - -- Simply add the storyshots configuration inside any of your `test.js` file. You must ensure you have either a running storybook or a static build available. - -- Create a custom test file using Jest outside of the CRA scope: - - A more robust approach would be to separate existing test files ran by create-react-app (anything `(test|spec).js` suffixed files) from the test files to run storyshots with image snapshots. - This use case can be achieved by using a custom name for the test file, ie something like `image-storyshots.runner.js`. This file will contains the `initStoryshots` call with image snapshots configuration. - Then you will create a separate script entry in your package.json, for instance - ```json - { - "scripts": { - "image-snapshots" : "jest image-storyshots.runner.js --config path/to/custom/jest.config.json" - } - } - ``` - Note that you will certainly need a custom config file for Jest as you run it outside of the CRA scope and thus you do not have the built-in config. - - Once that's setup, you can run `yarn run image-snapshots` (or `npm run image-snapshots`). - -### Reminder - -An image snapshot is simply a screenshot taken by a web browser (in our case, Chrome). - -The browser opens a page (either using the static build of storybook or a running instance of Storybook) - -If you run your test without either the static build or a running instance, this wont work. - -To make sure your screenshots are taken from latest changes of your Storybook, you must keep your static build or running Storybook up-to-date. -This can be achieved by adding a step before running the test ie: `yarn run build-storybook && yarn run image-snapshots`. -If you run the image snapshots against a running Storybook in dev mode, you don't have to care about being up-to-date because the dev-server is watching changes and rebuilds automatically. - -## Options - -### `configPath` - -By default, Storyshots assumes the config directory path for your project as below: - -- Storybook for React: `.storybook` -- Storybook for React Native: `storybook` - -If you are using a different config directory path, you could change it like this: - -```js -import initStoryshots from '@storybook/addon-storyshots'; - -initStoryshots({ - configPath: '.my-storybook-config-dir' -}); -``` - -### `suite` - -By default, Storyshots groups stories inside a Jest test suite called "Storyshots". You could change it like this: - -```js -import initStoryshots from '@storybook/addon-storyshots'; - -initStoryshots({ - suite: 'MyStoryshots' -}); -``` - -### `storyKindRegex` - -If you'd like to only run a subset of the stories for your snapshot tests based on the story's kind: - -```js -import initStoryshots from '@storybook/addon-storyshots'; - -initStoryshots({ - storyKindRegex: /^MyComponent$/ -}); -``` - -This can be useful if you want to separate the snapshots in directories next to each component. See an example [here](https://github.com/storybooks/storybook/issues/892). - -If you want to run all stories except stories of a specific kind, you can write an inverse regex which is true for all kinds except those with a specific word such as `DontTest` - -```js -import initStoryshots from '@storybook/addon-storyshots'; - -initStoryshots({ - storyKindRegex:/^((?!.*?DontTest).)*$/ -}); -``` - -This can be useful while testing react components which make use of the findDomNode API since they always fail with snapshot testing -while using react-test-renderer see [here](https://github.com/facebook/react/issues/8324) - -### `storyNameRegex` - -If you'd like to only run a subset of the stories for your snapshot tests based on the story's name: - -```js -import initStoryshots from '@storybook/addon-storyshots'; - -initStoryshots({ - storyNameRegex: /buttons/ -}); -``` - -### `framework` - -If you are running tests from outside of your app's directory, storyshots' detection of which framework you are using may fail. Pass `"react"` or `"react-native"` to short-circuit this. - -### `test` - -Run a custom test function for each story, rather than the default (a vanilla snapshot test). Setting `test` will take precedence over the `renderer` option. See the exports section below for more details. - -### `renderer` - -Pass a custom renderer (such as enzymes `mount`) to record snapshots. Note that setting `test` overrides `renderer`. - -```js -import initStoryshots from '@storybook/addon-storyshots'; -import { mount } from 'enzyme'; - -initStoryshots({ - renderer: mount, -}); -``` - -If you are using enzyme, you need to make sure jest knows how to serialize rendered components. -You can either pass in a serializer (see below) or specify an enzyme-compatible serializer (like [enzyme-to-json](https://github.com/adriantoine/enzyme-to-json), [jest-serializer-enzyme](https://github.com/rogeliog/jest-serializer-enzyme) etc.) as the default `snapshotSerializer` in your config. - -Example for jest config in `package.json`: -```json -"devDependencies": { - "enzyme-to-json": "^3.2.2" -}, -"jest": { - "snapshotSerializers": [ - "enzyme-to-json/serializer" - ] - } -``` - -### `serializer` - -Pass a custom serializer (such as enzyme-to-json) to serialize components to snapshot-comparable data. - -```js -import initStoryshots from '@storybook/addon-storyshots'; -import toJSON from 'enzyme-to-json'; - -initStoryshots({ - renderer: mount, - serializer: toJSON, -}); -``` - -This option only needs to be set if the default `snapshotSerializers` is not set in your jest config. - -## Exports - -Apart from the default export (`initStoryshots`), Storyshots also exports some named test functions (see the `test` option above): - -### `snapshot` - -The default, render the story as normal and take a Jest snapshot. - -### `renderOnly` - -Just render the story, don't check the output at all (useful if you just want to ensure it doesn't error) - -### `snapshotWithOptions(options)` - -Like the default, but allows you to specify a set of options for the test renderer. [See for example here](https://github.com/storybooks/storybook/blob/b915b5439786e0edb17d7f5ab404bba9f7919381/examples/test-cra/src/storyshots.test.js#L14-L16). - -### `renderWithOptions(options)` - -Like the default, but allows you to specify a set of options for the renderer. See above. - -### `multiSnapshotWithOptions(options)` - -Like `snapshotWithOptions`, but generate a separate snapshot file for each stories file rather than a single monolithic file (as is the convention in Jest). This makes it dramatically easier to review changes. If you'd like the benefit of separate snapshot files, but don't have custom options to pass, simply pass an empty object. - -#### integrityOptions -This option is useful when running test with `multiSnapshotWithOptions(options)` in order to track snapshots are matching the stories. (disabled by default). -The value is just a [settings](https://github.com/isaacs/node-glob#options) to a `glob` object, that searches for the snapshot files. - -```js -initStoryshots({ - integrityOptions: { cwd: __dirname }, // it will start searching from the current directory - test: multiSnapshotWithOptions({}), -}); -``` - -### `shallowSnapshot` - -Take a snapshot of a shallow-rendered version of the component. Note that this option will be overriden if you pass a `renderer` option. - -### `getSnapshotFileName` - -Utility function used in `multiSnapshotWithOptions`. This is made available for users who implement custom test functions that also want to take advantage of multi-file storyshots. - -### `imageSnapshot` ( alpha ) - -Render the story and take Jest snapshots as images. see [Configure image snapshots](#configure-storyshots-for-image-snapshots) - -###### Example: - -Let's say we wanted to create a test function for shallow && multi-file snapshots: - -```js -import initStoryshots, { getSnapshotFileName } from '@storybook/addon-storyshots'; -import { shallow } from 'enzyme'; -import toJson from 'enzyme-to-json'; - -initStoryshots({ - test: ({ story, context }) => { - const snapshotFileName = getSnapshotFileName(context); - const storyElement = story.render(context); - const shallowTree = shallow(storyElement); - - if (snapshotFileName) { - expect(toJson(shallowTree)).toMatchSpecificSnapshot(snapshotFileName); - } - } -}); -``` +*addon-storyshots +*addon-storyshots-puppeteer diff --git a/addons/storyshots/.eslintrc.js b/addons/storyshots/storyshots-core/.eslintrc.js similarity index 100% rename from addons/storyshots/.eslintrc.js rename to addons/storyshots/storyshots-core/.eslintrc.js diff --git a/addons/storyshots/.npmignore b/addons/storyshots/storyshots-core/.npmignore similarity index 100% rename from addons/storyshots/.npmignore rename to addons/storyshots/storyshots-core/.npmignore diff --git a/addons/storyshots/.storybook/config.js b/addons/storyshots/storyshots-core/.storybook/config.js similarity index 100% rename from addons/storyshots/.storybook/config.js rename to addons/storyshots/storyshots-core/.storybook/config.js diff --git a/addons/storyshots/storyshots-core/README.md b/addons/storyshots/storyshots-core/README.md new file mode 100644 index 000000000000..1304e1376f03 --- /dev/null +++ b/addons/storyshots/storyshots-core/README.md @@ -0,0 +1,334 @@ +# StoryShots + +[![Build Status on CircleCI](https://circleci.com/gh/storybooks/storybook.svg?style=shield)](https://circleci.com/gh/storybooks/storybook) +[![CodeFactor](https://www.codefactor.io/repository/github/storybooks/storybook/badge)](https://www.codefactor.io/repository/github/storybooks/storybook) +[![Known Vulnerabilities](https://snyk.io/test/github/storybooks/storybook/8f36abfd6697e58cd76df3526b52e4b9dc894847/badge.svg)](https://snyk.io/test/github/storybooks/storybook/8f36abfd6697e58cd76df3526b52e4b9dc894847) +[![BCH compliance](https://bettercodehub.com/edge/badge/storybooks/storybook)](https://bettercodehub.com/results/storybooks/storybook) [![codecov](https://codecov.io/gh/storybooks/storybook/branch/master/graph/badge.svg)](https://codecov.io/gh/storybooks/storybook) +[![Storybook Slack](https://now-examples-slackin-rrirkqohko.now.sh/badge.svg)](https://now-examples-slackin-rrirkqohko.now.sh/) +[![Backers on Open Collective](https://opencollective.com/storybook/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/storybook/sponsors/badge.svg)](#sponsors) + +* * * + +StoryShots adds automatic Jest Snapshot Testing for [Storybook](https://storybook.js.org/). + +[Framework Support](https://github.com/storybooks/storybook/blob/master/ADDONS_SUPPORT.md) + +![StoryShots In Action](docs/storyshots-fail.png) + +To use StoryShots, you must use your existing Storybook stories as the input for Jest Snapshot Testing. + +## Getting Started + +Add the following module into your app. + +```sh +npm install --save-dev @storybook/addon-storyshots +``` + +## Configure your app for Jest + +Usually, you might already have completed this step. If not, here are some resources for you. + +If you are using Create React App, it's already configured for Jest. You just need to create a filename with the extension `.test.js`. + +If you aren't familiar with Jest, here are some resources: + +- [Getting Started - Jest Official Documentation](https://facebook.github.io/jest/docs/en/getting-started.html) +- [Javascript Testing with Jest - Egghead](https://egghead.io/lessons/javascript-test-javascript-with-jest). ***paid content*** + +> Note: If you use React 16, you'll need to follow [these additional instructions](https://github.com/facebook/react/issues/9102#issuecomment-283873039). + +### Configure Jest for React +StoryShots addon for React is dependent on [react-test-renderer](https://github.com/facebook/react/tree/master/packages/react-test-renderer), but +[doesn't](#deps-issue) install it, so you need to install it separately. + +```sh +npm install --save-dev react-test-renderer +``` + +### Configure Jest for Angular +StoryShots addon for Angular is dependent on [jest-preset-angular](https://github.com/thymikee/jest-preset-angular), but +[doesn't](#deps-issue) install it, so you need to install it separately. + +```sh +npm install --save-dev jest-preset-angular +``` + +If you already use Jest for testing your angular app - probably you already have the needed jest configuration. +Anyway you can add these lines to your jest config: +```js +module.exports = { + globals: { + __TRANSFORM_HTML__: true, + }, + transform: { + '^.+\\.jsx?$': 'babel-jest', + '^.+\\.(ts|html)$': '/node_modules/jest-preset-angular/preprocessor.js', + }, + moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node', '.html'], +}; +``` +### Configure Jest for Vue +StoryShots addon for Vue is dependent on [jest-vue-preprocessor](https://github.com/vire/jest-vue-preprocessor), but +[doesn't](#deps-issue) install it, so you need to install it separately. + + ```sh + npm install --save-dev jest-vue-preprocessor + ``` + +If you already use Jest for testing your vue app - probably you already have the needed jest configuration. +Anyway you can add these lines to your jest config: +```js +module.exports = { + transform: { + '^.+\\.jsx?$': 'babel-jest', + '.*\\.(vue)$': '/node_modules/jest-vue-preprocessor', + }, + transformIgnorePatterns: [ + '/node_modules/(?!(@storybook/.*\\.vue$))', + ], + moduleFileExtensions: ['vue', 'js', 'jsx', 'json', 'node'], +}; +``` + +### Why don't we install dependencies of each framework ? +Storyshots addon is currently supporting React, Angular and Vue. Each framework needs its own packages to be integrated with Jest. We don't want people that use only React will need to bring other dependencies that do not make sense for them. + +`dependencies` - will installed an exact version of the particular dep - Storyshots can work with different versions of the same framework (let's say React v16 and React v15), that have to be compatible with a version of its plugin (react-test-renderer). + +`optionalDependencies` - behaves like a regular dependency, but do not fail the installation in case there is a problem to bring the dep. + +`peerDependencies` - listing all the deps in peer will trigger warnings during the installation - we don't want users to install unneeded deps by hand. + +`optionalPeerDependencies` - unfortunately there is nothing like this =( + +For more information read npm [docs](https://docs.npmjs.com/files/package.json#dependencies) + +## Configure Storyshots for HTML snapshots + +Create a new test file with the name `Storyshots.test.js`. (Or whatever the name you prefer, as long as it matches Jest's config [`testMatch`](http://facebook.github.io/jest/docs/en/configuration.html#testmatch-array-string)). +Then add following content to it: + +```js +import initStoryshots from '@storybook/addon-storyshots'; + +initStoryshots(); +``` + +That's all. + +Now run your Jest test command. (Usually, `npm test`.) Then you can see all of your stories are converted as Jest snapshot tests. + +![Screenshot](docs/storyshots.png) + + +### Using `createNodeMock` to mock refs + +`react-test-renderer` doesn't provide refs for rendered components. By +default, it returns null when the refs are referenced. In order to mock +out elements that rely on refs, you will have to use the +`createNodeMock` option [added to React](https://reactjs.org/blog/2016/11/16/react-v15.4.0.html#mocking-refs-for-snapshot-testing) starting with version 15.4.0. + +Here is an example of how to specify the `createNodeMock` option in Storyshots: + +```js +import initStoryshots, { snapshotWithOptions } from '@storybook/addon-storyshots' +import TextareaThatUsesRefs from '../component/TextareaThatUsesRefs' + +initStoryshots({ + test: snapshotWithOptions({ + createNodeMock: (element) => { + if (element.type === TextareaThatUsesRefs) { + return document.createElement('textarea') + } + }, + }), +}) +``` + +## Options + +### `configPath` + +By default, Storyshots assumes the config directory path for your project as below: + +- Storybook for React: `.storybook` +- Storybook for React Native: `storybook` + +If you are using a different config directory path, you could change it like this: + +```js +import initStoryshots from '@storybook/addon-storyshots'; + +initStoryshots({ + configPath: '.my-storybook-config-dir' +}); +``` + +### `suite` + +By default, Storyshots groups stories inside a Jest test suite called "Storyshots". You could change it like this: + +```js +import initStoryshots from '@storybook/addon-storyshots'; + +initStoryshots({ + suite: 'MyStoryshots' +}); +``` + +### `storyKindRegex` + +If you'd like to only run a subset of the stories for your snapshot tests based on the story's kind: + +```js +import initStoryshots from '@storybook/addon-storyshots'; + +initStoryshots({ + storyKindRegex: /^MyComponent$/ +}); +``` + +This can be useful if you want to separate the snapshots in directories next to each component. See an example [here](https://github.com/storybooks/storybook/issues/892). + +If you want to run all stories except stories of a specific kind, you can write an inverse regex which is true for all kinds except those with a specific word such as `DontTest` + +```js +import initStoryshots from '@storybook/addon-storyshots'; + +initStoryshots({ + storyKindRegex:/^((?!.*?DontTest).)*$/ +}); +``` + +This can be useful while testing react components which make use of the findDomNode API since they always fail with snapshot testing +while using react-test-renderer see [here](https://github.com/facebook/react/issues/8324) + +### `storyNameRegex` + +If you'd like to only run a subset of the stories for your snapshot tests based on the story's name: + +```js +import initStoryshots from '@storybook/addon-storyshots'; + +initStoryshots({ + storyNameRegex: /buttons/ +}); +``` + +### `framework` + +If you are running tests from outside of your app's directory, storyshots' detection of which framework you are using may fail. Pass `"react"` or `"react-native"` to short-circuit this. + +### `test` + +Run a custom test function for each story, rather than the default (a vanilla snapshot test). Setting `test` will take precedence over the `renderer` option. See the exports section below for more details. + +### `renderer` + +Pass a custom renderer (such as enzymes `mount`) to record snapshots. Note that setting `test` overrides `renderer`. + +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { mount } from 'enzyme'; + +initStoryshots({ + renderer: mount, +}); +``` + +If you are using enzyme, you need to make sure jest knows how to serialize rendered components. +You can either pass in a serializer (see below) or specify an enzyme-compatible serializer (like [enzyme-to-json](https://github.com/adriantoine/enzyme-to-json), [jest-serializer-enzyme](https://github.com/rogeliog/jest-serializer-enzyme) etc.) as the default `snapshotSerializer` in your config. + +Example for jest config in `package.json`: +```json +"devDependencies": { + "enzyme-to-json": "^3.2.2" +}, +"jest": { + "snapshotSerializers": [ + "enzyme-to-json/serializer" + ] + } +``` + +### `serializer` + +Pass a custom serializer (such as enzyme-to-json) to serialize components to snapshot-comparable data. + +```js +import initStoryshots from '@storybook/addon-storyshots'; +import toJSON from 'enzyme-to-json'; + +initStoryshots({ + renderer: mount, + serializer: toJSON, +}); +``` + +This option only needs to be set if the default `snapshotSerializers` is not set in your jest config. + +## Exports + +Apart from the default export (`initStoryshots`), Storyshots also exports some named test functions (see the `test` option above): + +### `snapshot` + +The default, render the story as normal and take a Jest snapshot. + +### `renderOnly` + +Just render the story, don't check the output at all (useful if you just want to ensure it doesn't error) + +### `snapshotWithOptions(options)` + +Like the default, but allows you to specify a set of options for the test renderer. [See for example here](https://github.com/storybooks/storybook/blob/b915b5439786e0edb17d7f5ab404bba9f7919381/examples/test-cra/src/storyshots.test.js#L14-L16). + +### `renderWithOptions(options)` + +Like the default, but allows you to specify a set of options for the renderer. See above. + +### `multiSnapshotWithOptions(options)` + +Like `snapshotWithOptions`, but generate a separate snapshot file for each stories file rather than a single monolithic file (as is the convention in Jest). This makes it dramatically easier to review changes. If you'd like the benefit of separate snapshot files, but don't have custom options to pass, simply pass an empty object. + +#### integrityOptions +This option is useful when running test with `multiSnapshotWithOptions(options)` in order to track snapshots are matching the stories. (disabled by default). +The value is just a [settings](https://github.com/isaacs/node-glob#options) to a `glob` object, that searches for the snapshot files. + +```js +initStoryshots({ + integrityOptions: { cwd: __dirname }, // it will start searching from the current directory + test: multiSnapshotWithOptions({}), +}); +``` + +### `shallowSnapshot` + +Take a snapshot of a shallow-rendered version of the component. Note that this option will be overriden if you pass a `renderer` option. + +### `getSnapshotFileName` + +Utility function used in `multiSnapshotWithOptions`. This is made available for users who implement custom test functions that also want to take advantage of multi-file storyshots. + +###### Example: + +Let's say we wanted to create a test function for shallow && multi-file snapshots: + +```js +import initStoryshots, { getSnapshotFileName } from '@storybook/addon-storyshots'; +import { shallow } from 'enzyme'; +import toJson from 'enzyme-to-json'; + +initStoryshots({ + test: ({ story, context }) => { + const snapshotFileName = getSnapshotFileName(context); + const storyElement = story.render(context); + const shallowTree = shallow(storyElement); + + if (snapshotFileName) { + expect(toJson(shallowTree)).toMatchSpecificSnapshot(snapshotFileName); + } + } +}); +``` diff --git a/addons/storyshots/docs/storyshots-fail.png b/addons/storyshots/storyshots-core/docs/storyshots-fail.png similarity index 100% rename from addons/storyshots/docs/storyshots-fail.png rename to addons/storyshots/storyshots-core/docs/storyshots-fail.png diff --git a/addons/storyshots/docs/storyshots.png b/addons/storyshots/storyshots-core/docs/storyshots.png similarity index 100% rename from addons/storyshots/docs/storyshots.png rename to addons/storyshots/storyshots-core/docs/storyshots.png diff --git a/addons/storyshots/package.json b/addons/storyshots/storyshots-core/package.json similarity index 90% rename from addons/storyshots/package.json rename to addons/storyshots/storyshots-core/package.json index f028488b431f..81a41c6ec16b 100644 --- a/addons/storyshots/package.json +++ b/addons/storyshots/storyshots-core/package.json @@ -18,13 +18,10 @@ "dependencies": { "@storybook/addons": "4.0.0-alpha.8", "@storybook/core": "4.0.0-alpha.8", - "@storybook/node-logger": "4.0.0-alpha.8", "babel-runtime": "^6.26.0", "glob": "^7.1.2", "global": "^4.3.2", - "jest-image-snapshot": "^2.4.2", "jest-specific-snapshot": "^0.5.0", - "puppeteer": "^1.4.0", "read-pkg-up": "^3.0.0" }, "devDependencies": { diff --git a/addons/storyshots/src/angular/app.component.ts b/addons/storyshots/storyshots-core/src/angular/app.component.ts similarity index 100% rename from addons/storyshots/src/angular/app.component.ts rename to addons/storyshots/storyshots-core/src/angular/app.component.ts diff --git a/addons/storyshots/src/angular/app.token.ts b/addons/storyshots/storyshots-core/src/angular/app.token.ts similarity index 100% rename from addons/storyshots/src/angular/app.token.ts rename to addons/storyshots/storyshots-core/src/angular/app.token.ts diff --git a/addons/storyshots/src/angular/helpers.ts b/addons/storyshots/storyshots-core/src/angular/helpers.ts similarity index 100% rename from addons/storyshots/src/angular/helpers.ts rename to addons/storyshots/storyshots-core/src/angular/helpers.ts diff --git a/addons/storyshots/src/angular/loader.js b/addons/storyshots/storyshots-core/src/angular/loader.js similarity index 100% rename from addons/storyshots/src/angular/loader.js rename to addons/storyshots/storyshots-core/src/angular/loader.js diff --git a/addons/storyshots/src/angular/renderTree.js b/addons/storyshots/storyshots-core/src/angular/renderTree.js similarity index 100% rename from addons/storyshots/src/angular/renderTree.js rename to addons/storyshots/storyshots-core/src/angular/renderTree.js diff --git a/addons/storyshots/src/angular/types.ts b/addons/storyshots/storyshots-core/src/angular/types.ts similarity index 100% rename from addons/storyshots/src/angular/types.ts rename to addons/storyshots/storyshots-core/src/angular/types.ts diff --git a/addons/storyshots/src/config-loader.js b/addons/storyshots/storyshots-core/src/config-loader.js similarity index 100% rename from addons/storyshots/src/config-loader.js rename to addons/storyshots/storyshots-core/src/config-loader.js diff --git a/addons/storyshots/src/frameworkLoader.js b/addons/storyshots/storyshots-core/src/frameworkLoader.js similarity index 100% rename from addons/storyshots/src/frameworkLoader.js rename to addons/storyshots/storyshots-core/src/frameworkLoader.js diff --git a/addons/storyshots/src/getIntegrityOptions.js b/addons/storyshots/storyshots-core/src/getIntegrityOptions.js similarity index 100% rename from addons/storyshots/src/getIntegrityOptions.js rename to addons/storyshots/storyshots-core/src/getIntegrityOptions.js diff --git a/addons/storyshots/src/hasDependency.js b/addons/storyshots/storyshots-core/src/hasDependency.js similarity index 100% rename from addons/storyshots/src/hasDependency.js rename to addons/storyshots/storyshots-core/src/hasDependency.js diff --git a/addons/storyshots/src/html/loader.js b/addons/storyshots/storyshots-core/src/html/loader.js similarity index 100% rename from addons/storyshots/src/html/loader.js rename to addons/storyshots/storyshots-core/src/html/loader.js diff --git a/addons/storyshots/src/html/renderTree.js b/addons/storyshots/storyshots-core/src/html/renderTree.js similarity index 100% rename from addons/storyshots/src/html/renderTree.js rename to addons/storyshots/storyshots-core/src/html/renderTree.js diff --git a/addons/storyshots/src/index.js b/addons/storyshots/storyshots-core/src/index.js similarity index 97% rename from addons/storyshots/src/index.js rename to addons/storyshots/storyshots-core/src/index.js index 6296e2151f0c..cce8f0b8acca 100644 --- a/addons/storyshots/src/index.js +++ b/addons/storyshots/storyshots-core/src/index.js @@ -5,7 +5,6 @@ import addons, { mockChannel } from '@storybook/addons'; import loadFramework from './frameworkLoader'; import getIntegrityOptions from './getIntegrityOptions'; import { getPossibleStoriesFiles, getSnapshotFileName } from './utils'; -import { imageSnapshot } from './test-body-image-snapshot'; import { multiSnapshotWithOptions, @@ -26,7 +25,6 @@ export { shallowSnapshot, renderOnly, renderWithOptions, - imageSnapshot, }; const methods = ['beforeAll', 'beforeEach', 'afterEach', 'afterAll']; diff --git a/addons/storyshots/src/react/loader.js b/addons/storyshots/storyshots-core/src/react/loader.js similarity index 100% rename from addons/storyshots/src/react/loader.js rename to addons/storyshots/storyshots-core/src/react/loader.js diff --git a/addons/storyshots/src/react/renderShallowTree.js b/addons/storyshots/storyshots-core/src/react/renderShallowTree.js similarity index 100% rename from addons/storyshots/src/react/renderShallowTree.js rename to addons/storyshots/storyshots-core/src/react/renderShallowTree.js diff --git a/addons/storyshots/src/react/renderTree.js b/addons/storyshots/storyshots-core/src/react/renderTree.js similarity index 100% rename from addons/storyshots/src/react/renderTree.js rename to addons/storyshots/storyshots-core/src/react/renderTree.js diff --git a/addons/storyshots/src/require_context.js b/addons/storyshots/storyshots-core/src/require_context.js similarity index 100% rename from addons/storyshots/src/require_context.js rename to addons/storyshots/storyshots-core/src/require_context.js diff --git a/addons/storyshots/src/rn/loader.js b/addons/storyshots/storyshots-core/src/rn/loader.js similarity index 100% rename from addons/storyshots/src/rn/loader.js rename to addons/storyshots/storyshots-core/src/rn/loader.js diff --git a/addons/storyshots/src/test-bodies.js b/addons/storyshots/storyshots-core/src/test-bodies.js similarity index 100% rename from addons/storyshots/src/test-bodies.js rename to addons/storyshots/storyshots-core/src/test-bodies.js diff --git a/addons/storyshots/src/utils.js b/addons/storyshots/storyshots-core/src/utils.js similarity index 100% rename from addons/storyshots/src/utils.js rename to addons/storyshots/storyshots-core/src/utils.js diff --git a/addons/storyshots/src/utils.test.js b/addons/storyshots/storyshots-core/src/utils.test.js similarity index 100% rename from addons/storyshots/src/utils.test.js rename to addons/storyshots/storyshots-core/src/utils.test.js diff --git a/addons/storyshots/src/vue/loader.js b/addons/storyshots/storyshots-core/src/vue/loader.js similarity index 100% rename from addons/storyshots/src/vue/loader.js rename to addons/storyshots/storyshots-core/src/vue/loader.js diff --git a/addons/storyshots/src/vue/renderTree.js b/addons/storyshots/storyshots-core/src/vue/renderTree.js similarity index 100% rename from addons/storyshots/src/vue/renderTree.js rename to addons/storyshots/storyshots-core/src/vue/renderTree.js diff --git a/addons/storyshots/stories/__snapshots__/storyshot.enzyme.test.js.snap b/addons/storyshots/storyshots-core/stories/__snapshots__/storyshot.enzyme.test.js.snap similarity index 100% rename from addons/storyshots/stories/__snapshots__/storyshot.enzyme.test.js.snap rename to addons/storyshots/storyshots-core/stories/__snapshots__/storyshot.enzyme.test.js.snap diff --git a/addons/storyshots/stories/__snapshots__/storyshot.shallow.test.js.snap b/addons/storyshots/storyshots-core/stories/__snapshots__/storyshot.shallow.test.js.snap similarity index 100% rename from addons/storyshots/stories/__snapshots__/storyshot.shallow.test.js.snap rename to addons/storyshots/storyshots-core/stories/__snapshots__/storyshot.shallow.test.js.snap diff --git a/addons/storyshots/stories/__snapshots__/storyshot.shallowWithOptions.test.js.snap b/addons/storyshots/storyshots-core/stories/__snapshots__/storyshot.shallowWithOptions.test.js.snap similarity index 100% rename from addons/storyshots/stories/__snapshots__/storyshot.shallowWithOptions.test.js.snap rename to addons/storyshots/storyshots-core/stories/__snapshots__/storyshot.shallowWithOptions.test.js.snap diff --git a/addons/storyshots/stories/directly_required/__snapshots__/index.storyshot b/addons/storyshots/storyshots-core/stories/directly_required/__snapshots__/index.storyshot similarity index 100% rename from addons/storyshots/stories/directly_required/__snapshots__/index.storyshot rename to addons/storyshots/storyshots-core/stories/directly_required/__snapshots__/index.storyshot diff --git a/addons/storyshots/stories/directly_required/index.js b/addons/storyshots/storyshots-core/stories/directly_required/index.js similarity index 100% rename from addons/storyshots/stories/directly_required/index.js rename to addons/storyshots/storyshots-core/stories/directly_required/index.js diff --git a/addons/storyshots/stories/required_with_context/Button.stories.js b/addons/storyshots/storyshots-core/stories/required_with_context/Button.stories.js similarity index 100% rename from addons/storyshots/stories/required_with_context/Button.stories.js rename to addons/storyshots/storyshots-core/stories/required_with_context/Button.stories.js diff --git a/addons/storyshots/stories/required_with_context/Welcome.stories.js b/addons/storyshots/storyshots-core/stories/required_with_context/Welcome.stories.js similarity index 100% rename from addons/storyshots/stories/required_with_context/Welcome.stories.js rename to addons/storyshots/storyshots-core/stories/required_with_context/Welcome.stories.js diff --git a/addons/storyshots/stories/required_with_context/__snapshots__/Button.stories.storyshot b/addons/storyshots/storyshots-core/stories/required_with_context/__snapshots__/Button.stories.storyshot similarity index 100% rename from addons/storyshots/stories/required_with_context/__snapshots__/Button.stories.storyshot rename to addons/storyshots/storyshots-core/stories/required_with_context/__snapshots__/Button.stories.storyshot diff --git a/addons/storyshots/stories/required_with_context/__snapshots__/Welcome.stories.storyshot b/addons/storyshots/storyshots-core/stories/required_with_context/__snapshots__/Welcome.stories.storyshot similarity index 100% rename from addons/storyshots/stories/required_with_context/__snapshots__/Welcome.stories.storyshot rename to addons/storyshots/storyshots-core/stories/required_with_context/__snapshots__/Welcome.stories.storyshot diff --git a/addons/storyshots/stories/storyshot.enzyme.test.js b/addons/storyshots/storyshots-core/stories/storyshot.enzyme.test.js similarity index 100% rename from addons/storyshots/stories/storyshot.enzyme.test.js rename to addons/storyshots/storyshots-core/stories/storyshot.enzyme.test.js diff --git a/addons/storyshots/stories/storyshot.renderOnly.test.js b/addons/storyshots/storyshots-core/stories/storyshot.renderOnly.test.js similarity index 100% rename from addons/storyshots/stories/storyshot.renderOnly.test.js rename to addons/storyshots/storyshots-core/stories/storyshot.renderOnly.test.js diff --git a/addons/storyshots/stories/storyshot.renderWithOptions.test.js b/addons/storyshots/storyshots-core/stories/storyshot.renderWithOptions.test.js similarity index 100% rename from addons/storyshots/stories/storyshot.renderWithOptions.test.js rename to addons/storyshots/storyshots-core/stories/storyshot.renderWithOptions.test.js diff --git a/addons/storyshots/stories/storyshot.shallow.test.js b/addons/storyshots/storyshots-core/stories/storyshot.shallow.test.js similarity index 100% rename from addons/storyshots/stories/storyshot.shallow.test.js rename to addons/storyshots/storyshots-core/stories/storyshot.shallow.test.js diff --git a/addons/storyshots/stories/storyshot.shallowWithOptions.test.js b/addons/storyshots/storyshots-core/stories/storyshot.shallowWithOptions.test.js similarity index 100% rename from addons/storyshots/stories/storyshot.shallowWithOptions.test.js rename to addons/storyshots/storyshots-core/stories/storyshot.shallowWithOptions.test.js diff --git a/addons/storyshots/stories/storyshot.test.js b/addons/storyshots/storyshots-core/stories/storyshot.test.js similarity index 100% rename from addons/storyshots/stories/storyshot.test.js rename to addons/storyshots/storyshots-core/stories/storyshot.test.js diff --git a/addons/storyshots/tsconfig.json b/addons/storyshots/storyshots-core/tsconfig.json similarity index 75% rename from addons/storyshots/tsconfig.json rename to addons/storyshots/storyshots-core/tsconfig.json index 84fb13689add..4dfc8c494582 100644 --- a/addons/storyshots/tsconfig.json +++ b/addons/storyshots/storyshots-core/tsconfig.json @@ -1,5 +1,5 @@ { - "extends": "../../tsconfig.json", + "extends": "../../../tsconfig.json", "include": [ "src/**/*.ts" ], diff --git a/addons/storyshots/storyshots-puppeteer/README.md b/addons/storyshots/storyshots-puppeteer/README.md new file mode 100644 index 000000000000..8ad279995720 --- /dev/null +++ b/addons/storyshots/storyshots-puppeteer/README.md @@ -0,0 +1,154 @@ +## Configure Storyshots for image snapshots ( alpha ) + +/*\ **React-native** is **not supported** by this test function. + +Internally, it uses [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot). + +When willing to generate and compare image snapshots for your stories, you have two options: +- Have a storybook running (ie. accessible via http(s), for instance using `yarn run storybook`) +- Have a static build of the storybook (for instance, using `yarn run build-storybook`) + +Then you will need to reference the storybook URL (`file://...` if local, `http(s)://...` if served) + +### Using default values for _imageSnapshots_ + +Then you can either create a new Storyshots instance or edit the one you previously used: +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; + +initStoryshots({suite: 'Image storyshots', test: imageSnapshot()}); +``` +This will assume you have a storybook running on at __. +Internally here are the steps: +- Launches a Chrome headless using [puppeteer](https://github.com/GoogleChrome/puppeteer) +- Browses each stories (calling __ URL), +- Take screenshots & save all images under _\_image_snapshots\__ folder. + +### Specifying the storybook URL + +If you want to set specific storybook URL, you can specify via the `storybookUrl` parameter, see below: +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; + +initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://my-specific-domain.com:9010'})}); +``` +The above config will use __ for screenshots. + + +You may also use a local static build of storybook if you do not want to run the webpack dev-server: +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; + +initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'file:///path/to/my/storybook-static'})}); +``` + +### Specifying options to _jest-image-snapshots_ + +If you wish to customize [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot), then you can provide a `getMatchOptions` parameter that should return the options config object. Additionally, you can provide `beforeScreenshot` which is called before the screenshot is captured. +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; +const getMatchOptions = ({context : {kind, story}, url}) => { + return { + failureThreshold: 0.2, + failureThresholdType: 'percent', + } +} +const beforeScreenshot = (page, {context : {kind, story}, url}) => { + return new Promise(resolve => + setTimeout(() => { + resolve(); + }, 600) + ) +} +initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', getMatchOptions, beforeScreenshot})}); +``` +`getMatchOptions` receives an object: `{ context: {kind, story}, url}`. _kind_ is the kind of the story and the _story_ its name. _url_ is the URL the browser will use to screenshot. + +`beforeScreenshot` receives the [Puppeteer page instance](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-page) and an object: `{ context: {kind, story}, url}`. _kind_ is the kind of the story and the _story_ its name. _url_ is the URL the browser will use to screenshot. `beforeScreenshot` is part of the promise chain and is called after the browser navigation is completed but before the screenshot is taken. It allows for triggering events on the page elements and delaying the screenshot and can be used avoid regressions due to mounting animations. + +### Specifying options to _goto()_ (puppeteer API) + +You might use `getGotoOptions` to specify options when the storybook is navigating to a story (using the `goto` method). Will be passed to [Puppeteer .goto() fn](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options) + +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; +const getGotoOptions = ({context, url}) => { + return { + waitUntil: 'networkidle0', + } +} +initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', getGotoOptions})}); +``` +### Specifying options to _screenshot()_ (puppeteer API) + +You might use `getScreenshotOptions` to specify options for screenshot. Will be passed to [Puppeteer .screenshot() fn](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagescreenshotoptions) + +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; +const getScreenshotOptions = ({context, url}) { + return { + fullPage: false // Do not take the full page screenshot. Default is 'true' in Storyshots. + } +} +initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', getScreenshotOptions})}); +``` + +`getScreenshotOptions` receives an object `{ context: {kind, story}, url}`. _kind_ is the kind of the story and the _story_ its name. _url_ is the URL the browser will use to screenshot. + +### Specifying custom Chrome executable path (puppeteer API) + +You might use `chromeExecutablePath` to specify the path to a different version of Chrome, without downloading Chromium. Will be passed to [Runs a bundled version of Chromium](https://github.com/GoogleChrome/puppeteer#default-runtime-settings) + +```js +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; + +const chromeExecutablePath = '/usr/local/bin/chrome'; + +initStoryshots({suite: 'Image storyshots', test: imageSnapshot({storybookUrl: 'http://localhost:6006', chromeExecutablePath})}); +``` + +### Integrate image storyshots with regular app + +You may want to use another Jest project to run your image snapshots as they require more resources: Chrome and Storybook built/served. +You can find a working example of this in the [official-storybook](https://github.com/storybooks/storybook/tree/master/examples/official-storybook) example. + +### Integrate image storyshots with [Create React App](https://github.com/facebookincubator/create-react-app) + +You have two options here, you can either: + +- Simply add the storyshots configuration inside any of your `test.js` file. You must ensure you have either a running storybook or a static build available. + +- Create a custom test file using Jest outside of the CRA scope: + + A more robust approach would be to separate existing test files ran by create-react-app (anything `(test|spec).js` suffixed files) from the test files to run storyshots with image snapshots. + This use case can be achieved by using a custom name for the test file, ie something like `image-storyshots.runner.js`. This file will contains the `initStoryshots` call with image snapshots configuration. + Then you will create a separate script entry in your package.json, for instance + ```json + { + "scripts": { + "image-snapshots" : "jest image-storyshots.runner.js --config path/to/custom/jest.config.json" + } + } + ``` + Note that you will certainly need a custom config file for Jest as you run it outside of the CRA scope and thus you do not have the built-in config. + + Once that's setup, you can run `yarn run image-snapshots` (or `npm run image-snapshots`). + +### Reminder + +An image snapshot is simply a screenshot taken by a web browser (in our case, Chrome). + +The browser opens a page (either using the static build of storybook or a running instance of Storybook) + +If you run your test without either the static build or a running instance, this wont work. + +To make sure your screenshots are taken from latest changes of your Storybook, you must keep your static build or running Storybook up-to-date. +This can be achieved by adding a step before running the test ie: `yarn run build-storybook && yarn run image-snapshots`. +If you run the image snapshots against a running Storybook in dev mode, you don't have to care about being up-to-date because the dev-server is watching changes and rebuilds automatically. \ No newline at end of file diff --git a/addons/storyshots/storyshots-puppeteer/package.json b/addons/storyshots/storyshots-puppeteer/package.json new file mode 100644 index 000000000000..cd5ee06b6f6e --- /dev/null +++ b/addons/storyshots/storyshots-puppeteer/package.json @@ -0,0 +1,23 @@ +{ + "name": "@storybook/addon-storyshots-puppeteer", + "version": "4.0.0-alpha.8", + "description": "Image snappshots addition to StoryShots base on puppeteer", + "repository": { + "type": "git", + "url": "https://github.com/storybooks/storybook.git" + }, + "license": "MIT", + "main": "dist/index.js", + "jsnext:main": "src/index.js", + "scripts": { + "prepare": "node ../../../scripts/prepare.js" + }, + "dependencies": { + "@storybook/node-logger": "4.0.0-alpha.8", + "jest-image-snapshot": "^2.4.2", + "puppeteer": "^1.4.0" + }, + "peerDependencies": { + "@storybook/addon-storyshots": "4.0.0-alpha.8" + } +} diff --git a/addons/storyshots/src/test-body-image-snapshot.js b/addons/storyshots/storyshots-puppeteer/src/index.js similarity index 100% rename from addons/storyshots/src/test-body-image-snapshot.js rename to addons/storyshots/storyshots-puppeteer/src/index.js diff --git a/examples/official-storybook/image-snapshots/storyshots-image.runner.js b/examples/official-storybook/image-snapshots/storyshots-image.runner.js index 775058ba109f..ee2e65e183f0 100644 --- a/examples/official-storybook/image-snapshots/storyshots-image.runner.js +++ b/examples/official-storybook/image-snapshots/storyshots-image.runner.js @@ -4,7 +4,8 @@ * */ import path from 'path'; import fs from 'fs'; -import initStoryshots, { imageSnapshot } from '@storybook/addon-storyshots'; +import initStoryshots from '@storybook/addon-storyshots'; +import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer'; import { logger } from '@storybook/node-logger'; // Image snapshots diff --git a/examples/official-storybook/package.json b/examples/official-storybook/package.json index 0ef0424eb842..4f86be89fb1d 100644 --- a/examples/official-storybook/package.json +++ b/examples/official-storybook/package.json @@ -25,6 +25,7 @@ "@storybook/addon-notes": "4.0.0-alpha.8", "@storybook/addon-options": "4.0.0-alpha.8", "@storybook/addon-storyshots": "4.0.0-alpha.8", + "@storybook/addon-storyshots-puppeteer": "4.0.0-alpha.8", "@storybook/addon-storysource": "4.0.0-alpha.8", "@storybook/addon-viewport": "4.0.0-alpha.8", "@storybook/addons": "4.0.0-alpha.8", diff --git a/package.json b/package.json index 9be7cc792912..e47898ffe7f6 100644 --- a/package.json +++ b/package.json @@ -156,6 +156,7 @@ }, "workspaces": [ "addons/*", + "addons/storyshots/*", "app/*", "lib/*", "examples/marko-cli", From 77998b803f4aae5eb641f89c2f19bb25f069b5e1 Mon Sep 17 00:00:00 2001 From: igor-dv Date: Sun, 10 Jun 2018 14:38:38 +0300 Subject: [PATCH 2/6] minor --- addons/storyshots/README.md | 4 ++-- addons/storyshots/storyshots-core/package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/addons/storyshots/README.md b/addons/storyshots/README.md index d886a7ff693a..7c511fa0ab31 100644 --- a/addons/storyshots/README.md +++ b/addons/storyshots/README.md @@ -2,5 +2,5 @@ TBD -*addon-storyshots -*addon-storyshots-puppeteer +- addon-storyshots +- addon-storyshots-puppeteer diff --git a/addons/storyshots/storyshots-core/package.json b/addons/storyshots/storyshots-core/package.json index 81a41c6ec16b..38c36d164373 100644 --- a/addons/storyshots/storyshots-core/package.json +++ b/addons/storyshots/storyshots-core/package.json @@ -12,7 +12,7 @@ "scripts": { "build-storybook": "build-storybook", "example": "jest storyshot.test", - "prepare": "node ../../scripts/prepare.js", + "prepare": "node ../../../scripts/prepare.js", "storybook": "start-storybook -p 6006" }, "dependencies": { From 4af0f09e9786d853488143a6ab62a88eeb87d260 Mon Sep 17 00:00:00 2001 From: igor-dv Date: Sun, 10 Jun 2018 15:03:30 +0300 Subject: [PATCH 3/6] Use $LERNA_ROOT_PATH in the build-packs script --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index e47898ffe7f6..bcdae335f10e 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "bootstrap:docs": "yarn install --cwd docs", "bootstrap:react-native-vanilla": "npm --prefix examples/react-native-vanilla install", "bootstrap:react-native-typescript": "npm --prefix examples/react-native-typescript install", - "build-packs": "lerna exec --scope '@storybook/*' --parallel -- ../../scripts/build-pack.sh ../../packs", + "build-packs": "lerna exec --scope '@storybook/*' --parallel -- \\$LERNA_ROOT_PATH/scripts/build-pack.sh \\$LERNA_ROOT_PATH/packs", "build-storybooks": "./scripts/build-storybooks.sh", "changelog": "pr-log --sloppy", "precommit": "lint-staged", From a87798b2dcc5b9be7cb9365b575f3fa3dbcb9049 Mon Sep 17 00:00:00 2001 From: igor-dv Date: Sun, 10 Jun 2018 16:42:39 +0300 Subject: [PATCH 4/6] Common storyshots README.md improvements --- addons/storyshots/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/addons/storyshots/README.md b/addons/storyshots/README.md index 7c511fa0ab31..fa102d2950dc 100644 --- a/addons/storyshots/README.md +++ b/addons/storyshots/README.md @@ -1,6 +1,4 @@ # StoryShots -TBD - -- addon-storyshots -- addon-storyshots-puppeteer +- [addon-storyshots](addon-storyshots) - Basic StoryShots api +- [addon-storyshots-puppeteer](addon-storyshots-puppeteer) - Image Snapshots addition to StoryShots based on [puppeteer](https://github.com/GoogleChrome/puppeteer) From 93682870435b8edd7442b20383c6b0d28adfab19 Mon Sep 17 00:00:00 2001 From: igor-dv Date: Sun, 10 Jun 2018 16:43:58 +0300 Subject: [PATCH 5/6] Common storyshots README.md improvements --- addons/storyshots/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/addons/storyshots/README.md b/addons/storyshots/README.md index fa102d2950dc..c6d792f1cd7b 100644 --- a/addons/storyshots/README.md +++ b/addons/storyshots/README.md @@ -1,4 +1,4 @@ # StoryShots -- [addon-storyshots](addon-storyshots) - Basic StoryShots api -- [addon-storyshots-puppeteer](addon-storyshots-puppeteer) - Image Snapshots addition to StoryShots based on [puppeteer](https://github.com/GoogleChrome/puppeteer) +- [addon-storyshots](storyshots-core) - Basic StoryShots api +- [addon-storyshots-puppeteer](storyshots-puppeteer) - Image Snapshots addition to StoryShots based on [puppeteer](https://github.com/GoogleChrome/puppeteer) From 93c5f24306374f189b3ac7d057e503737124ce88 Mon Sep 17 00:00:00 2001 From: igor-dv Date: Sun, 10 Jun 2018 18:53:23 +0300 Subject: [PATCH 6/6] try to refresh the cache of the core-dependencies --- .circleci/config.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 906cc5061d4f..e26b5d786537 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -30,7 +30,7 @@ jobs: yarn bootstrap --core - save_cache: name: "Cache core dependencies" - key: core-dependencies-{{ checksum "yarn.lock" }} + key: core-dependencies-v2-{{ checksum "yarn.lock" }} paths: - node_modules - examples/angular-cli/node_modules @@ -53,7 +53,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore core dist cache" keys: @@ -104,7 +104,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore core dist cache" keys: @@ -147,7 +147,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore core dist cache" keys: @@ -206,7 +206,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore docs dependencies cache" keys: @@ -226,7 +226,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore core dist cache" keys: @@ -247,7 +247,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore core dist cache" keys: @@ -267,7 +267,7 @@ jobs: - restore_cache: name: "Restore core dependencies cache" keys: - - core-dependencies-{{ checksum "yarn.lock" }} + - core-dependencies-v2-{{ checksum "yarn.lock" }} - restore_cache: name: "Restore core dist cache" keys: