### Setup Project Dependencies for Storycap

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Initial setup steps to install project dependencies using `yarn --frozen-lockfile` and then bootstrap Lerna packages with `yarn bootstrap` after cloning the repository. This prepares the monorepo for development.

```sh
$ yarn --frozen-lockfile
$ yarn bootstrap
```

--------------------------------

### Replace zisui dependency with storycap

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Instructions to uninstall `zisui` and install `storycap` using npm.

```sh
$ npm uninstall zisui
$ npm install storycap
```

--------------------------------

### Run React Development Server with npm start

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-managed-react/README.md

Starts the React application in development mode, making it accessible via a local server (http://localhost:3000). The page automatically reloads on code changes, and lint errors are displayed in the console.

```Shell
npm start
```

--------------------------------

### Replace storybook-chrome-screenshot dependency with storycap

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Instructions to uninstall `storybook-chrome-screenshot` and install `storycap` using npm, followed by updating the Storybook addons registration file to reflect the new dependency.

```sh
$ npm uninstall storybook-chrome-screenshot
$ npm install storycap
```

```js
/* .storybook/addons.js */

//import 'storybook-chrome-screenshot/register';
import 'storycap/register';
```

--------------------------------

### Run React App in Development Mode with npm start

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-simple-react/README.md

This command starts the React application in development mode, making it accessible via a local server. It enables live reloading on code changes and displays lint errors in the console.

```Shell
npm start
```

--------------------------------

### Update CLI usage for storycap from storybook-chrome-screenshot

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Shows the updated command-line interface usage for `storycap`, including how to specify the Storybook URL and boot a local server using the `--serverCmd` option, replacing the older `storybook-chrome-screenshot` CLI arguments.

```sh
# Before
$ storybook-chrome-screenshot -p 8080 -h localhost -s ./public
```

```sh
# After
$ storycap http://localhost:8080 --serverCmd "start-storybook -p 8080 -h localhost -s ./public"
```

--------------------------------

### Run React App in Development Mode with npm start

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-managed-react/README.md

This command starts the React development server, making the application accessible locally. It provides live reloading on code changes and displays lint errors directly in the console.

```Shell
npm start
```

--------------------------------

### Run Storycap with server command

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Launch your Storybook server using the `--serverCmd` option, allowing Storycap to automatically start and then capture screenshots from the specified URL.

```sh
$ storycap --serverCmd "start-storybook -p 9001" http://localhost:9001
```

--------------------------------

### Run End-to-End Tests for a Single Storybook Example

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Executes end-to-end tests specifically for a designated Storybook example. This command is useful for isolating and debugging issues related to a particular Storybook configuration or component.

```sh
./e2e.sh examples/v4-simple
```

--------------------------------

### Run React App in Development Mode with npm start

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-simple-react/README.md

This command starts the React application in development mode, making it accessible via a local server. It provides live reloading on code changes and displays lint errors directly in the console.

```Shell
npm start
```

--------------------------------

### Run React App in Development Mode with npm start

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-react18/README.md

This command starts the development server for a React application. It opens the app in the browser at http://localhost:3000 and provides live reloading on code edits, displaying lint errors in the console.

```Shell
npm start
```

--------------------------------

### Create Docker Base Image for Storycap with Node and Dependencies

Source: https://github.com/reg-viz/storycap/blob/master/README.md

This Dockerfile provides a base image for running Storycap, starting from Node.js 18. It installs essential system dependencies required for browser automation and screenshot generation, such as various `lib` packages, `ca-certificates`, and `git`.

```dockerfile
FROM node:18

RUN apt-get update -y \
    && apt-get install -yq \
    ca-certificates \
    fonts-liberation \
    git \
    libayatana-appindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libc6 \
    libcairo2 \
    libcups2 \
    libdbus-1-3 \
    libexpat1 \
    libfontconfig1 \
    libgbm1 \
    libgcc1 \
    libglib2.0-0 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    libstdc++6 \
    libx11-6 \
    libx11-xcb1 \
    libxcb1 \
    libxcomposite1 \
    libxcursor1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxi6 \
    libxrandr2 \
    libxrender1 \
    libxss1 \
    libxtst6 \
    lsb-release \
    wget \
    xdg-utils
```

--------------------------------

### Install Storycap via npm

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Instructions to install Storycap using npm. Installing Puppeteer is optional, depending on whether you want Storycap to manage its own Chromium version or use an existing one.

```sh
$ npm install storycap
```

```sh
$ npm install storycap puppeteer
```

--------------------------------

### Launch React App Tests with npm test

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-managed-react/README.md

This command launches the test runner in an interactive watch mode, allowing developers to run tests and see results as code changes. It's based on the Create React App testing setup.

```Shell
npm test
```

--------------------------------

### Update CLI usage for storycap from zisui

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Explains that migrating from `zisui` to `storycap` in simple mode only requires changing the CLI command name, as all `zisui` CLI options are compatible with `storycap`.

```sh
# Before

$ zisui http://your.storybook.com
```

```sh
# After

$ storycap http://your.storybook.com
```

--------------------------------

### Deprecated screenshot options in withScreenshot

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Details changes to `withScreenshot` options, noting the deletion of `namespace` and `filePattern` fields, and the change for `viewport` to `viewports` for setting multiple viewports.

```APIDOC
- namespace field is deleted. If you want to add suffix to eace story, use defaultVariantSuffix
- filePattern field is deleted
- viewport field can't accepts Array. If you want set multiple viewports, use viewports field or --viewport CLI option
```

--------------------------------

### Launch React App Tests with npm test

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-simple-react/README.md

This command launches the test runner in interactive watch mode, allowing developers to run tests and see results as they make changes. It's part of the standard Create React App testing setup.

```Shell
npm test
```

--------------------------------

### Example Usage of Viewport with addParameters

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Demonstrates how to configure multiple named viewports within the `screenshot.viewports` field using `addParameters` in JavaScript, allowing for different screenshot dimensions for various devices.

```javascript
addParameters({
  screenshot: {
    viewports: {
      large: {
        width: 1024,
        height: 768,
      },
      small: {
        width: 375,
        height: 668,
      },
      xsmall: {
        width: 320,
        height: 568,
      },
    },
  },
});
```

--------------------------------

### Deprecated CLI options in storycap

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Lists deprecated CLI options from `storybook-chrome-screenshot` and their `storycap` equivalents, such as `--browser-timeout` replaced by `--serverTimeout` and `--filter-kind`/`--filter-story` by `--include`.

```APIDOC
- --browser-timeout: Use --serverTimeout instead of it
- --filter-kind, --filter-story: Use --include instead of them
```

--------------------------------

### Install Storycrawler with npm

Source: https://github.com/reg-viz/storycap/blob/master/packages/storycrawler/README.md

Installs the storycrawler package using npm, a package manager for JavaScript. This command adds the package to your project's dependencies, making it available for use in your applications.

```sh
$ npm i storycrawler
```

--------------------------------

### Update Storybook Addons for Storycap Migration

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

This snippet shows the initial step of migrating from 'zisui' to 'storycap' by updating the `addons.js` file in your Storybook configuration. It replaces the 'zisui/register' import with 'storycap/register' to enable Storycap's features.

```js
/* .storybook/addons.js */

import 'zisui/register';
```

```js
/* .storybook/addons.js */

import 'storycap/register';
```

--------------------------------

### Storycap Command Line Interface Options

Source: https://github.com/reg-viz/storycap/blob/master/README.md

This snippet provides a comprehensive list of all command-line arguments supported by the `storycap` tool. Each option includes its short form (if available), full name, data type, default value, and a brief description of its function. It also includes example usage scenarios for common tasks.

```APIDOC
usage: storycap [options] storybook_url

Options:
      --help                       Show help                                                                   [boolean]
      --version                    Show version number                                                         [boolean]
  -o, --outDir                     Output directory.                               [string] [default: "__screenshots__"]
  -p, --parallel                   Number of browsers to screenshot.                               [number] [default: 4]
  -f, --flat                       Flatten output filename.                                   [boolean] [default: false]
  -i, --include                    Including stories name rule.                                    [array] [default: []]
  -e, --exclude                    Excluding stories name rule.                                    [array] [default: []]
      --delay                      Waiting time [msec] before screenshot for each story.           [number] [default: 0]
  -V, --viewport                   Viewport.                                              [array] [default: ["800x600"]]
      --disableCssAnimation        Disable CSS animation and transition.                       [boolean] [default: true]
      --disableWaitAssets          Disable waiting for requested assets                       [boolean] [default: false]
      --trace                      Emit Chromium trace files per screenshot.                  [boolean] [default: false]
      --silent                                                                                [boolean] [default: false]
      --verbose                                                                               [boolean] [default: false]
      --forwardConsoleLogs         Forward in-page console logs to the user's console.        [boolean] [default: false]
      --serverCmd                  Command line to launch Storybook server.                       [string] [default: ""]
      --serverTimeout              Timeout [msec] for starting Storybook server.               [number] [default: 60000]
      --shard                      The sharding options for this run. In the format <shardNumber>/<totalShards>.
                                   <shardNumber> is a number between 1 and <totalShards>. <totalShards> is the total
                                   number of computers working.                                [string] [default: "1/1"]
      --captureTimeout             Timeout [msec] for capture a story.                          [number] [default: 5000]
      --captureMaxRetryCount       Number of count to retry to capture.                            [number] [default: 3]
      --metricsWatchRetryCount     Number of count to retry until browser metrics stable.       [number] [default: 1000]
      --viewportDelay              Delay time [msec] between changing viewport and capturing.    [number] [default: 300]
      --reloadAfterChangeViewport  Whether to reload after viewport changed.                  [boolean] [default: false]
      --stateChangeDelay           Delay time [msec] after changing element's state.               [number] [default: 0]
      --listDevices                List available device descriptors.                         [boolean] [default: false]
  -C, --chromiumChannel            Channel to search local Chromium. One of "puppeteer", "canary", "stable", "*"
                                                                                                 [string] [default: "*"]
      --chromiumPath               Executable Chromium path.                                      [string] [default: ""]
      --puppeteerLaunchConfig      JSON string of launch config for Puppeteer.
               [string] [default: "{ \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"] }"]

Examples:
  storycap http://localhost:9009
  storycap http://localhost:9009 -V 1024x768 -V 320x568
  storycap http://localhost:9009 -i "some-kind/a-story"
  storycap http://example.com/your-storybook -e "**/default" -V iPad
  storycap --serverCmd "start-storybook -p 3000" http://localhost:3000

```

--------------------------------

### Migrate global screenshot options from setScreenshotOptions to withScreenshot

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Explains how to move global screenshot options previously configured with `setScreenshotOptions` in `storybook-chrome-screenshot` to the `withScreenshot` decorator in `storycap`, as `setScreenshotOptions` is deprecated.

```js
/* Before */
/* .storybook/config.js */
import { setScreenshotOptions } from 'storybook-chrome-screenshot';

setScreenshotOptions({
  viewport: {
    width: 768,
    height: 400,
    deviceScaleFactor: 2,
  },
});
```

```js
/* After */
/* .storybook/config.js */
import { addDecorator } from '@storybook/react';
import { withScreenshot } from 'storycap';

addDecorator(
  withScreenshot({
    viewport: {
      width: 768,
      height: 400,
      deviceScaleFactor: 2,
    },
  }),
);
```

--------------------------------

### Update Storybook decorators from storybook-chrome-screenshot to storycap

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

Demonstrates how to remove the deprecated `initScreenshot` decorator and update `withScreenshot` imports and usage in `.storybook/config.js` and individual story files when migrating from `storybook-chrome-screenshot` to `storycap`.

```js
/* Before */
/* .storybook/config.js */

import { addDecorator } from '@storybook/react';
import { initScreenshot, withScreenshot } from 'storybook-chrome-screenshot';

addDecorator(initScreenshot());
addDecorator(
  withScreenshot({
    /* Some options... */
  }),
);
```

```js
/* After */
/* .storybook/config.js */

import { addDecorator } from '@storybook/react';
import { withScreenshot } from 'storycap';

addDecorator(
  withScreenshot({
    /* Some options... */
  }),
);
```

```js
import React from 'react';
import { storiesOf } from '@storybook/react';
// import { withScreenshot } from 'storybook-chrome-screenshot';
import { withScreenshot } from 'storycap'; // <-
import { Button } from './Button';

storiesOf('Button', module)
  .addDecorator(withScreenshot())
  .add('with default style', () => <Button>Default</Button>);
```

--------------------------------

### Launch React App Test Runner with npm test

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-react18/README.md

This command launches the test runner in an interactive watch mode, allowing developers to continuously run tests as code changes. It's part of the Create React App's testing setup.

```Shell
npm test
```

--------------------------------

### Update Storybook Config for Storycap withScreenshot

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

This snippet demonstrates the migration of the `withScreenshot` decorator in your Storybook `config.js` file. It updates the import path from 'zisui' to 'storycap' to ensure screenshot functionality uses the 'storycap' library.

```js
/* .storybook/config.js */

import { addDecorator } from '@storybook/react';
import { withScreenshot } from 'zisui';

addDecorator(withScreenshot({
  // Some screenshot options...
});
```

```js
/* .storybook/config.js */

import { addDecorator } from '@storybook/react';
import { withScreenshot } from 'storycap';

addDecorator(withScreenshot({
  // Some screenshot options...
});
```

--------------------------------

### Configure Storycap with addParameters for Storybook v5+

Source: https://github.com/reg-viz/storycap/blob/master/MIGRATION.md

For Storybook v5.0 and later, Storycap supports global parameters. This snippet shows how to use `addParameters` in `config.js` to configure screenshot options, which is the recommended approach over `addDecorator` for newer Storybook versions.

```js
/* .storybook/config.js */

import { addDecorator, addParameters } from '@storybook/react';
import { withScreenshot } from 'storycap';

addDecorator(withScreenshot);
addParameters({
  screenshot: {
    // Some screenshot options...
  }
});
```

--------------------------------

### Eject Create React App Configuration with npm run eject

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-simple-react/README.md

This command removes the single build dependency from a Create React App project, copying all configuration files (Webpack, Babel, ESLint) into the project. This provides full control over the build setup but is a one-way operation.

```Shell
npm run eject
```

--------------------------------

### Eject Create React App Configuration with npm run eject

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-simple-react/README.md

This command removes the single build dependency from a Create React App project, copying all configuration files (Webpack, Babel, ESLint, etc.) directly into the project. This provides full control over the build setup but is a one-way operation.

```Shell
npm run eject
```

--------------------------------

### Eject Create React App Configuration with npm run eject

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-managed-react/README.md

This is a one-way operation that removes the single build dependency and copies all configuration files (Webpack, Babel, ESLint) into the project. It provides full control over the build setup but means the project is no longer managed by Create React App's default scripts.

```Shell
npm run eject
```

--------------------------------

### Eject Create React App Configuration with npm run eject

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-managed-react/README.md

Removes the single build dependency from a Create React App project, copying all configuration files (Webpack, Babel, ESLint, etc.) directly into the project. This provides full control over the build setup but is a one-way, irreversible operation.

```Shell
npm run eject
```

--------------------------------

### Compose Screenshot Variants in Storybook with Storycap using `extends`

Source: https://github.com/reg-viz/storycap/blob/master/README.md

This example illustrates how to compose multiple screenshot variants using the `extends` field in Storycap. It shows how a 'hovered' variant can extend a 'small' variant, leading to a combinatorial explosion of generated screenshots (e.g., normal, small, hovered, small_hovered).

```javascript
export const Normal = {
  parameters: {
    screenshot: {
      variants: {
        small: {
          viewport: 'iPhone 5',
        },
        hovered: {
          extends: 'small',
          hover: 'button.my-button',
        },
      },
    },
  },
};
```

--------------------------------

### Eject Create React App Configuration with npm run eject

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-react18/README.md

This is a one-way operation that removes the single build dependency from a Create React App project. It copies all the configuration files and transitive dependencies (Webpack, Babel, ESLint, etc.) directly into your project, giving you full control over the build setup. Once ejected, this action cannot be undone.

```Shell
npm run eject
```

--------------------------------

### Implement Custom Font Loading Wait for Storybook Screenshots with Storycap

Source: https://github.com/reg-viz/storycap/blob/master/README.md

This example shows how to implement a custom `waitFor` function for Storycap to ensure fonts are fully loaded before taking a screenshot. It involves a `preload` link in `preview-head.html` and a global JavaScript function `fontLoading` that resolves a Promise when the font is marked as loaded, which Storycap then waits for.

```html
<!-- ./storybook/preview-head.html -->
<link rel="preload" href="/some-heavy-asset.woff" as="font" onload="this.setAttribute('loaded', 'loaded')" />
<script>
  function fontLoading() {
    const loaded = () => !!document.querySelector('link[rel="preload"][loaded="loaded"]');
    if (loaded()) return Promise.resolve();
    return new Promise((resolve, reject) => {
      const id = setInterval(() => {
        if (!loaded()) return;
        clearInterval(id);
        resolve();
      }, 50);
    });
  }
</script>
```

```javascript
/* .storybook/preview.js */

import { withScreenshot } from 'storycap';

export const decorators = [withScreenshot];

export const parameters = {
  screenshot: {
    waitFor: 'fontLoading',
  },
};
```

--------------------------------

### Build React App for Production with npm run build

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-simple-react/README.md

This command builds the React application for production, optimizing it for performance and minifying the code. The output is placed in the `build` folder, ready for deployment.

```Shell
npm run build
```

--------------------------------

### Build React App for Production with npm run build

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-simple-react/README.md

This command builds the React application for production, optimizing it for performance and bundling all assets into the 'build' folder. The output is minified and ready for deployment.

```Shell
npm run build
```

--------------------------------

### Build React App for Production with npm run build

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-managed-react/README.md

This command bundles the React application for production, optimizing it for performance. The output is minified and includes hashed filenames, making it ready for deployment.

```Shell
npm run build
```

--------------------------------

### Build React App for Production with npm run build

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-managed-react/README.md

Builds the React application for production, optimizing it for performance and creating minified, hashed files in the `build` folder. The output is correctly bundled and ready for deployment.

```Shell
npm run build
```

--------------------------------

### Build React App for Production with npm run build

Source: https://github.com/reg-viz/storycap/blob/master/examples/v7-react18/README.md

This command builds the React application for production, optimizing it for performance. It correctly bundles React, minifies the code, and includes hashes in filenames, preparing the app for deployment.

```Shell
npm run build
```

--------------------------------

### Launch React App Test Runner with npm test

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-simple-react/README.md

This command launches the test runner in interactive watch mode, allowing developers to run tests and see results as they make changes. It's useful for continuous testing during development.

```Shell
npm test
```

--------------------------------

### Run Storycap in simple mode

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Execute Storycap against a running Storybook instance without requiring any specific Storybook configuration. Simply provide the URL of your Storybook server.

```sh
$ npx storycap http://localhost:9001
```

--------------------------------

### Run Storycap with pre-built Storybook

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Capture screenshots from a pre-built Storybook. This involves building Storybook, serving the static files with `http-server`, and then running Storycap against the local server.

```sh
$ build-storybook -o dist-storybook
$ storycap --serverCmd "npx http-server dist-storybook -p 9001" http://localhost:9001
```

--------------------------------

### Build All Storycap Lerna Packages

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Executes the build process for all packages within the `reg-viz/storycap` monorepo. This command compiles source code and prepares all modules for distribution or further development.

```sh
$ yarn build
```

--------------------------------

### Launch React Test Runner with npm test

Source: https://github.com/reg-viz/storycap/blob/master/examples/v8-managed-react/README.md

Launches the interactive test runner for the React application. It runs tests in watch mode, providing immediate feedback on test results and allowing for continuous testing during development.

```Shell
npm test
```

--------------------------------

### Run End-to-End Tests for All Storybook Versions

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Initiates end-to-end tests across all configured Storybook versions to verify full system functionality. Upon successful completion, captured PNG screenshots will be available in the `__screenshots__` directory for review.

```sh
./e2e.sh
```

--------------------------------

### Run Unit Tests for All Storycap Packages

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Executes the comprehensive suite of unit tests across all packages in the `reg-viz/storycap` monorepo. This ensures that all components function as expected after changes.

```sh
$ yarn test
```

--------------------------------

### Run Storycap in managed mode with server command

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Combine the Storybook server launch and Storycap execution into a single command using the `--serverCmd` option, streamlining the screenshot capture process in managed mode.

```sh
$ npx storycap http://localhost:9009 --serverCmd "start-storybook -p 9009"
```

--------------------------------

### Configure Storybook main.js for Storycap

Source: https://github.com/reg-viz/storycap/blob/master/README.md

To enable Storycap's managed mode, add 'storycap' to the `addons` array in your `.storybook/main.js` configuration file.

```js
/* .storybook/main.js */

module.exports = {
  stories: ['../src/**/*.stories.@(js|mdx)'],
  addons: [
    '@storybook/addon-actions',
    '@storybook/addon-links',
    'storycap' // <-- Add storycap
  ]
};
```

--------------------------------

### Run Storycap against hosted Storybook

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Storycap can crawl and capture screenshots from a publicly hosted Storybook instance by simply providing its URL.

```sh
$ storycap https://next--storybookjs.netlify.app/vue-kitchen-sink/
```

--------------------------------

### Run Storycap in managed mode

Source: https://github.com/reg-viz/storycap/blob/master/README.md

After configuring Storybook for managed mode, launch your Storybook server and then execute Storycap against its URL to capture screenshots based on your defined parameters.

```sh
$ npx start-storybook -p 9009
$ npx storycap http://localhost:9009
```

--------------------------------

### Build a Specific Storycap Lerna Package

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Allows building an individual package within the monorepo. Users can navigate to the package directory and run `yarn build`, or directly invoke `tsc` with the build configuration for TypeScript projects.

```sh
$ cd packages/<package-name>
$ yarn build
# or
$ yarn run tsc -p tsconfig.build.json
```

--------------------------------

### Lint and Format Storycap Codebase

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Commands to ensure code quality and consistency. `yarn lint` runs ESLint for static code analysis, and `yarn format` uses Prettier to automatically reformat code files according to project standards.

```sh
$ yarn lint     # runs eslint
$ yarn format   # runs prettier --write
```

--------------------------------

### Run Unit Tests for a Specific Storycap Package

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Enables running unit tests for a single package, which is useful during focused development. This can be done by changing into the package directory and running `yarn test`, or by directly invoking `jest`.

```sh
$ cd packages/<package-name>
$ yarn test
# or
$ yarn run jest
```

--------------------------------

### Crawl Storybook stories with Storycrawler and Puppeteer

Source: https://github.com/reg-viz/storycap/blob/master/packages/storycrawler/README.md

Demonstrates how to connect to a Storybook server, fetch stories, launch multiple Puppeteer browsers, and process each story to extract metrics. It utilizes `StorybookConnection`, `StoriesBrowser`, `StoryPreviewBrowser`, `MetricsWatcher`, and `createExecutionService` to automate the crawling process, showing how to interact with Puppeteer's page instance for data extraction.

```ts
import {
  StorybookConnection,
  StoriesBrowser,
  StoryPreviewBrowser,
  MetricsWatcher,
  createExecutionService,
} from 'storycrawler';

(async function () {
  // Connect to the target Storybook server.
  const storybookUrl = 'https://storybookjs.netlify.app/vue-kitchen-sink';
  const connection = await new StorybookConnection({ storybookUrl }).connect();

  // Launch Puppeteer process to fetch stories info.
  const storiesBrowser = await new StoriesBrowser(connection).boot();
  // Item in stories has name, kind and id of the corresponding story
  const stories = await storiesBrowser.getStories();

  // Launce Puppeteer browsers to visit each story's preview window(iframe.html)
  const workers = await Promise.all([0, 1, 2, 3].map(i => new StoryPreviewBrowser(connection, i).boot()));

  try {
    // `createExecutionService` creates a queue of the tasks for each story.
    const service = createExecutionService(workers, stories, story => async worker => {
      // Display story in the worker's preview window
      await worker.setCurrentStory(story);

      // Wait for UI framework updating DOM
      await new MetricsWatcher(worker.page).waitForStable();

      // Extract information from the preview window.
      // You can access Puppeteer's page instance via `worker.page`.
      const m = await worker.page.metrics();
      return { story, nodesCount: m.Nodes };
    });

    // `createExecutionService` register tasks but does not kick them.
    // Tasks in queue start via calling `.execute()`.
    const results = await service.execute();

    results.forEach(({ story, nodesCount }) => console.log(`${story.id}: ${nodesCount}`));
  } finally {
    await storiesBrowser.close();
    await Promise.all(workers.map(worker => worker.close()));
    await connection.disconnect();
  }
})();
```

--------------------------------

### Configure Storybook preview.js with withScreenshot decorator

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Import and register the `withScreenshot` decorator in `.storybook/preview.js`. This decorator is essential for Storycap to capture stories in managed mode. Global screenshot parameters can also be set here.

```js
/* .storybook/preview.js */

import { withScreenshot } from 'storycap';

export const decorators = [
  withScreenshot // Registration the decorator is required
];

export const parameters = {
  // Global parameter is optional.
  screenshot: {
    // Put global screenshot parameters(e.g. viewport)
  }
};
```

--------------------------------

### Configure Basic Screenshot Variants in Storybook with Storycap

Source: https://github.com/reg-viz/storycap/blob/master/README.md

This snippet demonstrates how to configure basic screenshot variants for a Storybook component using Storycap. It shows how to define a 'hovered' variant that applies a hover state to a specific CSS selector, resulting in multiple PNG outputs for a single story.

```javascript
import React from 'react';
import MyButton from './MyButton';

export default {
  title: 'MyButton',
  component: MyButton,
};

export const Normal = {
  parameters: {
    screenshot: {
      variants: {
        hovered: {
          hover: 'button.my-button',
        },
      },
    },
  },
};
```

--------------------------------

### Overwrite Storybook screenshot parameters per story

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Demonstrates how to set specific screenshot options, such as `delay` or `viewport`, for individual stories by defining them within the `parameters.screenshot` key of a story's export.

```js
import React from 'react';
import MyComponent from './MyComponent';

export default {
  title: 'MyComponent',
  component: MyComponent,
  parameters: {
    screenshot: {
      delay: 200
    }
  }
};

export const Normal = {};

export const Small = {
  args: {
    text: 'small'
  },
  parameters: {
    screenshot: {
      viewport: 'iPhone 5'
    }
  }
};
```

--------------------------------

### Update Storycap Documentation Table of Contents and CLI Usage

Source: https://github.com/reg-viz/storycap/blob/master/CONTRIBUTING.md

Runs a script to automatically update generated sections in Markdown files, such as the Table of Contents and CLI usage sections. This command should be executed when modifying `.md` files or adding new CLI options to keep documentation current.

```sh
$ yarn doc
```

--------------------------------

### API: withScreenshot decorator

Source: https://github.com/reg-viz/storycap/blob/master/README.md

A Storybook decorator that signals Storycap to capture screenshots for the stories it is applied to. It is a key component for enabling managed mode.

```APIDOC
withScreenshot:
  Description: A Storybook decorator to notify Storycap to captures stories.
```

--------------------------------

### ScreenshotOptions Type Definition for Storycap

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Defines the configuration options available for `storycap` screenshots. These options can be set via `addParameters` or `withScreenshot`. Properties include `delay` (waiting time before capture), `waitAssets` (wait for all resources), `waitFor` (wait for a promise), `fullPage` (capture entire page), `hover`, `focus`, `click` (interact with elements), `skip` (cancel capture), `viewport`/`viewports` (screenshot dimensions), `variants` (multiple PNG generation), `waitImages` (deprecated, use `waitAssets`), `omitBackground` (transparent screenshots), `captureBeyondViewport` (capture outside viewport), and `clip` (capture a specific portion).

```typescript
interface ScreenshotOptions {
  delay?: number;                           // default 0 msec
  waitAssets?: boolean;                     // default true
  waitFor?: string | () => Promise<void>;   // default ""
  fullPage?: boolean;                     // default true
  hover?: string;                           // default ""
  focus?: string;                           // default ""
  click?: string;                           // default ""
  skip?: boolean;                           // default false
  viewport?: Viewport;
  viewports?: string[] | { [variantName: string]: Viewport };
  variants?: Variants;
  waitImages?: boolean;                     // default true
  omitBackground?: boolean;                 // default false
  captureBeyondViewport?: boolean;          // default true
  clip?: { x: number; y: number; width: number; height: number } | null; // default null
}
```

--------------------------------

### Variants Type Definition for Multiple Storycap Screenshots

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Defines a type used to generate multiple PNGs from a single story. Each variant can override `ScreenshotOptions` and includes an `extends` property to inherit options from other variants. When extending, the generated PNG file will have a suffix like `_${parentVariantName}_${thisVariantName}`.

```typescript
type Variants = {
  [variantName: string]: {
    extends?: string | string[]; // default: ""
    delay?: number;
    waitAssets?: boolean;
    waitFor?: string | () => Promise<void>;
    fullPage?: boolean;
    hover?: string;
    focus?: string;
    click?: string;
    skip?: boolean;
    viewport?: Viewport;
    waitImages?: boolean;
    omitBackground?: boolean;
    captureBeyondViewport?: boolean;
    clip?: { x: number; y: number; width: number; height: number } | null;
  };
}
```

--------------------------------

### Wait for Specific HTML Elements in Storybook Screenshots with Storycap

Source: https://github.com/reg-viz/storycap/blob/master/README.md

This snippet demonstrates using the `waitFor` option in Storycap to pause screenshot generation until specific HTML elements appear. It leverages the `screen.findByRole` function from `@storybook/test` to ensure lazy-loaded elements are present before the screenshot is taken.

```javascript
/* MyComponent.stories.js */

import { screen } from '@storybook/test';

export const MyStory = {
  screenshot: {
    waitFor: async () => {
      await screen.findByRole('link');
    },
  },
};
```

--------------------------------

### Viewport Type Definition for Storycap Screenshot Dimensions

Source: https://github.com/reg-viz/storycap/blob/master/README.md

Defines the viewport configuration for screenshots, compatible with Puppeteer's viewport interface. It can be a string representing a valid device name or an object specifying `width`, `height`, `deviceScaleFactor`, `isMobile`, `hasTouch`, and `isLandscape` properties.

```typescript
type Viewport =
  | string
  | {
      width: number; // default: 800
      height: number; // default: 600
      deviceScaleFactor: ?number; // default: 1,
      isMobile?: boolean; // default: false,
      hasTouch?: boolean; // default: false,
      isLandscape?: boolean; // default: false,
    };
```

--------------------------------

### isScreenshot Function to Detect Storycap Environment

Source: https://github.com/reg-viz/storycap/blob/master/README.md

A utility function that returns a boolean indicating whether the current process is running within the Storycap browser. This is useful for conditionally changing story behavior, such as disabling JavaScript animations, only when Storycap is active.

```typescript
function isScreenshot(): boolean;
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.