{"id":17779535,"url":"https://github.com/percy/percy-storybook","last_synced_at":"2025-05-15T09:04:13.118Z","repository":{"id":38357204,"uuid":"101525579","full_name":"percy/percy-storybook","owner":"percy","description":"Percy's Storybook SDK. ","archived":false,"fork":false,"pushed_at":"2025-03-17T08:52:59.000Z","size":11175,"stargazers_count":153,"open_issues_count":8,"forks_count":46,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-19T03:33:35.244Z","etag":null,"topics":["component","component-visual-testing","percy","percy-sdk","percy-storybook","storybook","testing","visual-testing"],"latest_commit_sha":null,"homepage":"https://docs.percy.io/docs/storybook","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/percy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-27T02:41:27.000Z","updated_at":"2025-03-05T06:06:17.000Z","dependencies_parsed_at":"2023-10-18T13:45:42.378Z","dependency_job_id":"2a6bf7b7-c3ee-41dc-88c4-725a6368f63f","html_url":"https://github.com/percy/percy-storybook","commit_stats":{"total_commits":718,"total_committers":27,"mean_commits":26.59259259259259,"dds":0.5988857938718664,"last_synced_commit":"143a4e3802eb980cbc35b66c248b1392dbad635b"},"previous_names":[],"tags_count":203,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percy%2Fpercy-storybook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percy%2Fpercy-storybook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percy%2Fpercy-storybook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percy%2Fpercy-storybook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/percy","download_url":"https://codeload.github.com/percy/percy-storybook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244865192,"owners_count":20523316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","component-visual-testing","percy","percy-sdk","percy-storybook","storybook","testing","visual-testing"],"created_at":"2024-10-27T01:04:28.428Z","updated_at":"2025-03-24T01:16:22.807Z","avatar_url":"https://github.com/percy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @percy/storybook\n[![Version](https://img.shields.io/npm/v/@percy/storybook.svg)](https://npmjs.org/package/@percy/storybook)\n![Test](https://github.com/percy/percy-storybook/workflows/Test/badge.svg)\n\n## Visual Testing with Percy\n\n[Percy](https://percy.io?utm_source=storybook\u0026utm_medium=partnered\u0026utm_campaign=documentation) is an all-in-one visual testing and review platform. It captures screenshots, compares them against the baseline, and highlights visual changes. With increased visual coverage, teams can deploy code changes with confidence with every commit.\n\n[Storybook](https://storybook.js.org) supports cross-browser visual testing natively using Percy. You can use Percy for visual testing of web applications on desktop and mobile browsers.\n\nSign up [here](https://www.browserstack.com/users/sign_in?utm_source=storybook\u0026utm_medium=partnered\u0026utm_campaign=documentation) to get started with Percy for free.\n\nThe benefits of utilizing Percy for visual testing include the following:\n\n- Consistency: Promotes consistent user experience by identifying visual discrepancies early in the development process.\n- Efficiency: Improves efficiency by reducing the time and effort required to manually spot visual regressions.\n- Integrations: Percy integrates with popular tools and services like GitHub, GitLab, Bitbucket, and more.\n- Collaboration: Improves collaboration between developers, designers, and QA teams by providing a visual representation of changes.\n- Prevent regression: Prevents you from experiencing unintended visual regressions.\n\n## How does Percy work?\n\nPercy compares new snapshots against relevant baselines to detect visual changes. Percy manages baseline selection across branches so your tests are always relevant. If visual changes are detected, Percy highlights and groups the resulting diffs for you to review.\n\n## Run your first build with percy\n[Percy’s sample build tutorial for Storybook.](https://www.browserstack.com/docs/percy/sample-build/storybook?utm_source=storybook\u0026utm_medium=partnered\u0026utm_campaign=documentation)\n\n## Installation\n\n``` session\n$ npm install --save-dev @percy/cli @percy/storybook\n```\n\n## Usage\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    Before running the following commands, make sure your project's \u003ccode\u003ePERCY_TOKEN\u003c/code\u003e\n    is properly configured.\n  \u003c/summary\u003e\n\n  ``` sh\n  # Unix\n  $ export PERCY_TOKEN=\"\u003cyour-project-token\u003e\"\n\n  # Windows\n  $ set PERCY_TOKEN=\"\u003cyour-project-token\u003e\"\n\n  # Powershell\n  $ $Env:PERCY_TOKEN=\"\u003cyour-project-token\u003e\"\n  ```\n\u003c/details\u003e\n\nWith a static Storybook build:\n\n``` sh\n$ percy storybook ./storybook-build\n```\n\nWith a local or live Storybook URL:\n\n``` sh\n$ percy storybook http://localhost:9009\n$ percy storybook https://storybook.foobar.com\n```\n\nAutomatically run `start-storybook`:\n\n``` sh\n$ percy storybook:start --port=9009 --static-dir=./public\n```\n\n## Commands:\n\u003c!-- commands --\u003e\n* [`percy storybook`](#percy-storybook)\n* [`percy storybook:start`](#percy-storybookstart)\n\n### `percy storybook`\n\nSnapshot static or hosted Storybook stories\n\n```\nUsage:\n  $ percy storybook [options] \u003curl|directory\u003e\n\nArguments:\n  url|directory                      Storybook url or build output directory\n\nSubcommands:\n  storybook:start [options]          Run start-storybook to snapshot stories\n  help [command]                     Display command help\n\nOptions:\n  -i, --include \u003cpattern\u003e            Pattern matching story names to include in snapshots\n  -e, --exclude \u003cpattern\u003e            Pattern matching story names to exclude from snapshots\n  --shard-count \u003cnumber\u003e             Number of shards to split snapshots into\n  --shard-size \u003cnumber\u003e              Size of each shard to split snapshots into\n  --shard-index \u003cindex\u003e              Index of the shard to take snapshots of\n  --partial                          Marks the build as a partial build\n\nPercy options:\n  -c, --config \u003cfile\u003e                Config file path\n  -d, --dry-run                      Print snapshot names only\n  -h, --allowed-hostname \u003chostname\u003e  Allowed hostnames to capture in asset discovery\n  --disallowed-hostname \u003chostname\u003e   Disallowed hostnames to abort in asset discovery\n  -t, --network-idle-timeout \u003cms\u003e    Asset discovery network idle timeout\n  --disable-cache                    Disable asset discovery caches\n  --debug                            Debug asset discovery and do not upload snapshots\n\nGlobal options:\n  -v, --verbose                      Log everything\n  -q, --quiet                        Log errors only\n  -s, --silent                       Log nothing\n  --help                             Display command help\n\nExamples:\n  $ percy storybook ./build\n  $ percy storybook http://localhost:9000/\n```\n\n### `percy storybook:start`\n\nRun start-storybook to snapshot stories\n\n```\nUsage:\n  $ percy storybook:start [options]\n\nOptions:\n  -i, --include \u003cpattern\u003e            Pattern matching story names to include in snapshots\n  -e, --exclude \u003cpattern\u003e            Pattern matching story names to exclude from snapshots\n  --shard-count \u003cnumber\u003e             Number of shards to split snapshots into\n  --shard-size \u003cnumber\u003e              Size of each shard to split snapshots into\n  --shard-index \u003cindex\u003e              Index of the shard to take snapshots of\n  --partial                          Marks the build as a partial build\n  --port [number]                    Port to start Storybook (default: 9000)\n  --host [hostname]                  Host to start Storybook (default: \"localhost\")\n\nPercy options:\n  -c, --config \u003cfile\u003e                Config file path\n  -d, --dry-run                      Print snapshot names only\n  -h, --allowed-hostname \u003chostname\u003e  Allowed hostnames to capture in asset discovery\n  --disallowed-hostname \u003chostname\u003e   Disallowed hostnames to abort in asset discovery\n  -t, --network-idle-timeout \u003cms\u003e    Asset discovery network idle timeout\n  --disable-cache                    Disable asset discovery caches\n  --debug                            Debug asset discovery and do not upload snapshots\n\nGlobal options:\n  -v, --verbose                      Log everything\n  -q, --quiet                        Log errors only\n  -s, --silent                       Log nothing\n  --help                             Display command help\n\nExamples:\n  $ percy storybook:start\n  $ percy storybook:start --port 9000\n  $ percy storybook:start --static-dir public\n```\n\u003c!-- commandsstop --\u003e\n\n## Configuration\n\n[Storybook parameters](https://storybook.js.org/docs/react/writing-stories/parameters) are a set of static,\nnamed metadata about a story, used to control the behavior of Storybook features and addons. The `percy`\nparameter can be provided to add per-snapshot configuration options to a story or set of stories.\n  \n``` javascript\n// individual stories\nMyStory.parameters = {\n  percy: { ... }\n};\n```\n``` javascript\n// .storybook/preview.js\nexport const parameters = {\n  percy: { ... }\n};\n```\n  \nThe following `percy` Storybook parameters are accepted in addition to [common per-snapshot \noptions](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration?utm_source=storybook\u0026utm_medium=partnered\u0026utm_campaign=documentation):\n\n- **skip** - Boolean indicating whether or not to skip this story.\n- **name** - Snapshot name. (default: `${story.kind}: ${story.name}`)\n- **args** - [Story args](https://storybook.js.org/docs/react/writing-stories/args) to use when\n  taking the snapshot.\n- **globals** - [Story\n  globals](https://storybook.js.org/docs/react/essentials/toolbars-and-globals#globals) to use when\n  taking the snapshot.\n- **queryParams** - Query parameters to use when snapshotting.\n- **waitForTimeout** - Wait for a timeout before taking the snapshot.\n- **waitForSelector** - Wait for a selector to exist before taking the snapshot.\n- **include** - An array of regex patterns matching story names to only include for snapshotting.\n- **exclude** - An array of regex patterns matching story names to always exclude from snapshotting.\n- **additionalSnapshots** - An array of additional snapshots to take of this story.\n  - **prefix** - A prefix added to this additional snapshot's name.\n  - **suffix** - A suffix added to this additional snapshot's name.\n  - **name** - Snapshot name. Replaces the inherited name.\n  - **args** - Additional story args for this additional snapshot.\n  - **globals** - Additional story globals for this additional snapshot.\n  - **queryParams** - Additional query parameters for this additional snapshot.\n  - **include** - Only apply the additional snapshot to matching stories.\n  - **exclude** - Do not apply the additional snapshot to matching stories.\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to see an example story configuration\u003c/summary\u003e\u003cbr\u003e\n\n  ``` javascript\n  MyStory.parameters = {\n    percy: {\n      name: 'My snapshot',\n      additionalSnapshots: [\n        { prefix: '[Dark mode] ', args: { colorScheme: 'dark' } },\n        { suffix: ' with a search', queryParams: { search: 'foobar' } }\n      ]\n    }\n  };\n  ```\n\n  With this example, 3 snapshots will be taken of this story with args and query params appended\n  to the URL of each snapshot:\n\n  ``` sh\n  # --dry-run will log snapshots without creating a new build\n  # --verbose will show debug logs, including the snapshot url\n  $ percy storybook --dry-run --verbose ./example-storybook\n  # ...\n  [percy] Snapshot found: My snapshot\n  [percy] -\u003e url: [...]?id=component--my-story\n  [percy] Snapshot found: [Dark mode] My snapshot\n  [percy] -\u003e url: [...]?id=component--my-story\u0026args=colorScheme:dark\n  [percy] Snapshot found: My snapshot with a search\n  [percy] -\u003e url: [...]?id=component--my-story\u0026search=foobar\n  ```\n\u003c/details\u003e\n\n## Percy config file options\n\nIn addition to [common Percy config file options](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview),\nthis SDK also adds the following Storybook specific options:\n\n``` yaml\n# .percy.yml\nversion: 2\nstorybook:\n  args: {}\n  globals: {}\n  queryParams: {}\n  waitForTimeout: 0\n  waitForSelector: ''\n  additionalSnapshots: []\n  include: []\n  exclude: []\n```\n\nSee the [configuration options above](#configuration) for details about each accepted config file\noption (**note**: the `skip` and `name` parameters are _not_ accepted as Percy config file options).\n\n## Upgrading\n\nPrior versions of the Storybook SDK were drastically different than the current version. The\ncommand, it's arguments, and how the SDK works internally have changed completely. Using the old\ncommand with new versions will now result in an error message. The new command is now integrated into\n[`@percy/cli`](https://github.com/percy/cli) as a plugin.\n\nTo use new versions of this SDK, you will have to also install the CLI with the SDK:\n\n``` sh\n$ npm install --save-dev @percy/cli @percy/storybook\n```\n\nSince both the command and arguments have changed, you'll need to replace your existing usage with\nthe [new usage described above](#usage). For some projects, this may require setting additional \n[configuration options](#configuration). See the list of breaking changes below for details.\n\n### Breaking changes\n\nMost importantly, the command itself has changed and all previous arguments are no longer accepted.\n  \n- The `percy-storybook` command has been replaced with a [`percy` CLI](https://github.com/percy/cli) \n  subcommand, `percy storybook`.\n\n- The previous `--build_dir` flag is now a command argument and there is no default build directory. If\n  you relied on the default, it must now be explicitly provided.\n\n  ``` sh\n  # before\n  $ percy-storybook\n  # after\n  $ percy storybook ./storybook-static\n\n  # before\n  $ percy-storybook --build_dir ./build\n  # after\n  $ percy storybook ./build\n  ```\n\n- The `--widths` flag is no longer accepted. Widths can be set using the respective `widths`\n  [Percy config file `snapshot` option](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#snapshot) or \n  `percy` Storybook parameter.\n\n- The `--minimum_height` flag is no longer accepted and therefore no longer defaults to\n  800px. The default minimum height shared by all SDKs is 1024px. The minimum height can be \n  set using the respective `min-height` [Percy config file `snapshot`\n  option](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#snapshot) or `percy` Storybook parameter.\n\n- The `--debug` flag is now `--verbose`, inherited from the CLI.\n\n- The `--output-format` flag is no longer accepted and has no alternative. If you relied on this\n  flag, please open an issue.\n\n- The `--rtl` and `--rtl_regex` flags are no longer accepted. The `--rtl` flag duplicated stories\n  and set the `direction=rtl` query parameter for the duplicate's URL. The `--rtl_regex` flag was\n  used to determine when to create this RTL duplicate story.\n\n  \u003cdetails\u003e\n    \u003csummary\u003eClick here to see how to replicate the old behaviour with new configuration\n    options\u003c/summary\u003e\u003cbr\u003e\n\n    ``` js\n    // .storybook/preview.js\n\n    export const parameters = {\n      percy: {\n        // tell percy to take an additional RTL snapshot for matching stories\n        additionalSnapshots: [{\n          suffix: ' [RTL]',\n          queryParams: { direction: 'rtl' },\n          include: ['^FormElement: .*']\n        }]\n      }\n    };\n    ```\n  \u003c/details\u003e\n\n#### Performance\n\nThe old SDK did not take DOM snapshots or perform asset discovery, as all other modern Percy SDKs\ndo. This sometimes resulted in flakey snapshots or snapshots with missing assets. However, DOM\nsnapshots and asset discovery add an overhead cost of performance. Where the old SDK was very quick\nto simply upload the local build directory, the new SDK can be a little slower while it is capturing\nthe real DOM and relevant assets of each story.\n\n#### Unexpected diffs\n\nBecause the old SDK did not take DOM snapshots, JavaScript had to be enabled in our rendering\nenvironment for Storybook to properly load. This is in contrast to all of our other SDKs, where\nJavaScript is disabled by default to prevent flakey diffs caused by animations or other JavaScript\nrunning on the page. With the new SDK and real DOM snapshots, JS is disabled by default. If you\nupgrade and experience diffs due to the lack of JavaScript, it can be re-enabled using the matching\nPercy config file or per-snapshot option, [`enableJavaScript`](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#snapshot).\n\n## Development\n- Current package.json and yarn.lock install storybook v7 as devDependency and hence require node 16 for development.\n- There are separate package.json and config files for storybook v6, for testing purposes. Please check `prepare-storybook-v6-tests.sh` file for more details around changes for storybook v6 testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpercy%2Fpercy-storybook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpercy%2Fpercy-storybook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpercy%2Fpercy-storybook/lists"}