Storycap
Storycap 会抓取你的 Storybook 并生成截图图像。它主要负责生成可视化测试所需的图像，例如 reg-suit。
特性
- :camera: 通过 Puppeteer 对每个 story 进行截图。
- :zap: 速度极快。
- :package: 零配置。
- :rocket: 提供灵活的截图选项。
- :tada: 独立于任何 UI 框架（React、Angular、Vue 等...）
安装
$ npm install storycap
或
$ npm install storycap puppeteer
安装 puppeteer 是可选的。请参阅 Chromium 版本 获取更多详细信息。
快速开始
Storycap 有两种运行模式。一种是“简单模式”，另一种是“托管模式”。
在简单模式下，你无需配置 Storybook。只需提供 Storybook 的 URL，例如
$ npx storycap http://localhost:9001
你可以通过 --serverCmd 选项启动你的服务器。
$ storycap --serverCmd "start-storybook -p 9001" http://localhost:9001
当然，你可以使用预构建的 Storybook
$ build-storybook -o dist-storybook
$ storycap --serverCmd "npx http-server dist-storybook -p 9001" http://localhost:9001
此外，Storycap 还可以抓取已构建并托管的 Storybook 页面
$ storycap https://next--storybookjs.netlify.app/vue-kitchen-sink/
托管模式
设置 Storybook
如果你想控制 stories 的捕获方式（时机、大小等...），请使用托管模式。
首先，将 storycap 添加到你的 Storybook 配置文件中
/* .storybook/main.js */
module.exports = {
stories: ['../src/**/*.stories.@(js|mdx)'],
addons: [
'@storybook/addon-actions',
'@storybook/addon-links',
'storycap', // <-- Add storycap
],
};
接下来，使用 withScreenshot 装饰器来指定 Storycap 如何捕获你的 stories。
/* .storybook/preview.js */
import { withScreenshot } from 'storycap';
export const decorators = [
withScreenshot, // Registration the decorator is required
];
export const parameters = {
// Global parameter is optional.
screenshot: {
// Put global screenshot parameters(e.g. viewport)
},
};
[!NOTE] 你可以使用
addParameters和screenshot键来设置截图配置。
设置你的 stories（可选）
你也可以通过 parameters 在特定的 stories 文件中覆盖全局截图选项。
import React from 'react';
import MyComponent from './MyComponent';
export default {
title: 'MyComponent',
component: MyComponent,
parameters: {
screenshot: {
delay: 200,
},
},
};
export const Normal = {};
export const Small = {
args: {
text: 'small',
},
parameters: {
screenshot: {
viewport: 'iPhone 5',
},
},
};
运行 storycap 命令
$ npx start-storybook -p 9009
$ npx storycap http://localhost:9009
或者你可以通过 --serverCmd 选项执行一行命令
$ npx storycap http://localhost:9009 --serverCmd "start-storybook -p 9009"
API
withScreenshot
一个 Storybook 装饰器，用于通知 Storycap 捕获 stories。
类型 ScreenshotOptions
ScreenshotOptions 对象作为 addParameters 参数或 withScreenshot 参数的 screenshot 键的值可用。
interface ScreenshotOptions {
delay?: number; // default 0 msec
waitAssets?: boolean; // default true
waitFor?: string | () => Promise<void>; // default ""
fullPage?: boolean; // default true
hover?: string; // default ""
focus?: string; // default ""
click?: string; // default ""
skip?: boolean; // default false
viewport?: Viewport;
viewports?: string[] | { [variantName]: Viewport };
variants?: Variants;
waitImages?: boolean; // default true
omitBackground?: boolean; // default false
captureBeyondViewport?: boolean; // default true
clip?: { x: number; y: number; width: number; height: number } | null; // default null
}
delay：捕获前的等待时间 [毫秒]。waitAssets：如果设置为 true，Storycap 将等待 story 请求的所有资源（例如waitFor：如果你设置一个函数返回Promise，Storycap 将等待该 Promise 被解决。你也可以设置一个返回Promise的全局函数的名称。fullPage：如果设置为 true，Storycap 将捕获 story 的整个页面。focus：如果设置有效的 CSS 选择器字符串，Storycap 将在聚焦匹配该选择器的元素后进行捕获。hover：如果设置有效的 CSS 选择器字符串，Storycap 将在悬停匹配该选择器的元素后进行捕获。click：如果设置有效的 CSS 选择器字符串，Storycap 将在点击匹配该选择器的元素后进行捕获。skip：如果设置为 true，Storycap 将取消捕获相应的 stories。viewport，viewports：参见下面的类型Viewport部分。variants：参见下面的类型Variants部分。waitImages：已弃用。请使用waitAssets。如果设置为 true，Storycap 将等待 story 中的omitBackground：如果设置为 true，Storycap 将省略页面背景，允许生成透明截图。注意 Storybook 主题也需要是透明的。captureBeyondViewport：如果设置为 true，Storycap 将捕获视口之外的截图。另请参见 Puppeteer API 文档。clip：如果设置，Storycap 将仅捕获由 x/y/width/height 边界限定的屏幕区域。
类型 Variants
Variants 用于从一个 story 生成 多个 PNG。
type Variants = {
[variantName: string]: {
extends?: string | string[]; // default: ""
delay?: number;
waitAssets?: boolean;
waitFor?: string | () => Promise<void>;
fullPage?: boolean;
hover?: string;
focus?: string;
click?: string;
skip?: boolean;
viewport?: Viewport;
waitImages?: boolean;
omitBackground?: boolean;
captureBeyondViewport?: boolean;
clip?: { x: number; y: number; width: number; height: number } | null;
};
};
extends：如果设置为其他变体的名称（或其名称数组），此变体将继承其他变体选项。并且此变体生成的文件名将带有后缀，例如_${parentVariantName}_${thisVariantName}。
类型 Viewport
Viewport 与 Puppeteer 视口接口 兼容。
type Viewport =
| string
| {
width: number; // default: 800
height: number; // default: 600
deviceScaleFactor: ?number; // default: 1,
isMobile?: boolean; // default: false,
hasTouch?: boolean; // default: false,
isLandscape?: boolean; // default: false,
};
[!NOTE] 如果设置为字符串，应选择一个有效的 设备名称。
Viewport 值可在 viewports 字段中使用，例如
addParameters({
screenshot: {
viewports: {
large: {
width: 1024,
height: 768,
},
small: {
width: 375,
height: 668,
},
xsmall: {
width: 320,
height: 568,
},
},
},
});
函数 isScreenshot
function isScreenshot(): boolean;
返回当前进程是否在 Storycap 浏览器中运行。这对于仅在 Storycap 中更改 stories 的行为很有用（例如，禁用 JavaScript 动画）。
命令行选项
usage: storycap [options] storybook_url
Options:
--help Show help [boolean]
--version Show version number [boolean]
-o, --outDir Output directory. [string] [default: "__screenshots__"]
-p, --parallel Number of browsers to screenshot. [number] [default: 4]
-f, --flat Flatten output filename. [boolean] [default: false]
-i, --include Including stories name rule. [array] [default: []]
-e, --exclude Excluding stories name rule. [array] [default: []]
--delay Waiting time [msec] before screenshot for each story. [number] [default: 0]
-V, --viewport Viewport. [array] [default: ["800x600"]]
--disableCssAnimation Disable CSS animation and transition. [boolean] [default: true]
--disableWaitAssets Disable waiting for requested assets [boolean] [default: false]
--trace Emit Chromium trace files per screenshot. [boolean] [default: false]
--silent [boolean] [default: false]
--verbose [boolean] [default: false]
--forwardConsoleLogs Forward in-page console logs to the user's console. [boolean] [default: false]
--serverCmd Command line to launch Storybook server. [string] [default: ""]
--serverTimeout Timeout [msec] for starting Storybook server. [number] [default: 60000]
--shard The sharding options for this run. In the format <shardNumber>/<totalShards>.
<shardNumber> is a number between 1 and <totalShards>. <totalShards> is the total
number of computers working. [string] [default: "1/1"]
--captureTimeout Timeout [msec] for capture a story. [number] [default: 5000]
--captureMaxRetryCount Number of count to retry to capture. [number] [default: 3]
--metricsWatchRetryCount Number of count to retry until browser metrics stable. [number] [default: 1000]
--viewportDelay Delay time [msec] between changing viewport and capturing. [number] [default: 300]
--reloadAfterChangeViewport Whether to reload after viewport changed. [boolean] [default: false]
--stateChangeDelay Delay time [msec] after changing element's state. [number] [default: 0]
--listDevices List available device descriptors. [boolean] [default: false]
-C, --chromiumChannel Channel to search local Chromium. One of "puppeteer", "canary", "stable", "*"
[string] [default: "*"]
--chromiumPath Executable Chromium path. [string] [default: ""]
--puppeteerLaunchConfig JSON string of launch config for Puppeteer.
[string] [default: "{ "args": ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"] }"]
Examples:
storycap http://localhost:9009
storycap http://localhost:9009 -V 1024x768 -V 320x568
storycap http://localhost:9009 -i "some-kind/a-story"
storycap http://example.com/your-storybook -e "**/default" -V iPad
storycap --serverCmd "start-storybook -p 3000" http://localhost:3000
从一个 story 生成多个 PNG
默认情况下，Storycap 从一个 story 生成一张截图图像。如果你想为一个 story 生成多个 PNG（例如，视口、元素状态变化等...），请使用 variants。
基本用法
例如
import React from 'react';
import MyButton from './MyButton';
export default {
title: 'MyButton',
component: MyButton,
};
export const Normal = {
parameters: {
screenshot: {
variants: {
hovered: {
hover: 'button.my-button',
},
},
},
},
};
上述配置将生成 2 个 PNG
MyButton/normal.pngMyButton/normal_hovered.png
变体键，例如上述示例中的 hovered，用作生成 PNG 文件名的后缀。几乎所有的 ScreenshotOptions 字段都可以作为变体值的字段使用。
注意： variants 本身和 viewports 不允许作为变体的字段。
变体组合
你可以通过 extends 字段组合多个变体。
export const Normal = {
parameters: {
screenshot: {
variants: {
small: {
viewport: 'iPhone 5',
},
hovered: {
extends: 'small',
hover: 'button.my-button',
},
},
},
},
};
上述示例将生成以下文件
MyButton/normal.png(默认MyButton/normal_small.png(派生自small变体MyButton/normal_hovered.png(派生自hovered变体MyButton/normal_small_hovered.png(派生自hovered和small变体
[!NOTE] 你可以使用
viewports选项的键来扩展一些视口，因为viewports字段在内部被扩展为变体。
跨多台计算机并行化
为了跨多台计算机并行处理更多 stories，可以使用 shard 参数。
shard 参数的格式为字符串：<分片编号>/<总分片数>。<分片编号> 是一个介于 1 和 <总分片数> 之间的数字（包含边界）。<总分片数> 是运行执行任务的计算机总数。
例如，使用 --shard 1/1 运行被认为是单台计算机上的默认行为。两台计算机分别运行 --shard 1/2 和 --shard 2/2 将把 stories 分割到两台计算机上。
Stories 根据其 ID 排序后，以循环方式分布到分片中。如果一系列“紧密相连”的 stories 比其他 stories 截图速度慢，它们也应该被均匀分布。
技巧
使用 Docker 运行
使用 regviz/node-xcb。
或者创建你的 Docker 基础镜像，例如
FROM node:18
RUN apt-get update -y \
&& apt-get install -yq \
ca-certificates \
fonts-liberation \
git \
libayatana-appindicator3-1 \
libasound2 \
libatk-bridge2.0-0 \
libatk1.0-0 \
libc6 \
libcairo2 \
libcups2 \
libdbus-1-3 \
libexpat1 \
libfontconfig1 \
libgbm1 \
libgcc1 \
libglib2.0-0 \
libgtk-3-0 \
libnspr4 \
libnss3 \
libpango-1.0-0 \
libpangocairo-1.0-0 \
libstdc++6 \
libx11-6 \
libx11-xcb1 \
libxcb1 \
libxcomposite1 \
libxcursor1 \
libxdamage1 \
libxext6 \
libxfixes3 \
libxi6 \
libxrandr2 \
libxrender1 \
libxss1 \
libxtst6 \
lsb-release \
wget \
xdg-utils
完全控制截图时机
有时你可能想要完全管理截图的时机。如果你有此需求，请使用 waitFor 选项。此参数接受返回 Promise 的函数，或指向返回 Promise 的全局函数的名称。
示例 1
例如，你可以使用 `@storybook/test` 包提供的 screen 函数等待特定的 HTML 元素出现。这在元素延迟渲染时非常有用。
/* MyComponent.stories.js */
import { screen } from '@storybook/test';
export const MyStory = {
screenshot: {
waitFor: async () => {
await screen.findByRole('link');
},
},
};
示例 2
另一个示例，以下设置告诉 Storycap 等待 fontLoading 的解决
<!-- ./storybook/preview-head.html -->
<link rel="preload" href="/some-heavy-asset.woff" as="font" onload="this.setAttribute('loaded', 'loaded')" />
<script>
function fontLoading() {
const loaded = () => !!document.querySelector('link[rel="preload"][loaded="loaded"]');
if (loaded()) return Promise.resolve();
return new Promise((resolve, reject) => {
const id = setInterval(() => {
if (!loaded()) return;
clearInterval(id);
resolve();
}, 50);
});
}
</script>
/* .storybook/preview.js */
import { withScreenshot } from 'storycap';
export const decorators = [withScreenshot];
export const parameters = {
screenshot: {
waitFor: 'fontLoading',
},
};
Chromium 版本
自 v3.0.0 起，Storycap 不再直接使用 Puppeteer。相反，Storycap 按照以下顺序搜索 Chromium 二进制文件
- 已安装的 Puppeteer 包（如果你明确安装了）
- 本地安装的 Canary Chrome
- 本地安装的 Stable Chrome
你可以使用 --chromiumChannel 选项更改搜索渠道，或者使用 --chromiumPath 选项设置可执行的 Chromium 文件路径。
Storybook 兼容性
Storybook 版本
Storycap 已在以下版本中测试通过
- 简单模式
- Storybook v7.x
- Storybook v8.x
- 托管模式
- Storybook v7.x
- Storybook v8.x
另请参见 examples 目录中的包。
UI 框架
Storycap（包括简单模式和托管模式）与特定的 UI 框架无关（例如 React、Angular、Vue.js 等...）。因此，你可以将它与你喜欢的框架一起用于 Storybook :smile: 。
工作原理
Storycap 使用 Puppeteer 访问已启动的页面。
贡献
请参阅 CONTRIBUTING.md。
