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 标志，并且没有替代方案。如果您依赖于此标志，请打开一个 issue。

  • 不再接受 --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 快照，因此必须在我们的渲染环境中启用 JavaScript 才能使 Storybook 正确加载。这与我们所有其他 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 文件。
制作人
  • percy-admin
    percy-admin
标签
如何安装插件 创建插件