# @gitlab/frontend-tests 中文文档

规范地址：https://npmcn.com/package/%40gitlab/frontend-tests/

版本：0\.2\.0
npm 元数据更新时间：2026-11-13T19:39:01.666Z
中文译文更新时间：2026-11-16T10:59:27.496Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gitlab/frontend-tests
原文对照：https://npmcn.com/package/%40gitlab/frontend-tests/?lang=original
源码仓库：https://gitlab.com/gitlab-org/frontend/toolkit/tests

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

- 包体积（解压后）：327 kB，52 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：msw ^2\.0\.0，@jest/types \>=29，@testing-library/dom \>=9
- 首次发布：2026-10-05T09:01:01.086Z
- 最新版本发布：2026-11-13T19:39:01.275Z
- 近 30 天下载量：65244（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

GitLab 前端软件包可重复使用的测试基础设施

## 安装

```sh
npm install @gitlab/frontend-tests
```

也可以使用：`pnpm add @gitlab/frontend-tests`、`yarn add @gitlab/frontend-tests`、`bun add @gitlab/frontend-tests`

## README

# @ gitlab/ 前端测试

GitLab 拥有的前端软件包的可再使用的测试基础设施. 它包括一个用于单元测试的共享Jest配置和一个前端集成测试设置工厂. 每个软件包可以在不复制文件或遵循许多人工步骤的情况下设置其测试基础设施.

## 安装

```sh
pnpm add -D @gitlab/frontend-tests
```

## 发展

该包被用TypeScript来书写,并随卷而建. 测试使用Rstest. Linting使用ESLint 9并有平面配置和打字-slint.

`tsconfig.json` 是编辑器,并且 `pnpm typecheck` 配置并覆盖测试. `tsconfig.build.json` 把它扩展为卷起 不包括测试,所以他们不参加 `dist/`。 。 。 .

相对进口 `src/` 携带一个 `.js` 扩展`./types.js`),哪个类型脚本映射到 `.ts` 来源. 释放的 `.d.ts` 文件保存这些描述符,其中 `node16` 模块解析需要。 卷起后, `scripts/emit_cjs_types.mjs` 复制次数 `.d.ts` 改为 `.d.cts` 双胞胎 `require` 导出条件, 因此常见JS TypeScript 消费者也会解决类型问题 . `lodash-es` 捆绑到 `dist/` 因为它只载运无害环境管理;唯一的运行时间依赖是 `@whatwg-node/fetch`。 。 。 .

```sh
pnpm install      # install dependencies
pnpm test         # run tests
pnpm build        # build dist/ (ESM, CJS and .d.ts)
pnpm lint         # run ESLint
pnpm typecheck    # run tsc --noEmit
```

## 添加模块

1.  添加模块 `src/`。 。 。 .
2.  旁边添加测试 `*.test.ts`。 。 。 .
3.  将公共API从 `src/index.ts`。 。 。 . 将几个模块共享的数据形状或消费者自写的数据形状放入 `src/integration/types.ts`。保留一个类型,描述一个函数的参数或该函数旁边的返回值。 不导出执行细节 。 以单个字母命名通用参数( N)`T`, (中文(简体) ), `K`, (中文(简体) ), `V`)或带有描述性说明 `Type` 后缀 (`DataType`),从来没有与a `T` 前缀; ESLint 执行此选项.
4.  将新条目添加到 `input` 地图在 `rollup.config.js`,改为 `exports` 财务报告和审定财务报表 `typesVersions` 内 `package.json`,并添加根解析器根根根(见Cauders)。 这个是作为子路径出版的 `@gitlab/frontend-tests/<name>`。 。 。 .

## 综合测试核心

这个包持有GitLab前端集成测试的框架核心. 这些测试在jsdom上装了一个真正的Vue应用. 他们与Mock Service Worker(MSW)在网络层拦截了GraphQL和REST请求. 核心提供固定加载,固定变体,请求捕获和MSW服务器接线. 它还提供Jest配置工厂和MSW所需的多填充.

### 模块

`@gitlab/frontend-tests/integration` 这是核心。 出口:

-   固定设施: `loadFixturesMap(basePath)`, (中文(简体) ), `matchFixture`, (中文(简体) ), `isValidGraphqlFixture`, (中文(简体) ), `setFixtureData`, (中文(简体) ), `setFixtureErrors`, (中文(简体) ), `setFixtureItemsCount`, (中文(简体) ), `createFixturePaginator`。 。 。 . `loadFixturesMap` 读取每个 `*.json` 在目录中的文件,并按 CamameCased 操作名键取结果.
-   固定变体 : `defineFixtureVariants`, (中文(简体) ), `defineRestFixtureVariants`, (中文(简体) ), `setQueryVariant`, (中文(简体) ), `activateVariant`, (中文(简体) ), `getActiveVariant`, (中文(简体) ), `getVariant`, (中文(简体) ), `resetAllVariants`, (中文(简体) ), `dumpRegistry`。 。 。 .
-   请求抓取 : `captureRequest`, (中文(简体) ), `capturedRequests`, (中文(简体) ), `resetCapturedRequests`, (中文(简体) ), `snapshotRequests`, (中文(简体) ), `expectGraphQLCalls`, (中文(简体) ), `lastRequestVariables`, (中文(简体) ), `captureMissingOperation`, (中文(简体) ), `missingOperations`, (中文(简体) ), `clearMissingOperations`。 。 。 .
-   MSW 线程 : `buildHandlers(featureHandlers, restEndpoints)` 财务报告和审定财务报表 `createServer(featureHandlers, restEndpoints)`。 。 。 . `buildHandlers` 创建一个 `graphql.operation` 处理器,按顺序测试每个特性解析器。 它还增加了REST端点处理器和可回答400的全集. `createServer` 构建一个 `msw/node` 服务器来自这些处理器.
-   `baseMetadata`。 。 。 .
-   消费者类型: `GraphqlFixture`, (中文(简体) ), `GraphqlFixtureInput`, (中文(简体) ), `GraphqlVariables`, (中文(简体) ), `FeatureHandler`, (中文(简体) ), `RestEndpoint`, (中文(简体) ), `RestFixture`, (中文(简体) ), `FixtureVariants`, (中文(简体) ), `CapturedRequest` 财务报告和审定财务报表 `RequestCounts`。 。 。 . `setQueryVariant` 从变位键中取出其活性名称, 所以 `setQueryVariant(constant).withError()` 与传递到 `defineFixtureVariants`。 。 。 .

`@gitlab/frontend-tests/integration/polyfills/text-encoding` 财务报告和审定财务报表 `@gitlab/frontend-tests/integration/polyfills` 是热闹 `setupFiles` 条目,按顺序排列。 第一个 `TextEncoder` 财务报告和审定财务报表 `TextDecoder` 打开 `global`。第二个增加了网络流, `BroadcastChannel`,以及 `fetch`, (中文(简体) ), `Request`, (中文(简体) ), `Response` 财务报告和审定财务报表 `Headers` 从 `@whatwg-node/fetch`。 。 。 .

`@gitlab/frontend-tests/integration/jest-config` 出口 `createFrontendIntegrationConfig(config)` 财务报告和审定财务报表 `MSW_ESM_DEPENDENCIES`。 。 。 .

`@gitlab/frontend-tests/integration/setup-budget` 财务报告和审定财务报表 `@gitlab/frontend-tests/integration/setup-budget-lint` 说明如下: [等待预算](https://npmcn.com/package/%40gitlab/frontend-tests/#readme-wait-budgets)。 。 。 .

### 游戏配置

将现有的杰斯特配置传递给工厂. 它带着应用的集成覆盖返回一个副本 .

```js
const { createFrontendIntegrationConfig } = require('@gitlab/frontend-tests/integration/jest-config');
const baseConfig = require('./jest.config.base');

module.exports = createFrontendIntegrationConfig({
  ...baseConfig,
  setupFilesAfterEnv: ['<rootDir>/spec/integration/test_setup.js'],
});
```

工厂改变了这些东西:

-   添加只依赖无害环境管理的 msw (`rettime`, (中文(简体) ), `until-async`, (中文(简体) ), `@open-draft/*`改为: `transformIgnorePatterns` 许可列表 .
-   将两个多填充项附加到 `setupFiles`首先,文本编码.
-   清除 `testPathIgnorePatterns`。 。 。 .
-   禁用全局假定时器 .
-   设定 `testTimeout` 到20000年,当地为7000年.

它不会触摸 `setupFilesAfterEnv`,模块别名或测试环境。 那些留在消费者身边.

`msw` v2为同级依赖,以及 `@jest/types` 是一个可选的对等端, 仅限 TypeScript 客户使用 `jest-config` 需要帮助. `@whatwg-node/fetch` 是唯一的正常依赖; `lodash-es` 被捆绑.

### 等待预算

`setupBeforeEach` 让启动应用程序的等待预算比其他Spec还要长,没有通过帮助者的旗帜线. 打电话 `installSetupBudget` 从a `setupFilesAfterEnv` 文件 :

```js
import { installSetupBudget } from '@gitlab/frontend-tests/integration/setup-budget';

installSetupBudget({ timeout: 3000 });
```

两种选择都是可选的:

-   `timeout`:普通等车的上限. 默认为3000.
-   `setupTimeout`: 内部等待的天花板 `setupBeforeEach`默认 CI 为 15000, 本地为 6000。 它必须留在下面 `testTimeout` 那个 `createFrontendIntegrationConfig` 套装(20 000 CI, 当地7 000),或 `installSetupBudget` 掷出. 消费者超越 `testTimeout` 未选中.

`installSetupBudget` 安装一个 `@testing-library/dom` `asyncWrapper` 并揭露 `setupBeforeEach` 作为一个全球. `setupBeforeEach(fn)` 经常登记 `beforeEach`。每次等待时 `fn` 运行,包括等待 内部的帮助 它叫,得到 `setupTimeout`。其他的等待会得到 `timeout`钩子按申报顺序运行,所以 `beforeEach` 以上声明 `setupBeforeEach` 在同一块中运行 `timeout`明确 `timeout` 但慢等日志对照预算衡量它. `installSetupBudget` 链到一个 `asyncWrapper` 安装在它之前。 类型脚本规格获取 `setupBeforeEach` 从导入 `installSetupBudget`。 。 。 .

```js
describe('when the item has labels', () => {
  setupBeforeEach(async () => {
    mountApp();
    await waitForElement(findList);
  });

  describe('when a label is removed', () => {
    beforeEach(() => removeLabel()); // regular budget

    it('updates the list', async () => {
      await waitForElement(findEmptyState); // regular budget
    });
  });
});
```

使用其允许运行时间的三分之二的等待时间记录在 `console.log` 作为 `[integration] slow wait` 或者说 `[integration] slow setup wait`时 `JEST_INTEGRATION_SLOW_WAITS_FILE` 设置时,每个慢等作为JSON行附加在该文件上: `{ file, test, elapsedMs, ceilingMs, phase }`时 `phase` 实值 `setup` 或者说 `test` (单位:千美元)`WAIT_PHASE`) (中文(简体) ).

`@gitlab/frontend-tests/integration/setup-budget-lint` 出口 `SETUP_BUDGET_RESTRICTED_SYNTAX` 财务报告和审定财务报表 `SETUP_BUDGET_GLOBALS` 为ESLint平面配置. ESLint保留一个 `no-restricted-syntax` 设置每个文件匹配,从而将条目分散到现有的列表中:

```js
import {
  SETUP_BUDGET_GLOBALS,
  SETUP_BUDGET_RESTRICTED_SYNTAX,
} from '@gitlab/frontend-tests/integration/setup-budget-lint';

export default [
  {
    files: ['spec/integration/**/*_spec.js'],
    languageOptions: { globals: SETUP_BUDGET_GLOBALS },
    rules: { 'no-restricted-syntax': ['error', ...SETUP_BUDGET_RESTRICTED_SYNTAX] },
  },
];
```

规则:

-   每个测试最多一个 `setupBeforeEach`A级 `setupBeforeEach` 内置 a `describe` 上面已经有一个 是一个错误, 并且两个在同一块.
-   等待者不设置自己的 `timeout`。如果等待真的不能更快,请禁用该行的规则并说原因.

Lint条目生活在自己的子路径中,所以一个ESLint配置不会加载测试运行时间.

`@testing-library/dom` 是一个可选的同伴依赖关系,仅此而已 `setup-budget` 需要帮助。 预算不出口自 `@gitlab/frontend-tests/integration`,因此只使用固定装置的消费者和服务器不需要.

### 抓到他们了

-   装入多填充器通过 `setupFiles`没有 `setupFilesAfterEnv`。 。 。 . `msw/node` 读取这些全局,而其模块正文则评估,所以它们必须在加载前存在. 在主条目之前保留文本编码条目 : `@whatwg-node/fetch` 需求 `TextDecoder` 在装入时间, 捆绑商抬起进口, 所以一个文件不能保证订单.
-   根层 `integration.js` 财务报告和审定财务报表 `integration/*.js` 文件是忽略 `exports` 字段,例如 Webpack 4 和 ESLint 导入解析器。 节点和杰斯特从不装货 每个新子路径都加一个.
-   确定每个导入解析到此软件包的同一份副本 。 变体登记和被捕获请求存储是模块级单子. 有了两个拷贝,一个Spec中被激活的变体对处理器来说是看不见的.

## 出版

该套件被发布到公共npm注册处(registry.npmjs.org),而不是GitLab套件注册处. 仅 `dist/` 现予公布.

出版使用 npm 信任的出版与 OIDC. 这个 `publish` 任务从 GitLab CI 获得寿命短的ID符 ()`id_tokens`,观众 `npm:registry.npmjs.org`) (中文(简体) ). 无 npm 令牌被存储在 CI 变量中 。 成套材料均附有出处证明.

这个 `publish` 任务只运行于匹配的 git 标记 `v<digits>`,例如 `v0.1.0`。它运行在擦拭、打字、测试和建立通关之后.

要释放:

1.  将修改合并到 `main`。 。 。 .
2.  创建并按下标签 `vX.Y.Z` 打开 `main`。 。 。 .

标记管发布包. 这个 `publish` 任务集 `version` 内 `package.json` 在发布前从标签中跳出,所以不需要版本-弹出合并请求. 释放不更新承诺 `version`;标签为权威. `package.json` 携带占位符 `0.0.0-development`,它从未出版。 别用手碰它 要检查放出什么, 请运行 `npm view @gitlab/frontend-tests version`,或查看项目概览的最新版本.

之后 `publish` 成功, 时间 `release` 任务为标签创建 GitLab 发布,并带有一行描述和与 npm 包的链接。 它不会运行,如果 `publish` 失败,所以发布总是表示版本在npm上.

标记必须是 `vMAJOR.MINOR.PATCH`后缀(例如: `v1.0.0-rc.1`),或 `publish` 工作失败。 稳定版本随同 `latest` dist-tag; 预发版本(包含 `-`使用 `next` ditt-tag,这样它们不会取代没有版本或标签的消费者安装的稳定放出.

### 一次性设置

这是在第一个CI发布前需要的. 有出版权的人 `@gitlab` npm组织必须这样做.

1.  从登录的机器上手工发布第一个版本 `npm publish --access public`。可信任的出版商被设定在 npmjs.com 上的现有软件包设置上,因此软件包必须先存在.
2.  在 npmjs.com 上,打开软件包设置并找到信任的发布器部分. 选择 GitLab CI/ CD 并输入 :
    -   命名空间 : `gitlab-org/frontend/toolkit`
    -   项目名称 : `tests`
    -   顶级 CI 文件路径 : `.gitlab-ci.yml`
    -   允许 `npm publish`
3.  可选:在"出版访问"下,选择"需要双因子认证并禁止发信".

在此之后,标签管自行发布.

## 常见问题

### @gitlab/frontend-tests 是什么？

GitLab 前端软件包可重复使用的测试基础设施

### 如何安装 @gitlab/frontend-tests？

在项目目录运行 npm install @gitlab/frontend-tests，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：msw（^2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gitlab/frontend-tests 支持 TypeScript 吗？

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

### @gitlab/frontend-tests 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gitlab/frontend-tests 需要什么版本的 Node\.js？

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

### @gitlab/frontend-tests 可以商用吗？

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

### @gitlab/frontend-tests 的下载量有多少？

根据 npm 官方下载统计，@gitlab/frontend-tests 在 2026/10/17 – 2026/11/15 这 30 天内被下载 65,244 次，日均约 2,175 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gitlab/frontend-tests 还在维护吗？

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

