在 Nx 工作区中配置与修复 Jestnx/jest 插件、jest.preset.js 与 tsconfig.spec.json 实战指南【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles本篇指南围绕 tsParticles 仓库.opencode/skills体系中关于 Nx 导入nx import时 Jest 集成的完整参考文档展开系统讲解nx/jest/plugin的目标推断机制、jest.preset.js的创建与引用、按框架区分的测试依赖矩阵、tsconfig.spec.json的合规配置以及 Jest 与 Vitest 在同一工作区共存、CI 原子化并行等进阶话题。读完本文你将能够在 Nx 工作区中独立完成 Jest 从目标缺失到全量可跑的完整修复链路并理解每一步背后的插件机制与常见坑点。一、nx/jest的工作原理目标推断从何而来在 Nx 工作区中Jest 的测试目标test并非手写在project.json里而是由插件自动推断产生。nx/jest/plugin会扫描每个项目下的jest.config.{ts,js,cjs,mjs,cts,mts}文件只要发现这些配置文件之一就为该目录对应的项目创建一个test目标。这意味着配置文件的命名与位置直接决定了目标能否被识别。在nx.json中注册插件的方式如下{ plugin: nx/jest/plugin, options: { targetName: test } }其中targetName指定推断出来的目标名默认值为test可按需改名例如与 Vitest 冲突时改为jest-test见下文。执行npx nx add nx/jest时它实际完成两件事在nx.json中注册nx/jest/plugin——这是test目标能被推断的前提。缺少这一步nx run PROJECT:test会直接报错 Cannot find target test。更新namedInputs.production——把测试文件排除在生产构建输入之外避免测试文件改动触发不必要的生产构建缓存失效。这与当前 tsParticles 仓库 nx.json 中namedInputs.production的设计思路一致它只包含{projectRoot}/src/**/*、index.*、package.json、tsconfig*.json等生产相关输入测试文件并不在其中。两个关键 Gotchanx add nx/jest不会创建jest.preset.js。该文件只有在运行生成器如nx/jest:configuration时才会被生成。对于通过nx import导入的项目必须手动创建详见下一节。反过来如果手动创建了jest.preset.js但跳过npx nx add nx/jest插件未注册nx run PROJECT:test依然会失败并提示找不到test目标。两步缺一不可。二、Jest Preset共享配置的根与引用jest.preset.js位于工作区根目录为所有项目提供共享的 Jest 配置包括测试文件匹配模式、ts-jest 转换器、模块解析器、jsdom 环境等。Nx 预设生成的项目 jest 配置都会引用它因此导入时缺失该文件会导致经典的 Cannot find module jest-preset 报错。根jest.preset.js的标准内容const nxPreset require(nx/jest/preset).default; module.exports { ...nxPreset };项目级jest.config.ts的标准形态export default { displayName: my-lib, preset: ../../jest.preset.js, // project-specific overrides };这里有几个必须理解的细节preset的路径是相对路径从项目根目录指向工作区根目录。例如项目位于libs/my-lib时需写../../jest.preset.js。子目录导入时路径会保留原始的相对深度例如依然是../../jest.preset.js只要导入的目标目录深度与源目录深度一致该路径就能正确解析。深度不一致时需要在导入后校正preset路径这是常见的后导入修复项。displayName用于在 Nx 多项目并行输出时区分各项目的测试日志。三、按框架区分的测试依赖矩阵导入项目后需要按项目类型补齐测试依赖。下面按场景拆分核心依赖任何 Jest 项目都必须pnpm add -wD jest ts-jest types/jest nx/jestjest测试运行器本体。ts-jestTypeScript → CommonJS 的转换器是 Jest 默认转换链路的核心。types/jest提供describe、it、expect等全局类型的 TypeScript 定义。nx/jestNx 对 Jest 的插件与预设nx/jest/preset。环境相关依赖DOM 测试React、Vue、浏览器类库需要jest-environment-jsdom因为 Nx 预设默认将环境设为jsdom。Node 测试API、CLI无需额外依赖——Jest 默认环境是node但要注意Nx 预设默认是jsdom纯 Node 项目若沿用 Nx 预设会跑在 jsdom 环境下需要按需覆盖。React 测试pnpm add -wD testing-library/react testing-library/jest-domReact Babel非 ts-jest 转换部分 React 项目常见于较老的 Nx 工作区与 CRA 迁移项目不使用 ts-jest而是在项目jest.config的transform字段中配置babel-jest来处理 JSX 转换pnpm add -wD babel-jest babel/core babel/preset-env babel/preset-react babel/preset-typescript判断时机检查项目jest.config的transform使用的是babel-jest还是ts-jest。若为前者按上述命令补齐 Babel 全家桶这也是文档Tests fail with Cannot use import statement outside a module报错的一大来源——转换器缺失或未正确配置。Vue 测试pnpm add -wD vue/test-utils需要注意Vue 项目通常使用 Vitest 而非 Jest详见 VITE.md导入 Vue 项目时优先确认其测试框架选择。四、tsconfig.spec.json测试代码的类型合规Jest 项目需要独立的tsconfig.spec.json将测试文件纳入 TypeScript 检查范围。标准模板{ extends: ./tsconfig.json, compilerOptions: { outDir: ../../dist/out-tsc, module: commonjs, types: [jest, node] }, include: [ jest.config.ts, src/**/*.test.ts, src/**/*.spec.ts, src/**/*.d.ts ] }导入后最常见的三类问题缺少types: [jest, node]——会导致describe、it、expect在编辑器与类型检查中无法识别报 Cannot find type definition file for jest。缺少module: commonjs——Jest 默认不支持 ESMts-jest 会把代码转译成 CJSmodule不设为commonjs会导致运行期模块格式不匹配。include数组缺失测试文件模式——TypeScript 将不会检查测试文件类型错误被静默放过。五、Jest 与 Vitest 共存同一工作区两种测试框架大型工作区完全可以同时存在 Jest 与 VitestJestNext.js 应用、较老的 React 库、Node 库。Vitest基于 Vite 的 React/Vue 应用与库。nx/jest/plugin与nx/vite/plugin后者推断 Vitest 目标能够无冲突共存因为它们检测的是不同的配置文件jest.config.*与vite.config.*互不干扰。目标命名冲突两者默认都把目标命名为test。如果某个项目同时存在两类配置文件必须为其中一个改名例如{ plugin: nx/jest/plugin, options: { targetName: jest-test } }当前仓库的佐证tsParticles 本身就是一个典型的 Vitest 阵营示例——根 nx.json 的plugins数组中只有nx/plugins/package-json与tsparticles/cli-nx-plugin并无nx/jest/plugin全仓库也找不到任何jest.config.*文件而 utils/tests/vitest.config.ts 明确使用vitest/config的defineConfig并配置了environment: jsdom、coverage.provider: v8与include: [src/tests/*.ts]。这正是插件按配置文件区分框架机制的直观体现——同一工作区中Vitest 项目看vite.config.*Jest 项目看jest.config.*。六、testing-library/jest-dom的 Jest / Vitest 差异从 Jest 迁移到 Vitest或两者并存的工作区jest-dom的导入路径不同Jesttest-setup.ts中import testing-library/jest-dom;Vitesttest-setup.ts中import testing-library/jest-dom/vitest;如果源项目用的是 Jest而目标工作区对该类项目使用 Vitest必须更新导入路径。同时记得把testing-library/jest-dom加入 tsconfig 的types数组确保其匹配器matcher类型对测试文件可见。七、非 Nx 源码导入测试脚本的自动重写陷阱当导入的是没有nx.json的普通 pnpm/npm 工作区时Nx 在初始化阶段会自动重写package.json脚本测试脚本往往被改坏test: jest→test: nx test——若项目没有配置 executor会形成循环调用。test: vitest run→test: nx test run——run变成了一个参数命令直接损坏。修复方式删除所有被重写过的测试脚本。nx/jest/plugin与nx/vite/plugin会从配置文件推断出测试目标package.json里的test脚本反而是冗余且有害的。以当前仓库为参照utils/tests/package.json 中的测试入口是test: vitest run、test:ci: NODE_ENVtest vitest run --maxConcurrency2保持了脚本直呼工具的形态由工作区插件统一推断任务边界——这是 Nx 管理下脚本的推荐形态。八、CI 原子化按文件拆分的并行测试nx/jest/plugin支持把测试按文件拆分供 CI 并行分发使用{ plugin: nx/jest/plugin, options: { targetName: test, ciTargetName: test-ci } }启用后插件会为每个测试文件生成形如test-ci--src/lib/foo.spec.ts的独立目标从而支持 Nx Cloud 的任务分发。该能力在导入阶段不需要但在导入后的 CI 配置阶段非常有用。如果 CI 需要控制并发度可参考仓库中 utils/tests/package.json 的做法用--maxConcurrency之类的参数约束并行上限。九、导入后的常见问题速查表Cannot find target testnx/jest/plugin未在nx.json中注册。运行npx nx add nx/jest或手动补上插件配置。Cannot find module jest-preset工作区根目录缺少jest.preset.js。手动创建内容见第二节。Cannot find type definition file for jest缺少types/jest或tsconfig.spec.json未配置types: [jest, node]。Cannot use import statement outside a modulets-jest未安装或未配置为 transform。检查项目jest.config.ts的transform字段。Snapshot 路径不匹配导入后__snapshots__目录可能内嵌了旧路径。跑一次--updateSnapshot重新生成即可。十、修复顺序两条标准执行路径场景 A子目录导入Nx 源码monorepo 源npx nx add nx/jest——注册插件到nx.json不会创建jest.preset.js。手动创建jest.preset.js内容见第二节。安装核心依赖pnpm add -wD jest jest-environment-jsdom ts-jest types/jest。按框架补测试依赖React 项目装testing-library/react testing-library/jest-domVue 项目装vue/test-utilsBabel 转换的项目再补 Babel 依赖。核对tsconfig.spec.json包含types: [jest, node]。全量验证nx run-many -t test。场景 B整仓库导入非 Nx 源码单项目仓库从package.json删除被 Nx 重写的测试脚本见第七节。npx nx add nx/jest——注册插件同样不会创建 preset。手动创建jest.preset.js。安装依赖与场景 A 相同。核对/修复jest.config.*——确保preset路径指向根jest.preset.js。核对/修复tsconfig.spec.json——按需补types、module、include。全量验证nx run-many -t test。总结Jest 在 Nx 工作区中的落地本质上是插件注册、preset 就位、依赖补齐、类型合规四件事的组合nx/jest/plugin负责从jest.config.*推断test目标jest.preset.js提供跨项目共享配置框架相关的测试依赖矩阵决定了运行环境与断言能力tsconfig.spec.json保证测试代码通过类型检查。掌握这两条修复顺序与五类高频报错无论是子目录导入还是整仓库导入都能让 Jest 测试在 Nx 工作区中稳定运行。若项目实际走 Vitest 路线可继续参考 VITE.md 中的 Vite/Vitest 专项指引。【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Nx 工作区中配置与修复 Jest：@nx/jest 插件、jest.preset.js 与 tsconfig.spec.json 实战指南
在 Nx 工作区中配置与修复 Jestnx/jest 插件、jest.preset.js 与 tsconfig.spec.json 实战指南【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles本篇指南围绕 tsParticles 仓库.opencode/skills体系中关于 Nx 导入nx import时 Jest 集成的完整参考文档展开系统讲解nx/jest/plugin的目标推断机制、jest.preset.js的创建与引用、按框架区分的测试依赖矩阵、tsconfig.spec.json的合规配置以及 Jest 与 Vitest 在同一工作区共存、CI 原子化并行等进阶话题。读完本文你将能够在 Nx 工作区中独立完成 Jest 从目标缺失到全量可跑的完整修复链路并理解每一步背后的插件机制与常见坑点。一、nx/jest的工作原理目标推断从何而来在 Nx 工作区中Jest 的测试目标test并非手写在project.json里而是由插件自动推断产生。nx/jest/plugin会扫描每个项目下的jest.config.{ts,js,cjs,mjs,cts,mts}文件只要发现这些配置文件之一就为该目录对应的项目创建一个test目标。这意味着配置文件的命名与位置直接决定了目标能否被识别。在nx.json中注册插件的方式如下{ plugin: nx/jest/plugin, options: { targetName: test } }其中targetName指定推断出来的目标名默认值为test可按需改名例如与 Vitest 冲突时改为jest-test见下文。执行npx nx add nx/jest时它实际完成两件事在nx.json中注册nx/jest/plugin——这是test目标能被推断的前提。缺少这一步nx run PROJECT:test会直接报错 Cannot find target test。更新namedInputs.production——把测试文件排除在生产构建输入之外避免测试文件改动触发不必要的生产构建缓存失效。这与当前 tsParticles 仓库 nx.json 中namedInputs.production的设计思路一致它只包含{projectRoot}/src/**/*、index.*、package.json、tsconfig*.json等生产相关输入测试文件并不在其中。两个关键 Gotchanx add nx/jest不会创建jest.preset.js。该文件只有在运行生成器如nx/jest:configuration时才会被生成。对于通过nx import导入的项目必须手动创建详见下一节。反过来如果手动创建了jest.preset.js但跳过npx nx add nx/jest插件未注册nx run PROJECT:test依然会失败并提示找不到test目标。两步缺一不可。二、Jest Preset共享配置的根与引用jest.preset.js位于工作区根目录为所有项目提供共享的 Jest 配置包括测试文件匹配模式、ts-jest 转换器、模块解析器、jsdom 环境等。Nx 预设生成的项目 jest 配置都会引用它因此导入时缺失该文件会导致经典的 Cannot find module jest-preset 报错。根jest.preset.js的标准内容const nxPreset require(nx/jest/preset).default; module.exports { ...nxPreset };项目级jest.config.ts的标准形态export default { displayName: my-lib, preset: ../../jest.preset.js, // project-specific overrides };这里有几个必须理解的细节preset的路径是相对路径从项目根目录指向工作区根目录。例如项目位于libs/my-lib时需写../../jest.preset.js。子目录导入时路径会保留原始的相对深度例如依然是../../jest.preset.js只要导入的目标目录深度与源目录深度一致该路径就能正确解析。深度不一致时需要在导入后校正preset路径这是常见的后导入修复项。displayName用于在 Nx 多项目并行输出时区分各项目的测试日志。三、按框架区分的测试依赖矩阵导入项目后需要按项目类型补齐测试依赖。下面按场景拆分核心依赖任何 Jest 项目都必须pnpm add -wD jest ts-jest types/jest nx/jestjest测试运行器本体。ts-jestTypeScript → CommonJS 的转换器是 Jest 默认转换链路的核心。types/jest提供describe、it、expect等全局类型的 TypeScript 定义。nx/jestNx 对 Jest 的插件与预设nx/jest/preset。环境相关依赖DOM 测试React、Vue、浏览器类库需要jest-environment-jsdom因为 Nx 预设默认将环境设为jsdom。Node 测试API、CLI无需额外依赖——Jest 默认环境是node但要注意Nx 预设默认是jsdom纯 Node 项目若沿用 Nx 预设会跑在 jsdom 环境下需要按需覆盖。React 测试pnpm add -wD testing-library/react testing-library/jest-domReact Babel非 ts-jest 转换部分 React 项目常见于较老的 Nx 工作区与 CRA 迁移项目不使用 ts-jest而是在项目jest.config的transform字段中配置babel-jest来处理 JSX 转换pnpm add -wD babel-jest babel/core babel/preset-env babel/preset-react babel/preset-typescript判断时机检查项目jest.config的transform使用的是babel-jest还是ts-jest。若为前者按上述命令补齐 Babel 全家桶这也是文档Tests fail with Cannot use import statement outside a module报错的一大来源——转换器缺失或未正确配置。Vue 测试pnpm add -wD vue/test-utils需要注意Vue 项目通常使用 Vitest 而非 Jest详见 VITE.md导入 Vue 项目时优先确认其测试框架选择。四、tsconfig.spec.json测试代码的类型合规Jest 项目需要独立的tsconfig.spec.json将测试文件纳入 TypeScript 检查范围。标准模板{ extends: ./tsconfig.json, compilerOptions: { outDir: ../../dist/out-tsc, module: commonjs, types: [jest, node] }, include: [ jest.config.ts, src/**/*.test.ts, src/**/*.spec.ts, src/**/*.d.ts ] }导入后最常见的三类问题缺少types: [jest, node]——会导致describe、it、expect在编辑器与类型检查中无法识别报 Cannot find type definition file for jest。缺少module: commonjs——Jest 默认不支持 ESMts-jest 会把代码转译成 CJSmodule不设为commonjs会导致运行期模块格式不匹配。include数组缺失测试文件模式——TypeScript 将不会检查测试文件类型错误被静默放过。五、Jest 与 Vitest 共存同一工作区两种测试框架大型工作区完全可以同时存在 Jest 与 VitestJestNext.js 应用、较老的 React 库、Node 库。Vitest基于 Vite 的 React/Vue 应用与库。nx/jest/plugin与nx/vite/plugin后者推断 Vitest 目标能够无冲突共存因为它们检测的是不同的配置文件jest.config.*与vite.config.*互不干扰。目标命名冲突两者默认都把目标命名为test。如果某个项目同时存在两类配置文件必须为其中一个改名例如{ plugin: nx/jest/plugin, options: { targetName: jest-test } }当前仓库的佐证tsParticles 本身就是一个典型的 Vitest 阵营示例——根 nx.json 的plugins数组中只有nx/plugins/package-json与tsparticles/cli-nx-plugin并无nx/jest/plugin全仓库也找不到任何jest.config.*文件而 utils/tests/vitest.config.ts 明确使用vitest/config的defineConfig并配置了environment: jsdom、coverage.provider: v8与include: [src/tests/*.ts]。这正是插件按配置文件区分框架机制的直观体现——同一工作区中Vitest 项目看vite.config.*Jest 项目看jest.config.*。六、testing-library/jest-dom的 Jest / Vitest 差异从 Jest 迁移到 Vitest或两者并存的工作区jest-dom的导入路径不同Jesttest-setup.ts中import testing-library/jest-dom;Vitesttest-setup.ts中import testing-library/jest-dom/vitest;如果源项目用的是 Jest而目标工作区对该类项目使用 Vitest必须更新导入路径。同时记得把testing-library/jest-dom加入 tsconfig 的types数组确保其匹配器matcher类型对测试文件可见。七、非 Nx 源码导入测试脚本的自动重写陷阱当导入的是没有nx.json的普通 pnpm/npm 工作区时Nx 在初始化阶段会自动重写package.json脚本测试脚本往往被改坏test: jest→test: nx test——若项目没有配置 executor会形成循环调用。test: vitest run→test: nx test run——run变成了一个参数命令直接损坏。修复方式删除所有被重写过的测试脚本。nx/jest/plugin与nx/vite/plugin会从配置文件推断出测试目标package.json里的test脚本反而是冗余且有害的。以当前仓库为参照utils/tests/package.json 中的测试入口是test: vitest run、test:ci: NODE_ENVtest vitest run --maxConcurrency2保持了脚本直呼工具的形态由工作区插件统一推断任务边界——这是 Nx 管理下脚本的推荐形态。八、CI 原子化按文件拆分的并行测试nx/jest/plugin支持把测试按文件拆分供 CI 并行分发使用{ plugin: nx/jest/plugin, options: { targetName: test, ciTargetName: test-ci } }启用后插件会为每个测试文件生成形如test-ci--src/lib/foo.spec.ts的独立目标从而支持 Nx Cloud 的任务分发。该能力在导入阶段不需要但在导入后的 CI 配置阶段非常有用。如果 CI 需要控制并发度可参考仓库中 utils/tests/package.json 的做法用--maxConcurrency之类的参数约束并行上限。九、导入后的常见问题速查表Cannot find target testnx/jest/plugin未在nx.json中注册。运行npx nx add nx/jest或手动补上插件配置。Cannot find module jest-preset工作区根目录缺少jest.preset.js。手动创建内容见第二节。Cannot find type definition file for jest缺少types/jest或tsconfig.spec.json未配置types: [jest, node]。Cannot use import statement outside a modulets-jest未安装或未配置为 transform。检查项目jest.config.ts的transform字段。Snapshot 路径不匹配导入后__snapshots__目录可能内嵌了旧路径。跑一次--updateSnapshot重新生成即可。十、修复顺序两条标准执行路径场景 A子目录导入Nx 源码monorepo 源npx nx add nx/jest——注册插件到nx.json不会创建jest.preset.js。手动创建jest.preset.js内容见第二节。安装核心依赖pnpm add -wD jest jest-environment-jsdom ts-jest types/jest。按框架补测试依赖React 项目装testing-library/react testing-library/jest-domVue 项目装vue/test-utilsBabel 转换的项目再补 Babel 依赖。核对tsconfig.spec.json包含types: [jest, node]。全量验证nx run-many -t test。场景 B整仓库导入非 Nx 源码单项目仓库从package.json删除被 Nx 重写的测试脚本见第七节。npx nx add nx/jest——注册插件同样不会创建 preset。手动创建jest.preset.js。安装依赖与场景 A 相同。核对/修复jest.config.*——确保preset路径指向根jest.preset.js。核对/修复tsconfig.spec.json——按需补types、module、include。全量验证nx run-many -t test。总结Jest 在 Nx 工作区中的落地本质上是插件注册、preset 就位、依赖补齐、类型合规四件事的组合nx/jest/plugin负责从jest.config.*推断test目标jest.preset.js提供跨项目共享配置框架相关的测试依赖矩阵决定了运行环境与断言能力tsconfig.spec.json保证测试代码通过类型检查。掌握这两条修复顺序与五类高频报错无论是子目录导入还是整仓库导入都能让 Jest 测试在 Nx 工作区中稳定运行。若项目实际走 Vitest 路线可继续参考 VITE.md 中的 Vite/Vitest 专项指引。【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
