@gitlab/frontend-tests

中文文档
0.2.0发布于 2026/11/14MITTypeScriptESM + CJS构建来源已验证近 30 天下载 6.5万

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

中文使用文档
文档目录10 节
  1. 安装
  2. 发展
  3. 添加模块
  4. 综合测试核心
  5. 模块
  6. 游戏配置
  7. 等待预算
  8. 抓到他们了
  9. 出版
  10. 一次性设置

@ gitlab/ 前端测试

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

安装

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。 。 。 .

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 说明如下: 等待预算。 。 。 .

游戏配置

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

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 文件 :

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。 。 。 .

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 设置每个文件匹配,从而将条目分散到现有的列表中:

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] },
  },
];

规则:

  • 每个测试最多一个 setupBeforeEachA级 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 共发布 9 个版本,首次发布于 2026/10/05;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.2.0latest2026/11/142 天前
0.1.52026/11/079 天前
0.1.5-rc.1next2026/11/069 天前
0.1.5-rc.02026/11/069 天前
0.1.42026/10/2917 天前
0.1.32026/10/1730 天前

关于 @gitlab/frontend-tests 的常见问题

@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 和提交记录判断。