Percy

用于使用 Percy 进行视觉测试的 Storybook 插件

在 Github 上查看

每周下载量

@percy/storybook

使用 Percy 进行视觉测试

Percy 是一个一体化的视觉测试和审查平台。它捕获屏幕截图，与基准进行比较，并突出显示视觉变化。随着视觉覆盖范围的增加，团队可以在每次提交时放心地部署代码更改。

Storybook 原生支持使用 Percy 进行跨浏览器视觉测试。您可以使用 Percy 对桌面和移动浏览器上的 Web 应用程序进行视觉测试。

在此注册免费开始使用 Percy。

使用 Percy 进行视觉测试的好处包括：

一致性：通过在开发过程早期识别视觉差异来提升一致的用户体验。
效率：减少手动发现视觉回归所需的时间和精力，从而提高效率。
集成：Percy 集成流行的工具和服务，如 GitHub、GitLab、Bitbucket 等。
协作：通过提供变更的视觉表示，改善开发者、设计师和 QA 团队之间的协作。
防止回归：防止出现意外的视觉回归。

Percy 如何工作？

Percy 将新的快照与相关的基准进行比较，以检测视觉变化。Percy 管理跨分支的基准选择，因此您的测试始终相关。如果检测到视觉变化，Percy 会突出显示并将由此产生的差异进行分组，供您审查。

使用 percy 运行您的第一个构建

Percy 针对 Storybook 的示例构建教程。

安装

$ npm install --save-dev @percy/cli @percy/storybook

用法

# Unix
$ export PERCY_TOKEN="<your-project-token>"

# Windows
$ set PERCY_TOKEN="<your-project-token>"

# Powershell
$ $Env:PERCY_TOKEN="<your-project-token>"

使用静态 Storybook 构建

$ percy storybook ./storybook-build

使用本地或在线 Storybook URL

$ percy storybook http://localhost:9009
$ percy storybook https://storybook.foobar.com

自动运行 start-storybook

$ percy storybook:start --port=9009 --static-dir=./public

`percy storybook`

对静态或托管的 Storybook stories 进行快照

Usage:
  $ percy storybook [options] <url|directory>

Arguments:
  url|directory                      Storybook url or build output directory

Subcommands:
  storybook:start [options]          Run start-storybook to snapshot stories
  help [command]                     Display command help

Options:
  -i, --include <pattern>            Pattern matching story names to include in snapshots
  -e, --exclude <pattern>            Pattern matching story names to exclude from snapshots
  --shard-count <number>             Number of shards to split snapshots into
  --shard-size <number>              Size of each shard to split snapshots into
  --shard-index <index>              Index of the shard to take snapshots of
  --partial                          Marks the build as a partial build

Percy options:
  -c, --config <file>                Config file path
  -d, --dry-run                      Print snapshot names only
  -h, --allowed-hostname <hostname>  Allowed hostnames to capture in asset discovery
  --disallowed-hostname <hostname>   Disallowed hostnames to abort in asset discovery
  -t, --network-idle-timeout <ms>    Asset discovery network idle timeout
  --disable-cache                    Disable asset discovery caches
  --debug                            Debug asset discovery and do not upload snapshots

Global options:
  -v, --verbose                      Log everything
  -q, --quiet                        Log errors only
  -s, --silent                       Log nothing
  --help                             Display command help

Examples:
  $ percy storybook ./build
  $ percy storybook http://localhost:9000/

`percy storybook:start`

运行 start-storybook 对 stories 进行快照

Usage:
  $ percy storybook:start [options]

Options:
  -i, --include <pattern>            Pattern matching story names to include in snapshots
  -e, --exclude <pattern>            Pattern matching story names to exclude from snapshots
  --shard-count <number>             Number of shards to split snapshots into
  --shard-size <number>              Size of each shard to split snapshots into
  --shard-index <index>              Index of the shard to take snapshots of
  --partial                          Marks the build as a partial build
  --port [number]                    Port to start Storybook (default: 9000)
  --host [hostname]                  Host to start Storybook (default: "localhost")

Percy options:
  -c, --config <file>                Config file path
  -d, --dry-run                      Print snapshot names only
  -h, --allowed-hostname <hostname>  Allowed hostnames to capture in asset discovery
  --disallowed-hostname <hostname>   Disallowed hostnames to abort in asset discovery
  -t, --network-idle-timeout <ms>    Asset discovery network idle timeout
  --disable-cache                    Disable asset discovery caches
  --debug                            Debug asset discovery and do not upload snapshots

Global options:
  -v, --verbose                      Log everything
  -q, --quiet                        Log errors only
  -s, --silent                       Log nothing
  --help                             Display command help

Examples:
  $ percy storybook:start
  $ percy storybook:start --port 9000
  $ percy storybook:start --static-dir public

配置

Storybook 参数是一组关于 story 的静态命名元数据，用于控制 Storybook 功能和插件的行为。可以提供 percy 参数，为单个 story 或一组 stories 添加按快照配置的选项。

// individual stories
MyStory.parameters = {
  percy: { ... }
};

// .storybook/preview.js
export const parameters = {
  percy: { ... }
};

除了常见的按快照选项外，还支持以下 percy Storybook 参数

skip - 布尔值，指示是否跳过此 story。
name - 快照名称。（默认：${story.kind}: ${story.name}）
args - 对 story 进行快照时使用的story 参数。
globals - 对 story 进行快照时使用的story 全局变量。
queryParams - 快照时使用的查询参数。
waitForTimeout - 在拍摄快照之前等待超时。
waitForSelector - 在拍摄快照之前等待选择器存在。
include - 一个正则表达式模式数组，用于匹配要包含在快照中的 story 名称。
exclude - 一个正则表达式模式数组，用于匹配始终从快照中排除的 story 名称。
additionalSnapshots - 要对该 story 拍摄的其他快照数组。
- prefix - 添加到此额外快照名称的前缀。
- suffix - 添加到此额外快照名称的后缀。
- name - 快照名称。替换继承的名称。
- args - 此额外快照的其他 story 参数。
- globals - 此额外快照的其他 story 全局变量。
- queryParams - 此额外快照的其他查询参数。
- include - 仅将额外快照应用于匹配的 stories。
- exclude - 不将额外快照应用于匹配的 stories。

MyStory.parameters = {
  percy: {
    name: 'My snapshot',
    additionalSnapshots: [
      { prefix: '[Dark mode] ', args: { colorScheme: 'dark' } },
      { suffix: ' with a search', queryParams: { search: 'foobar' } }
    ]
  }
};

在此示例中，将为此 story 拍摄 3 个快照，并将 args 和 query params 附加到每个快照的 URL 中

# --dry-run will log snapshots without creating a new build
# --verbose will show debug logs, including the snapshot url
$ percy storybook --dry-run --verbose ./example-storybook
# ...
[percy] Snapshot found: My snapshot
[percy] -> url: [...]?id=component--my-story
[percy] Snapshot found: [Dark mode] My snapshot
[percy] -> url: [...]?id=component--my-story&args=colorScheme:dark
[percy] Snapshot found: My snapshot with a search
[percy] -> url: [...]?id=component--my-story&search=foobar

Percy 配置文件选项

除了常见的 Percy 配置文件选项外，此 SDK 还添加了以下 Storybook 特定的选项

# .percy.yml
version: 2
storybook:
  args: {}
  globals: {}
  queryParams: {}
  waitForTimeout: 0
  waitForSelector: ''
  additionalSnapshots: []
  include: []
  exclude: []

有关每个支持的配置文件选项的详细信息，请参见上方的配置选项（注意：skip 和 name 参数不作为 Percy 配置文件选项接受）。

升级

Storybook SDK 的先前版本与当前版本差异很大。命令、参数以及 SDK 的内部工作方式都已完全改变。在新版本中使用旧命令现在将导致错误消息。新命令现已作为插件集成到 @percy/cli 中。

要使用此 SDK 的新版本，您还需要随 SDK 一起安装 CLI

$ npm install --save-dev @percy/cli @percy/storybook

由于命令和参数都已更改，您需要将现有用法替换为上面描述的新用法。对于某些项目，这可能需要设置额外的配置选项。有关详细信息，请参见下方的重大更改列表。

重大更改

最重要的是，命令本身已更改，并且所有以前的参数都不再被接受。

percy-storybook 命令已替换为 percy CLI 子命令 percy storybook。

之前的 --build_dir 标志现在是命令参数，并且没有默认构建目录。如果您依赖于默认设置，现在必须明确提供。

# before
$ percy-storybook
# after
$ percy storybook ./storybook-static

# before
$ percy-storybook --build_dir ./build
# after
$ percy storybook ./build

--widths 标志不再接受。宽度可以使用相应的 widths Percy 配置文件 snapshot 选项或 percy Storybook 参数进行设置。
--minimum_height 标志不再接受，因此不再默认为 800px。所有 SDK 共享的默认最小高度为 1024px。最小高度可以使用相应的 min-height Percy 配置文件 snapshot 选项或 percy Storybook 参数进行设置。
--debug 标志现已改为 --verbose，从 CLI 继承而来。
--output-format 标志不再接受，也没有替代方案。如果您依赖此标志，请提交一个 issue。

--rtl 和 --rtl_regex 标志不再接受。--rtl 标志会复制 stories 并为复制品的 URL 设置 direction=rtl 查询参数。--rtl_regex 标志用于确定何时创建此 RTL 复制 story。

// .storybook/preview.js

export const parameters = {
  percy: {
    // tell percy to take an additional RTL snapshot for matching stories
    additionalSnapshots: [{
      suffix: ' [RTL]',
      queryParams: { direction: 'rtl' },
      include: ['^FormElement: .*']
    }]
  }
};

性能

旧的 SDK 不像所有其他现代 Percy SDK 那样捕获 DOM 快照或执行资源发现。这有时会导致快照不稳定或快照缺少资源。然而，DOM 快照和资源发现会增加性能开销。旧 SDK 只需快速上传本地构建目录，而新 SDK 在捕获每个 story 的实际 DOM 和相关资源时可能会慢一些。

意外差异

由于旧的 SDK 不捕获 DOM 快照，我们的渲染环境中必须启用 JavaScript，以便 Storybook 正常加载。这与我们所有其他 SDK 不同，在其他 SDK 中，默认禁用 JavaScript 以防止由动画或页面上运行的其他 JavaScript 引起的快照不稳定差异。使用新的 SDK 和真实的 DOM 快照，JS 默认是禁用的。如果您升级后遇到由于缺少 JavaScript 导致的差异，可以使用匹配的 Percy 配置文件或按快照选项 enableJavaScript 重新启用它。

开发

当前的 package.json 和 yarn.lock 将 storybook v7 安装为开发依赖，因此需要 Node 16 进行开发。
为了测试目的，有单独的 storybook v6 的 package.json 和配置文件。有关 storybook v6 测试更改的更多详细信息，请查看 prepare-storybook-v6-tests.sh 文件。

制作者

paolo-dipasquale-intercom

标签

如何安装插件创建插件