# @forgebook/testing 中文文档

规范地址：https://npmcn.com/package/%40forgebook/testing/

版本：0\.1\.8
npm 元数据更新时间：2026-11-01T01:45:43.514Z
中文译文更新时间：2026-11-01T04:47:03.022Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40forgebook/testing
原文对照：https://npmcn.com/package/%40forgebook/testing/?lang=original
项目主页：https://github.com/ensiria/forgebook#readme
源码仓库：https://github.com/ensiria/forgebook

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：365 kB，86 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18
- 运行依赖：3 个
- peer 依赖：vite ^8\.0\.0，vitest ^5\.0\.0，forgebook ^0\.1\.7，@playwright/test ^1\.64\.0
- 首次发布：2026-10-31T02:08:16.326Z
- 最新版本发布：2026-11-01T01:45:43.221Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

从包的故事中进行测试：浏览器中的每个故事和变体都带有斧头、溢出和覆盖、屏幕截图，每个故事都在服务器上呈现。

## 安装

```sh
npm install @forgebook/testing
```

也可以使用：`pnpm add @forgebook/testing`、`yarn add @forgebook/testing`、`bun add @forgebook/testing`

## README

# @forgebook /测试

从包的 [Forgebook](https://www.npmjs.com/package/forgebook) 故事，所以写故事就是写它 测试:

-   **在浏览器中** （剧作家），每个故事和变体（主题，对比，样式表，窄宽度）一个测试：它 由于页面中出现错误而失败 [斧](https://github.com/dequelabs/axe-core) 违反WCAG 2.2 A和AA 元素从父元素中溢出，或者覆盖层在故事框架之外保持开放；
-   **视觉**与参考截图相比，相同的帧，在剧作家容器中，所以字体和渲染 匹配无处不在;
-   **在服务器上** （Vitest），每个故事呈现为字符串，因此没有组件读取 `window` 或者 `document` 虽然它 渲染，并根据其参数检查其控件。

**要求:** `forgebook` ····· `@playwright/test` 1.64+·Vitest 5·Docker用于视觉测试· [麻省理工学院的许可证](https://github.com/ensiria/forgebook/blob/develop/packages/testing/LICENSE)

```sh
npm install --save-dev @forgebook/testing @playwright/test vitest
```

## 设置测试

测试在包本身上运行 **故事的来源** ( `StorySource` 它的目录列表)，在他们的一个文件夹 自己的。下面的例子是一个包，它的故事是 `src/*.stories.tsx` 谁的来源是 `stories/index.ts`：

```ts
// stories/index.ts
/// <reference types="@forgebook/story-format/client" />
import type { StorySource } from "@forgebook/story-format/source";

import files from "../src/*.stories.tsx?forgebook-files";

export const source: StorySource = {
  id: "acme-ui",
  name: "Acme UI",
  files: [files],
  sheets: { required: [], theme: [], restyled: [] }
};
```

### 在浏览器中

六个文件 `test/stories/`． 故事在哪里，与来源的模式相同：

```ts
// test/stories/storyFiles.ts
import { join } from "node:path";

import type { StoryFilesOptions } from "@forgebook/testing/story-files";

export const STORY_FILES: StoryFilesOptions = {
  sourceId: "acme-ui",
  name: "Acme UI",
  root: join(import.meta.dirname, "..", "..", "stories"),
  patterns: ["../src/*.stories.tsx"]
};
```

文件夹和端口，然后是剧作家配置和规格：

```ts
// test/stories/testServer.ts
import type { StoryTestServer } from "@forgebook/testing/playwright";

export const STORY_SERVER: StoryTestServer = { dir: import.meta.dirname, port: 41831, browserPort: 41832 };

// test/stories/playwright.config.ts
import { storyTestConfig } from "@forgebook/testing/playwright";

import { STORY_SERVER } from "./testServer";

export default storyTestConfig(STORY_SERVER);

// test/stories/stories.spec.ts
import { storyBrowserTests } from "@forgebook/testing/browser";

import { STORY_FILES } from "./storyFiles";

storyBrowserTests(STORY_FILES);
```

测试打开的帧页面，以及为其提供服务的Vite配置：

```html
<!-- test/stories/frame.html -->
<!doctype html>
<html lang="en">
  <head><meta charset="utf-8" /><title>Stories</title></head>
  <body><div id="root"></div><script type="module" src="./frame.tsx"></script></body>
</html>
```

```tsx
// test/stories/frame.tsx
import "@forgebook/testing/fonts.css";
import { mountFrame } from "@forgebook/react/frame";

import { source } from "../../stories/index";

const root = document.getElementById("root");
if (root !== null) void mountFrame(root, { sources: [source] });

// test/stories/vite.config.ts
import { react } from "@forgebook/react/vite";
import { storyTestViteConfig } from "@forgebook/testing/vite";

export default storyTestViteConfig(import.meta.dirname, react());
```

然后 `npx playwright install chromium` 一次, `playwright test -c test/stories/playwright.config.ts` 启动 框架页面，并为每个故事和变体(浅色、深色，都有更多的对比，窄宽度，和 结构视图)，通过运行它们的包管理器启动Vite (`vite` 在 `testServer.ts` 的名字 另一个命令)。一个打破规则的故事，其所有变体都失败了； `storyBrowserTests` 也需要 `check`的规则 包本身在每一帧上运行。

### 在服务器上

一个测试文件和一个带有目录插件的Vitest配置，该插件读取源文件 `?forgebook-files` 进口:

```tsx
// test/stories/stories.server.test.tsx
import { reactRenderer } from "@forgebook/react/renderer";
import { storyServerTests } from "@forgebook/testing/server";

import { source } from "../../stories/index";

storyServerTests(source, { renderer: reactRenderer });

// vitest.config.ts
import { react } from "@forgebook/react/vite";
import { forgebookPlugin } from "forgebook/vite";
import { defineConfig } from "vitest/config";

export default defineConfig({
  plugins: [forgebookPlugin({ framework: react() })],
  test: { include: ["test/**/*.test.tsx"] }
});
```

`storyServerTests` 也需要 `wrap`第二次遍历，每个故事都在一个装饰器（一个带有分部的提供商）中 翻译目录)，它的HTML检查。

### 限制了今天

-   视觉测试(`visual.spec.ts`， `visualTestConfig`， `startVisualBrowser`)比较参考系 在剧作家容器中的图像，所以他们需要Docker；本指南还没有涵盖它们，它们模块的TSDoc 所做的。

## 导入和命令

| 导入或命令 | 它是什么？ |
| --- | --- |
| `@forgebook/testing/browser` | 每个故事的浏览器和视觉测试 |
| `@forgebook/testing/server` | 每个故事的服务器渲染测试 |
| `@forgebook/testing/playwright`， `@forgebook/testing/vite` | 测试框架页面的剧作家配置和Vite配置 |
| `forgebook-heights` | 测量每层楼的高度和宽度，用于目录的装载箱 |
| `forgebook-shot` | 打开正在运行的目录中的一个故事，并用图片报告它 |

更多: [Forgebook的自述](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md).

## 常见问题

### @forgebook/testing 是什么？

从包的故事中进行测试：浏览器中的每个故事和变体都带有斧头、溢出和覆盖、屏幕截图，每个故事都在服务器上呈现。

### 如何安装 @forgebook/testing？

在项目目录运行 npm install @forgebook/testing，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（^8\.0\.0）、vitest（^5\.0\.0）、forgebook（^0\.1\.7）、@playwright/test（^1\.64\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 forgebook-shot、forgebook-heights，可以用 npx forgebook-shot 直接运行。

### @forgebook/testing 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @forgebook/testing 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @forgebook/testing 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @forgebook/testing 可以商用吗？

@forgebook/testing 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @forgebook/testing 还在维护吗？

最新版本 0\.1\.8 发布于 2026/11/01（2 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。