Nx 插件 E2E 测试工程生成指南使用 nx/plugin:e2e-project 生成器搭建插件端到端测试【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nxnx/plugin包提供的e2e-project生成器用于为已存在的 Nx 插件自动搭建端到端E2E测试工程它默认生成基于 Jest 的测试项目也支持切换到 Vitest。本文以仓库中的官方文档 e2e-project-examples.md 为主线结合生成器的参数 Schema、核心实现与单元测试完整讲解命令用法、全部参数、生成产物与底层工作原理帮助你为插件写出真正可运行的端到端测试。e2e-project 生成器能做什么在 Nx 中插件Nx Plugin的开发流程通常包括编写生成器generator与执行器executor而验证它们在真实工作区中是否按预期工作需要一套 E2E 测试工程它会在测试环境中临时创建一个全新的 Nx 工作区把刚构建的插件发布到本地 npm registry再在临时工作区中安装该插件并执行相关命令来验证行为。e2e-project生成器generators.json 中注册为e2e-project正是为此服务的脚手架给定一个已存在的插件项目它会生成一个名为pluginName-e2e的测试工程并配置好基于 Jest 或 Vitest 的e2etarget通过 Verdaccio 搭建本地 npm registry将插件发布后供测试工作区安装一个包含默认冒烟测试的*.spec.ts文件验证插件可以被安装到新建的工作区与插件项目之间的隐式依赖关系。核心参数一览生成器的全部参数定义在 schema.json 中其中pluginName与npmPackageName为必填项参数类型默认值必填说明pluginNamestring-是待测试插件的项目名x-priority: importantnpmPackageNamestring-是插件发布到 npm 时的包名x-priority: importantpluginOutputPathstring-重要插件构建后的输出路径x-priority: importanttestRunnerjest|vitestjest否E2E 测试使用的测试运行器projectDirectorystring项目名否插件所在目录决定 E2E 工程放置位置linternone|eslint|oxlint工作区当前使用的 linter否用于运行 lint 检查的工具jestConfigstring-否Jest 配置文件路径minimalbooleanfalse否生成最小化 E2E 工程不生成默认 executor/generator 的测试useProjectJsonboolean-否使用project.json承载 Nx 配置而不是内联到package.jsonskipFormatbooleanfalse否跳过文件格式化内部选项其中testRunner由枚举约束只能取jest或vitest默认jest。如果省略testRunner生成器内部会执行options.testRunner options.testRunner ?? jest见 e2e.ts因此默认即 Jest 方案。使用 Jest 的 E2E 工程默认方案官方文档给出的第一个示例是基于 Jest 的默认用法。假设插件项目名为my-plugin构建输出到dist/my-pluginnpm 包名为my-plugin执行nx g nx/plugin:e2e-project --pluginName my-plugin --npmPackageName my-plugin --pluginOutputPath dist/my-plugin该命令会在工作区生成my-plugin-e2e项目。从 e2e.spec.ts 的断言可以还原出生成的工程结构与关键配置my-plugin-e2e/tsconfig.json继承根目录tsconfig.base.json若不存在tsconfig.base.json则回退为继承根tsconfig.json见 e2e.spec.tsmy-plugin-e2e/src/my-plugin.spec.ts默认冒烟测试文件my-plugin-e2e/jest.config.ctsJest 配置使用ts-jest做 TypeScript 转换并配置globalSetup/globalTeardown指向本地 registry 脚本my-plugin-e2e/tsconfig.spec.json测试专用的 TypeScript 配置项目targets.e2eexecutor 为nx/jest:jestdependsOn: [^build]options.jestConfig指向my-plugin-e2e/jest.config.cts并开启runInBand: true见 e2e.spec.ts项目与插件之间建立了隐式依赖implicitDependencies: [my-plugin]见 e2e.spec.ts。Jest 配置的生成逻辑Jest 方案的配置由addJest函数完成e2e.ts其核心步骤为注册my-plugin-e2e项目配置projectType: applicationsourceRoot: root/src调用nx/jest的configurationGenerator以targetName: e2e生成 Jest 配置通过addLocalRegistryScripts生成tools/scripts/start-local-registry.ts与tools/scripts/stop-local-registry.ts并写入 Jest 配置的globalSetup/globalTeardown为e2etarget 补上dependsOn: [^build]与runInBand: true。生成的jest.config.cts大致如下以非 TS solution 布局为例见 e2e.spec.tsmodule.exports { displayName: my-plugin-e2e, preset: ../jest.preset.js, transform: { ^.\\.[tj]s$: [ts-jest, { tsconfig: rootDir/tsconfig.spec.json }], }, moduleFileExtensions: [ts, js, html], coverageDirectory: ../coverage/my-plugin-e2e, globalSetup: ../tools/scripts/start-local-registry.ts, globalTeardown: ../tools/scripts/stop-local-registry.ts, };注意runInBand: true与dependsOn: [^build]的组合^build保证在测试启动前先构建插件并将产物发布到本地 registryrunInBand则确保测试串行执行避免多个 E2E 套件并发抢占共享的临时目录。使用 Vitest 的 E2E 工程官方文档的第二个示例是切换到 Vitest 的用法只需在命令中追加--testRunner vitestnx g nx/plugin:e2e-project --pluginName my-plugin --npmPackageName my-plugin --pluginOutputPath dist/my-plugin --testRunner vitestVitest 方案由addVitest函数实现e2e.ts与 Jest 方案有几处关键差异调用nx/vitest的configurationGenerator以testTarget: e2e生成配置并指定testEnvironment: node、coverageProvider: none见 e2e.tse2etarget 的 executor 为nx/vitest:test同样配置dependsOn: [^build]并额外设置maxWorkers: 1与isolate: false见 e2e.spec.ts——这是因为多个测试套件共享tmp/test-project目录必须串行执行且 Vitest 4 移除了poolOptions嵌套选项也无法在 executor 的 argv 往返中存活因此使用标量选项Vitest 没有globalTeardown选项其globalSetup文件必须同时导出setup与teardown。因此生成器会创建tools/scripts/vitest-global-setup.ts包装器e2e.ts内容为export { default as setup } from ./start-local-registry; export { default as teardown } from ./stop-local-registry;若缺少teardownsetup 阶段启动的 Verdaccio 进程会在测试结束后残留见 e2e.spec.ts 的对应断言。生成器会在vitest.config.ts或vitest.config.mts的test配置块中注入globalSetup路径。一个值得注意的细节nx/vitest只会推断testtarget如果没有显式的e2etargetnx e2e命令就不存在^build也就不会在本地 registry 发布插件前运行见 e2e.spec.ts 的测试说明。因此 Vitest 方案的e2etarget 是显式注册的。底层原理临时工作区、本地 registry 与冒烟测试E2E 测试之所以能验证插件的真实行为靠的是 e2e.ts 中编排的完整流程校验插件存在validatePlugin会读取插件的项目配置若项目不存在则抛出Project name pluginName doesnt not exist.e2e.ts并在 e2e.spec.ts 中通过正反两个用例验证生成工程文件基于模板files/目录渲染my-plugin-e2e下的文件配置 Verdaccio 本地 registrysetupVerdaccio与addLocalRegistryScripts一起完成本地 npm registry 的搭建与启停脚本生成按testRunner分支接入 Jest 或 Vitest解除插件的 private 标记updatePluginPackageJson会删除插件package.json中的private字段因为发布到本地 registry 需要非私有包e2e.ts按需配置 lint 与 TS solution 工程。默认冒烟测试模板生成的测试文件来自模板simplePluginName.spec.ts__tmpl__其测试策略是beforeAll中通过createTestProject()使用create-nx-workspacelatest在tmp/test-project目录创建一个全新的临时工作区--preset apps --nxCloudskip --no-interactive随后把构建好的插件以e2e版本标签安装进去安装预算为 300 秒beforeAll(..., 300_000)因为该 hook 会同步执行两次安装必须覆盖冷包管理器缓存场景见模板文件注释以及 e2e.spec.ts 中预算不得低于 240_000 的回归测试it(should be installed)通过执行包管理器的 list 命令验证插件确实被安装npm ls在未正确安装时会失败afterAll递归清理临时工作区。运行 E2E 测试nx e2e my-plugin-e2e高级选项与边界情况控制项目放置位置projectDirectory当插件位于嵌套目录如namespace/my-plugin时可通过projectDirectory指定生成的 E2E 工程会落到directory-e2e下nx g nx/plugin:e2e-project --pluginName my-plugin --npmPackageName my-plugin --pluginOutputPath dist/namespace/my-plugin --projectDirectory namespace/my-plugin此时项目根目录为namespace/my-plugin-e2e见 e2e.spec.ts。最小化工程minimal设置--minimal后生成器不会生成针对默认 executor 和 generator 的测试适合只想验证插件可安装、可加载的场景。Lint 配置linter--linter支持eslint、oxlint或none默认继承工作区现有 lint 工具。指定--linter eslint时会生成my-plugin-e2e/eslint.config.mjs内容为导入根配置并展开import baseConfig from ../eslint.config.mjs; export default [...baseConfig];见 e2e.spec.ts 的快照断言。TypeScript solution 布局当工作区采用 TS solution 布局package.json中配置workspaces、根tsconfig.json使用references时生成器会走isTsSolutionSetup分支为 E2E 工程生成独立的package.json把新的 tsconfig 引用追加到根tsconfig.json并更新工作区文件Jest 转换器也随之切换为swc/jest并生成.spec.swcrc见 e2e.spec.ts。总结nx/plugin:e2e-project生成器把「为插件搭建端到端测试工程」这一重复性工作封装为一条命令默认 Jest 方案nx g nx/plugin:e2e-project --pluginName my-plugin --npmPackageName my-plugin --pluginOutputPath dist/my-pluginVitest 方案追加--testRunner vitest核心机制构建插件 → 发布到 Verdaccio 本地 registry → 在create-nx-workspace创建的临时工作区中安装e2e版本插件 → 冒烟测试验证安装成功。其参数定义、生成逻辑与全部行为均可在仓库中直接追溯schema.json、e2e.ts 与 e2e.spec.ts模板文件位于 files 目录。阅读这些文件可以进一步了解每个选项对生成产物的具体影响并按需裁剪你的插件测试策略。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考