next-runtime-env 单元测试完全指南如何用 Jest Testing Library 编写可靠的 env 测试【免费下载链接】next-runtime-envNext.js Runtime Environment Configuration - Populates your environment at runtime rather than build time.项目地址: https://gitcode.com/gh_mirrors/ne/next-runtime-envnext-runtime-env是一个 Next.js 运行时环境变量配置工具它把环境变量注入时机从构建时推迟到运行时让构建一次、部署多处成为现实。本文是一份面向新手的单元测试完全指南带你用 Jest Testing Library 为这类 env 工具编写可靠的测试覆盖配置、mock、覆盖率全流程。 为什么 next-runtime-env 需要单元测试运行时注入环境变量涉及服务端、浏览器、middleware三种运行环境还涉及白名单过滤NEXT_PUBLIC_前缀等安全边界。任何一处回归都可能导致敏感变量意外暴露到浏览器构建产物在不同环境表现不一致项目源码中已内置一整套.spec.ts/.spec.tsx测试文件是绝佳的教学样本纯函数测试src/helpers/get-public-env.spec.ts、src/script/env.spec.ts组件测试src/provider/env-provider.spec.tsx、src/script/env-script.spec.tsx日志行为测试src/helpers/log.spec.ts 测试环境快速搭建Jest ts-jest jsdom一键安装步骤克隆仓库并安装依赖即可git clone https://link.gitcode.com/i/12639d426d8f72dc6d5ddfa051b0e461 cd next-runtime-env pnpm install测试相关依赖在 package.json 的devDependencies中核心就三件套依赖作用jestts-jest让 Jest 直接运行 TypeScriptjest-environment-jsdom模拟浏览器 DOM 环境testing-library/reacttesting-library/jest-dom渲染 React 组件并断言 DOM最快配置方法读懂 jest.config.js整个配置文件极简就 5 个关键点见jest.config.jsmodule.exports { preset: ts-jest, // 直接支持 TS testEnvironment: jsdom, // 模拟浏览器 testPathIgnorePatterns: [...], // 忽略 examples 目录 collectCoverageFrom: [src/**/*.{ts,tsx}], coveragePathIgnorePatterns: [...], // 覆盖率排除 src/lib }; 新手要点testEnvironment: jsdom是测试 React 组件和window.__ENV的前提而examples/被排除是因为它是完整的示例应用不属于库本身的测试范围。 核心模块测试拆解1. 纯函数测试白名单过滤 getPublicEnvgetPublicEnv()只返回带NEXT_PUBLIC_前缀的变量。src/helpers/get-public-env.spec.ts用 5 个用例完整覆盖了正反场景✅ 返回单个 / 多个白名单变量❌ 返回空对象非白名单变量 混合列表只放行白名单项每个用例在afterEach中delete process.env.FOO清理状态保证用例互不污染——这是 env 测试的第一原则。2. 双端测试env() 的服务端与浏览器分支src/script/env.spec.ts是双端测试的最佳范本用Object.defineProperty伪造window.__ENV// 模拟浏览器中由 EnvScript 注入的变量 Object.defineProperty(global, window, { value: { __ENV: { NEXT_PUBLIC_FOO: foo } }, writable: true, }); expect(env(NEXT_PUBLIC_FOO)).toEqual(foo);它还覆盖了最关键的安全场景浏览器访问非公开变量时应抛错而不是静默返回undefined。expect(() env(BAM_BAM)).toThrow( Environment variable BAM_BAM is not public... ); 技巧afterEach中把global.window置回undefined让用例在纯 Node和浏览器之间自由切换。3. React 组件测试Provider 与 Script组件测试统一采用 Testing Library 的render 查询断言见src/provider/env-provider.spec.tsxconst { getByText } render( EnvProvider env{env} SomeClientComponent / /EnvProvider, ); expect(getByText(/^NODE_ENV:/).textContent).toBe(NODE_ENV: test);测试矩阵一览测试文件验证目标env-provider.spec.tsx子组件能通过useEnvContext拿到 envpublic-env-provider.spec.tsx私有变量不透出安全边界use-env-context.spec.tsx脱离 Provider 使用时必须抛错env-script.spec.tsx/public-env-script.spec.tsxscript标签正确写入window[__ENV]、nonce 透传值得注意的细节Mock 第三方组件env-script.spec.tsx用jest.mock(next/script, ...)把 Next 的 Script 组件替换成原生script让断言更直接。保存/还原 process.envbeforeAll中processEnv process.envafterAll中还原避免污染全局。标记未完成用例it.todo(...)优雅地保留待办nonce 从 headers 读取的场景。4. 依赖打桩日志测试的 spy 与 mock 两种姿势src/helpers/log.spec.ts使用jest.spyOn(console, log)监听控制台调用beforeAll清空实现、afterAll用mockRestore()还原。src/utils/make-env-public.spec.ts则直接jest.mock(../helpers/log)整体替换日志模块断言warnMock收到变量不存在已公开等提示。选择原则只关心是否被调用用 spy关心模块行为用 mock。⚡ 常用测试技巧速查技巧用途参考文件afterEach清理process.env防止用例互相污染get-public-env.spec.tsObject.defineProperty(global, window, ...)伪造浏览器全局对象env.spec.tsjest.spyOn(console, ...)验证日志输出log.spec.tsjest.mock(next/script)简化第三方依赖env-script.spec.tsxit.todo()登记未完成用例env-script.spec.tsxjest.clearAllMocks()重置 mock 调用记录make-env-public.spec.ts 运行测试与查看覆盖率pnpm test # 运行全部测试 pnpm test:coverage # 带覆盖率报告 pnpm test:watch # 50% 并发 监听模式覆盖率统计范围为src/**/*.{ts,tsx}并排除了src/lib仅含颜色库封装让报告聚焦于真正的业务逻辑。❓ 常见问题FAQQ1为什么用 jsdom 而不是 node 环境因为env()、EnvScript等 API 需要读取window.__ENVjsdom 提供了最小可用的浏览器环境。Q2测试中如何模拟变量未注入直接不设置process.env对应键并断言返回undefined或抛出明确错误参考src/script/env.spec.ts的两个undefined用例。Q3examples 目录为什么没有测试它是可运行的示例应用App Router / Pages Router 各一份由testPathIgnorePatterns排除避免与库测试混淆。小结为next-runtime-env这类运行时 env 工具写测试抓住三点即可——状态隔离每个用例清理process.env、双端覆盖Node 与 jsdom 都要跑、安全边界私有变量绝不透出。照着src/下的 spec 文件抄作业你就能快速为自己的 Next.js 项目建立可靠的 env 测试体系。【免费下载链接】next-runtime-envNext.js Runtime Environment Configuration - Populates your environment at runtime rather than build time.项目地址: https://gitcode.com/gh_mirrors/ne/next-runtime-env创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考