84,621
返回集成

Percy

用于 Percy 视觉测试的 Storybook 插件

在 Github 上查看

@percy/storybook

Version Test

使用 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 https://127.0.0.1:9009
$ percy storybook https://storybook.foobar.com

自动运行 start-storybook

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

命令

percy storybook

快照静态或托管的 Storybook 故事

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 https://127.0.0.1:9000/

percy storybook:start

运行 start-storybook 以对故事进行快照

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 参数 是一组关于故事的静态命名元数据，用于控制 Storybook 功能和插件的行为。可以提供 percy 参数以向故事或一组故事添加每个快照配置选项。

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

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

除了 常见的每个快照选项 外，还接受以下 percy Storybook 参数

  • skip - 指示是否跳过此故事的布尔值。
  • name - 快照名称。（默认：${story.kind}: ${story.name}）
  • args - 拍摄快照时要使用的 故事参数。
  • globals - 拍摄快照时要使用的 故事全局变量。
  • queryParams - 拍摄快照时要使用的查询参数。
  • waitForTimeout - 拍摄快照前等待超时。
  • waitForSelector - 拍摄快照前等待选择器存在。
  • include - 与故事名称匹配的正则表达式模式数组，仅包含用于拍摄快照的故事。
  • exclude - 与故事名称匹配的正则表达式模式数组，始终从拍摄快照中排除。
  • additionalSnapshots - 要为此故事拍摄的其他快照的数组。
    • prefix - 添加到此附加快照名称的前缀。
    • suffix - 添加到此附加快照名称的后缀。
    • name - 快照名称。替换继承的名称。
    • args - 此附加快照的其他故事参数。
    • globals - 此附加快照的其他故事全局变量。
    • queryParams - 此附加快照的其他查询参数。
    • include - 仅将附加快照应用于匹配的故事。
    • exclude - 不要将附加快照应用于匹配的故事。
MyStory.parameters = {
  percy: {
    name: 'My snapshot',
    additionalSnapshots: [
      { prefix: '[Dark mode] ', args: { colorScheme: 'dark' } },
      { suffix: ' with a search', queryParams: { search: 'foobar' } }
    ]
  }
};

在此示例中，将为此故事拍摄 3 个快照，并在每个快照的 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 标志，并且没有替代方案。如果您依赖此标志，请打开一个问题。

  • 不再接受 --rtl 和 --rtl_regex 标志。--rtl 标志复制故事并为副本的 URL 设置 direction=rtl 查询参数。--rtl_regex 标志用于确定何时创建此 RTL 副本故事。

    // .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 不会拍摄 DOM 快照或执行资产发现，因为所有其他现代 Percy SDK 都会这样做。这有时会导致不稳定的快照或缺少资产的快照。但是，DOM 快照和资产发现会增加性能开销。旧版 SDK 非常快地上传本地构建目录，而新版 SDK 在捕获每个故事的真实 DOM 和相关资产时可能会稍微慢一些。

意外差异

由于旧版 SDK 没有拍摄 DOM 快照，因此必须在我们的 Storybook 渲染环境中启用 JavaScript 才能正确加载。这与我们所有其他 SDK 形成对比，在其他 SDK 中，默认情况下禁用 JavaScript 以防止由动画或页面上运行的其他 JavaScript 导致的不稳定差异。使用新的 SDK 和真实的 DOM 快照，默认情况下 JS 已禁用。如果您升级并因缺少 JavaScript 而遇到差异，则可以使用匹配的 Percy 配置文件或每个快照选项 enableJavaScript 重新启用它。

开发

  • 当前的 package.json 和 yarn.lock 将 storybook v7 安装为 devDependency，因此开发需要 node 16。
  • 出于测试目的，有单独的 package.json 和配置文件用于 storybook v6。有关 storybook v6 测试更改的更多详细信息，请查看 prepare-storybook-v6-tests.sh 文件。
制作人
  • paolo-dipasquale-intercom
    paolo-dipasquale-intercom
标签
如何安装插件 创建插件