加入直播：周四，美国东部时间上午 11 点，Storybook 9 发布及 AMA
86,718
返回集成页面

Percy

使用 Percy 进行可视化测试的 Storybook 插件

在 Github 上查看

@percy/storybook

Version Test

使用 Percy 进行可视化测试

Percy 是一个一体化的可视化测试和评审平台。它可以捕获截图，与基线进行比较，并突出显示视觉变化。通过提高可视化覆盖率，团队可以在每次提交代码时自信地部署代码更改。

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

在这里注册，开始免费使用 Percy。

使用 Percy 进行可视化测试的优势包括以下几点

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

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 故事创建快照

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 为故事创建快照

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 中都会附加 args 和 query params。

# --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 不会像所有其他现代 Percy SDK 那样捕获 DOM 快照或执行资产发现。这有时会导致不稳定的快照或缺少资产的快照。然而，DOM 快照和资产发现会增加性能开销。旧 SDK 仅上传本地构建目录速度非常快，而新 SDK 在捕获每个故事的真实 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 文件。
作者
  • percy-admin
    percy-admin
标签
如何安装插件 创建插件