84,621
返回整合

Percy

用於使用 Percy 進行視覺測試的 Storybook 擴充功能

在 Github 上檢視

@percy/storybook

Version Test

使用 Percy 進行視覺測試

Percy 是一個全方位的視覺測試和審查平台。它會擷取螢幕截圖，將它們與基準線進行比較，並突顯視覺上的變化。透過提高視覺覆蓋率，團隊可以在每次提交時都充滿信心地部署程式碼變更。

Storybook 原生支援使用 Percy 進行跨瀏覽器的視覺測試。您可以使用 Percy 對桌上型電腦和行動瀏覽器上的網路應用程式進行視覺測試。

在這裡註冊即可免費開始使用 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 旗標現在是從 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 沒有像所有其他現代 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 作為 devDependency，因此需要節點 16 才能進行開發。
  • 有單獨的 package.json 和組態檔案適用於 storybook v6，以供測試之用。請檢查 prepare-storybook-v6-tests.sh 檔案，以取得有關 storybook v6 測試變更的更多詳細資訊。
由以下人員製作
  • percy-admin
    percy-admin
標籤
如何安裝擴充功能 建立擴充功能