在 Nx 仓库中为 Next.js 项目启用 Cypress 组件测试cypress-component-configuration 生成器完整指南【免费下载链接】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/nxCypress 组件测试Component Testing允许你在真实的浏览器环境中挂载并交互式测试单个 React/Next.js 组件而无需启动完整的 Next.js 服务器。在 Nx 仓库中nx/next提供的cypress-component-configuration生成器只需一条命令即可为指定 Next.js 项目生成一整套预配置好的组件测试基础设施——包括cypress.config.ts、Cypress 支持文件以及可直接运行的component-test目标。读完本文你将掌握该生成器的全部用法含--generate-tests自动测试生成、生成产物的每一项配置含义并能通过阅读nx/next/plugins/component-testing的源码理解nxComponentTestingPreset底层是如何基于 Nx Webpack 预设与 React 插件组装出 Cypress 组件测试环境的。前置条件与版本要求在开始之前请注意 Nx 对 Cypress 组件测试的支持有以下约束注意在 Next.js 项目中使用 Nx 的 Cypress 组件测试要求Cypress 版本不低于 10.7.0。如果你的工作区还在使用旧版本可以通过 migrate-to-cypress-11 生成器 迁移到 Cypress v11 及以上该生成器位于packages/cypress包中可直接用于升级项目内 Cypress 版本。另外需要区分两条技术路线本文介绍的cypress-component-configuration生成器面向的是Cypress 原生的组件测试基于其componenttesting type如果你希望通过Storybook Cypress的方式测试组件则应参考 React 的storybook-configuration生成器。但需要注意该功能已废弃并将在Nx 19版本中被移除新项目建议直接采用本文的 Cypress 原生组件测试方案。一键生成配置生成器命令与产出文件在 Nx 工作区中执行以下命令即可为指定 Next.js 项目生成 Cypress 组件测试配置nx g nx/next:cypress-component-configuration --projectmy-cool-next-project其中project是必选参数指向你要配置组件测试的 Next.js 应用或库项目。生成器执行完毕后会向该项目写入一系列预配置好的文件。从 生成器实现 可以看到它实际上做了四件事委托给nx/cypress的基础组件测试生成器以framework: next、jsx: true的方式初始化 Cypress 组件测试骨架初始化 Webpack 支持调用nx/webpack的webpackInitGenerator并通过ensureDependencies以compiler: swc、uiFramework: react补齐依赖这也是该生成器要求工作区安装nx/webpack的原因生成项目内的 Cypress 支持文件cypress/support/component.ts注册mount命令与cypress/support/styles.ct.css全局样式入口改写cypress.config.ts引入nx/next/plugins/component-testing的nxComponentTestingPreset预设并在component-test目标上追加skipServe: true。命令执行后生成的核心文件是预配置好的cypress.config.ts其默认内容如下import { defineConfig } from cypress; import { nxComponentTestingPreset } from nx/next/plugins/component-testing; export default defineConfig({ component: nxComponentTestingPreset(__filename), });nxComponentTestingPreset(__filename)会根据传入的配置文件路径自动推导所属项目并组装出针对该项目定制项目根目录、tsconfig、资源、输出目录等均来自项目配置的组件测试预设。除了上面这条命令生成器还提供了别名形式的命令nx g nx/next:cypress-component-project --projectmy-cool-next-project两者等价均指向同一个生成器。自定义 Cypress 配置选项nxComponentTestingPreset返回的是一份完整的component配置对象因此你可以通过对象展开spread的方式合并自定义选项覆盖或补充默认行为import { defineConfig } from cypress; import { nxComponentTestingPreset } from nx/next/plugins/component-testing; export default defineConfig({ component: { ...nxComponentTestingPreset(__filename), // extra options here }, });例如你可以在展开后的对象上追加specPattern、viewportWidth、supportFile或env等任意 Cypress 配置项。注意自定义属性需写在展开之后才能覆盖预设中的同名默认值。此外nxComponentTestingPreset本身也接受第二参数options。从 插件源码 中可以确认其支持以下选项选项类型默认值作用ctTargetNamestringcomponent-test指定项目中的组件测试目标名用于在项目图中定位目标及读取其devServerTargetbuildTargetstring读取component-test目标的devServerTarget指定用于构建测试环境的前置构建目标必须是nx/next:buildexecutorcompilerstringswc传给 Webpack 预设的编译工具当前默认使用 SWC自动生成组件测试--generate-tests生成器支持可选的--generate-tests标志为项目中的每个组件自动生成对应的测试文件nx g nx/next:cypress-component-configuration --projectmy-cool-next-project --generate-tests从 生成器源码 可以看到自动生成的筛选逻辑理解它有助于你预估生成结果生成器会遍历项目的sourceRoot借助isComponent判断文件是否为组件自动跳过路径中包含pages、server、app的文件——即 Next.js 的 Pages Router 页面、Server 组件与 App Router 目录下的文件不会被生成测试这与 Next.js 的服务端渲染语义有关此类文件不适合以客户端组件方式挂载测试对筛选出的每个组件调用nx/react的componentTestGenerator生成对应的*.cy.tsx测试文件。同时生成器还会在项目tsconfig.json的exclude中追加cypress/**/*、cypress.config.ts以及**/*.cy.{ts,js,tsx,jsx}等模式并在tsconfig.json的references中关联./cypress/tsconfig.json针对库项目确保类型检查时正确隔离 Cypress 测试代码——这些行为都有对应的 单元测试用例 逐一断言。运行组件测试生成器会在项目上新增一个名为component-test的目标用于运行组件测试nx g component-test my-cool-next-project即运行my-cool-next-project项目的component-test目标等价写法为nx run my-cool-next-project:component-test。执行后会启动 Cypress按componenttesting type 收集并运行项目内所有*.cy.{js,jsx,ts,tsx}测试。生成的项目配置project.json示例如下{ targets: { component-test: { executor: nx/cypress:cypress, options: { cypressConfig: path-to-project-root/cypress.config.ts, testingType: component, skipServe: true } } } }关键字段说明executor: nx/cypress:cypress复用nx/cypress的 Cypress executor 来驱动组件测试testingType: component告诉 Cypress 以组件测试模式运行而非 e2eskipServe: true组件测试不依赖 dev server 预启动——测试所需的编译与挂载完全由nxComponentTestingPreset内置的 Webpack dev server 承担。这一点也在生成器中通过projectConfig.targets[component-test].options { ..., skipServe: true }显式强制写入。源码级原理nxComponentTestingPreset 内部实现要真正用好这份配置有必要了解nx/next/plugins/component-testing中nxComponentTestingPreset做了什么。其完整实现位于 packages/next/plugins/component-testing.ts核心流程如下项目图定位通过readCachedProjectGraph()读取 Nx 项目图再用getProjectConfigByPath(graph, pathToConfig)根据cypress.config.ts的位置解析出所属项目及其目标默认目标名为component-test构建目标解析若未显式传入buildTarget则从component-test目标的执行选项里读取devServerTarget并对构建目标做强校验——该目标必须使用nx/next:buildexecutor否则直接抛出错误提示组件测试必须搭配nx/next:buildthrow new Error( The ${parsedBuildTarget.target} target of the ${project} project is not using the nx/next:build executor. ... );构建产物透传从构建目标的执行选项中继承assets、fileReplacements输出目录默认取dist/${projectName}/.nextWebpack 配置组装使用nx/webpack的composePluginsSync组合withNx({ target: web, postcssConfig: projectRoot, ... })与withReact({})两个插件并以项目根目录下的tsconfig.json、默认 SWC 编译器compiler: options?.compiler || swc构建 Webpack 配置——这正是 Next.js 组件测试能在不启动 Next dev server 的情况下完成 JSX/TSX 编译挂载的底层机制返回合并后的预设在nxBaseCypressPreset来自nx/cypress位于 packages/cypress/plugins/cypress-preset.ts负责输出目录、截图/视频目录、chromeWebSecurity: false等基础项之上覆盖specPattern: **/*.cy.{js,jsx,ts,tsx}并注入devServer: { framework: react, bundler: webpack, webpackConfig }。生成器 Schema 参数一览生成器的完整参数定义见 schema.json参数类型必填默认值说明projectstring✅—要配置 Cypress 组件测试的项目名下拉选择generateTestsboolean❌false是否为项目中已有组件自动生成默认测试文件skipFormatboolean❌false是否跳过生成后的文件格式化内部参数生成的支持文件与常见注意点除了cypress.config.ts生成器还会写入以下支持文件理解它们能帮你排查大多数组件测试跑不起来的问题cypress/support/component.ts组件测试的全局支持文件。生成器会在这里导入并注册mount命令Cypress.Commands.add(mount, mount)同时引入./styles.ct.css。需要注意mount的导入源与 Cypress 大版本相关见 生成器源码 与 测试快照Cypress14 及以上import { mount } from cypress/reactCypress14 以下import { mount } from cypress/react18。cypress/support/styles.ct.css全局样式入口可在此加载应用于所有组件的全局样式。如果项目根目录存在tailwind.config.js或tailwind.config.cjs生成器会自动写入 Tailwind 的三条指令让组件测试环境同样具备 Tailwind 样式能力tailwind base; tailwind components; tailwind utilities;Cypress 14 的justInTimeCompile注意事项从生成器测试的配置快照可以看到对于 Cypress 14生成器默认会在cypress.config.ts中显式写入justInTimeCompile: false。这是因为 Cypress 14 在 Webpack 下默认将justInTimeCompile置为true可能在 CI 中间歇性地只运行 0 个测试如果你确认自己的环境不会触发该问题可以删除这一行以重新开启 JIT 编译。更多参考Angular 项目同样支持基于 Cypress 的组件测试配置参见 Angular 的 cypress-component-configuration 文档React非 Next项目的组件测试配置参考 React 的 cypress-component-configuration 文档需要了解预设与基础配置更底层的行为可阅读 packages/cypress/plugins/cypress-preset.ts 与 packages/next/plugins/component-testing.ts生成器的行为契约与各种边界情况库项目、低版本 Cypress、测试排除规则均有 单元测试 覆盖可作为排查问题时的参考依据。【免费下载链接】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），仅供参考