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 - 符合要僅包含快照的故事名稱的 Regex 模式陣列。
  • exclude - 符合要始終從快照排除的故事名稱的 Regex 模式陣列。
  • 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 旗標現在是從 CLI 繼承的 --verbose。

  • 不再接受 --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 快照，因此必須在我們的轉譯環境中啟用 JavaScript，才能讓 Storybook 正確載入。這與我們所有其他預設停用 JavaScript 以防止動畫或其他在頁面上執行的 JavaScript 造成不穩定的差異的 SDK 形成對比。使用新的 SDK 和實際 DOM 快照時，預設會停用 JS。如果您升級並因缺少 JavaScript 而遇到差異，可以使用相符的 Percy 組態檔或每個快照的選項 enableJavaScript 重新啟用它。

開發

  • 目前的 package.json 和 yarn.lock 安裝 Storybook v7 作為 devDependency，因此需要 Node 16 進行開發。
  • Storybook v6 有個別的 package.json 和組態檔，用於測試目的。請查看 prepare-storybook-v6-tests.sh 檔案，以取得有關 Storybook v6 測試變更的更多詳細資料。
由
  • paolo-dipasquale-intercom
    paolo-dipasquale-intercom
標籤
如何安裝附加元件 建立附加元件