2026/9/14 4:04:47
FEATURED · 精选文章 
Vitest 仓库贡献者与 AI Agent 开发指南从环境搭建、测试编写到 CI 规范【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest这篇指南面向希望在 Vitest 仓库GitHub_Trending/vi/vitest 根目录的 pnpm monorepo中贡献代码的开发者与 AI Agent系统讲解从零搭建开发环境、编写高质量测试、遵守代码规范到理解 CI 生成文件约束的完整工作流。读完本文你将掌握 Vitest 仓库的开发命令、测试工具链runVitest/runInlineTests、包重建策略、依赖管理约定以及提交信息规范可以直接上手提交第一个经过验证的 PR。本文内容以仓库根目录 AGENTS.md 为骨架结合 CONTRIBUTING.md、docs/AGENTS.md、package.json、pnpm-workspace.yaml、eslint.config.js 及测试工具源码展开所有命令与配置均可在当前仓库中验证。仓库概览基于 pnpm workspaces 的 TypeScript monorepoVitest 是一个由 Vite 驱动的下一代测试框架package.json 中描述为 Next generation testing framework powered by Vite。仓库本身是一个使用 pnpm workspaces 组织的 monorepo核心特征如下语言TypeScript/JavaScript采用 ESM-first 策略包管理器pnpm强制要求见 CONTRIBUTING.md The package manager used to install and link dependencies must be pnpm构建系统Vite RollupMonorepo 结构所有核心包位于packages/目录测试按功能分散在test/目录下。pnpm-workspace.yaml明确列出了工作区成员docs、packages/*、examples/*、test/*等目录都被纳入同一个 workspace这意味着对vitest/*任意包的修改都能被其他包通过 workspace 链接即时感知。核心包职责一览AGENTS.md 将packages/下的核心包职责归纳如下理解这份地图是定位修改点的第一步包职责vitest主测试框架包含测试运行器核心除vitest/mocker外仓库内被引用的包都会被打包inline进它的 bundlebrowser浏览器模式测试支持browser-playwright/browser-preview浏览器模式的两种 providerui测试结果 Web UIexpect断言库spyMock 与 spy 工具snapshot快照测试coverage-v8/coverage-istanbul代码覆盖率utils共享工具mocker模块 Mockpretty-format值序列化web-workerNode.js 下的 Web Worker 模拟测试组织方面test/unit是核心功能测试test/e2e通过runVitest/runInlineTests运行端到端测试test/browser是浏览器专项测试test/node-runner则要求测试进程内完全无法访问 Vitest API用node --test运行。开发环境搭建与常用脚本初始设置三步走# 1. 安装依赖 pnpm install # 2. 构建所有包 pnpm build # 3. 涉及浏览器特性时安装 Playwright 浏览器 npx playwright install --with-deps值得注意仓库根 package.json 声明了 Node 版本要求^22.12.0 || ^24.0.0 || 26.0.0packageManager锁定为pnpm11.24.0。搭建环境前建议先确认本地 Node 与 pnpm 版本符合要求AGENTS.md 的 Troubleshooting 也提示了这一点。关键脚本速查脚本作用pnpm build构建所有包pnpm -r --filter vitest/ui --filter./packages/** run buildpnpm dev监听模式开发持续重建包需NODE_OPTIONS--max-old-space-size8192pnpm lint运行 ESLinteslint --cache .pnpm lint:fix自动修复 lint 问题pnpm typecheck运行 TypeScript 类型检查tsc -p tsconfig.check.json --noEmitpnpm docs启动文档站开发服务器pnpm -C docs run devpnpm docs:build构建文档站会先重新生成 CLI 表格运行测试命令、陷阱与正确姿势测试命令矩阵全部测试CItrue pnpm test:ci对应 package.json 中的test:ci会依次运行vitest/test-*下除test-browser外的所有测试包示例测试CItrue pnpm test:examples指定测试套件CItrue cd test/test-folder pnpm test test-file单元目录测试CItrue pnpm test test-file针对test/unit浏览器测试CItrue pnpm test:browser:playwright即pnpm -C test/browser run test:playwright。重要陷阱不要给 pnpm 传--AGENTS.md 特别强调了一个极易踩坑的细节向 pnpm 传测试过滤器时不要使用--。--会让 pnpm 丢弃过滤器导致过滤器失效、变成全量测试运行# 错误 —— 会运行所有测试过滤器被忽略 pnpm test -- basic.test.ts -t expect # 正确 —— 只运行匹配的测试 pnpm test basic.test.ts -t expect断言风格约定写测试时避免使用toContain做校验优先使用toMatchInlineSnapshot把测试错误及其堆栈一并纳入快照。如果快照失败应更新快照而不是改回toContain——这样做的目的是让失败信息更完整、回归可追溯。测试工具链runVitest 与 runInlineTestsAGENTS.md 指明复杂文件系统场景1 个文件必须使用runInlineTests普通场景可以使用runVitest以编程方式运行 Vitest。这两个工具都定义在 test/test-utils/index.ts是 e2e 测试的核心基础设施。runVitest 的行为约定runVitest(config)的第一个参数被当作磁盘上的配置文件处理因此 fixture 自带的配置文件优先级更高。源码注释test/test-utils/index.ts明确警告如果root中的 fixture 有配置文件其选项会覆盖这里传入的配置只有$cliOptions中的选项例外。传递 CLI-only 选项或覆盖配置的方式通过$cliOptions传 CLI 选项通过$viteConfig传 Vite 配置属性传config: false跳过配置文件发现。除非显式覆盖runVitest会强制设置watch: false、maxWorkers: 1、reporters: [verbose]传reporters: none可恢复 Vitest 真实默认值、cache: false并注入NO_COLOR环境变量见 test/test-utils/index.ts。返回的对象不会抛异常并会自动关闭启动的 Vitest 实例断言方式为expect(stderr).toBe()配合expect(testTree()).toMatchInlineSnapshot(...)失败场景用errorTree()输出已被剥离 ANSI 颜色、路径被规范化为root/。启动错误需要检查返回的thrown与stderr。runInlineTests 的临时文件系统runInlineTests会在 cwd 下创建vitest-test-uuid目录写入测试文件当目录结构中没有.config.文件时会自动补一个空的vitest.config.js测试结束后删除该目录设置VITEST_FS_CLEANUPfalse可保留目录用于调试。需要留意配置对象会用JSON.stringify序列化函数和正则会被静默丢弃这类配置应以整文件字符串的形式书写。runVitestCli 与真实 CLIrunVitestCli会启动真实的 CLI 二进制同样走dist产物并总是追加--maxWorkers1测试结束时杀掉子进程。交互方式是通过vitest.waitForStdout()和vitest.write()注意write()会清空已捕获的输出。可靠测试的纪律AGENTS.md 对测试可靠性有一组硬性要求全部可以在测试工具源码中找到对应实现绝不修改已提交的 fixture 文件e2e 测试并行运行需要可编辑目录的测试必须用runInlineTests确实需要 git 跟踪文件的测试如--changed必须加入 test/e2e/vitest.config.ts 的serialTests列表watch 模式只通过createFile/editFile修改文件它们会在测试后恢复内容和 mtime源码见 test/test-utils/index.ts防止下一个测试的 watcher 看到幻影变更restoreFile会连同 atime/mtime 一起恢复任何基于 stat 的比较都无法报告文件被修改在测试内而非 hook 中调用这些函数清理通过onTestFinished注册watch 场景要传显式的小rootrunVitest({ watch: true, root })会等待 watcher 就绪才 resolve对应源码中的waitForWatcherReady见 test/test-utils/index.tsESLint 的测试规则在本仓库被禁用eslint.config.js 中test: false因此漏网的.only不会被 lint 拦住需要自查并移除CI 在 Windows 上运行 unit、e2e、coverage 和 browser 套件并在 macOS 上运行一条 e2e 任务。Vitest 报告路径使用正斜杠比较import.meta.filename、process.execArgv等原始 OS 路径前要把\规范化为/package.json 脚本中绝不使用rm -rf、cp -r这类 Unix-only 命令改用 node 脚本或 rimraf。包重建策略测试跑的是 dist不是源码AGENTS.md 花费大量篇幅解释了一个新手最容易困惑的机制测试执行的是构建产物。测试套件通过 workspace 符号链接解析vitest而包导出指向dist/pnpm typecheck则解析 TypeScript 源码。所以 typecheck 通过绝不证明dist是最新的重跑测试前必须先重建。重建的精细化规则vitest和vitest/browser会通过__vitest_source__导出条件把其他vitest/*workspace 包从 TypeScript 源码内联进来packages/vitest/package.json 的imports字段和 packages/vitest/rollup.config.js 的exportConditions: [__vitest_source__]可佐证。因此修改vitest/utils、vitest/expect、vitest/snapshot、vitest/spy、vitest/pretty-format后只需pnpm --filter vitest build即可覆盖走 vitest bundle 的测试只有当测试直接 import 子包时例如test/unit从 dist 导入vitest/utils/*才需要单独重建该子包vitest/mocker是例外它是vitest的运行时依赖且永不内联见 packages/vitest/package.json 中vitest/mocker: workspace:*位于dependencies重建vitest不会带上 mocker 的改动必须执行pnpm --filter vitest/mocker buildpackages/vitest/src/runtime/下的 worker 端代码从构建后的dist/workers/*.js加载运行时改动同样需要重建vitestpnpm devwatch 模式只重建 JS.d.ts打包配置在 watch 模式下被跳过。修改公共类型后在对照dist/*.d.ts检查前需要跑一次完整构建。代码风格与 ESLint 硬性规则AGENTS.md 要求每次改动后运行pnpm lint:fix非自动修复的错误手动修复且在编辑器或 Agent 环境中应使用CItrue pnpm lint运行——因为配置在检测到编辑器环境时会禁用部分规则而这些规则在 CI 中仍会失败。以下规则lint:fix无法自动修复需要人工遵守禁止import ... from path这在所有文件中都是 ESLint 错误见 eslint.config.js 的no-restricted-imports。优先使用pathe仓库主流约定路径会规范化为 posixNode-only 代码允许node:pathpackages/*/src不得 importvitest或vitest/node即使仅类型导入也不行例外是声明了 vitest 为 peer dependency 的包coverage-*、ui、browser、browser-*、web-worker——eslint.config.js 的两个规则块正好对应这一约束console.log在包源码中是 ESLint 错误只允许console.warn和console.error删除调试日志有意的控制台输出需加显式的 eslint-disable 注释使用globalThis绝不用global或self仅docs/、packages/web-worker/、test/unit/例外packages/*/src禁止顶层awaittest/、scripts/和配置文件允许禁止const enum禁止export 在packages/browser中不要从未使用ivya的文件里 importivyaESLint 强制该依赖保持单一 rollup chunk见 eslint.config.js应复用既有入口点。TypeScript 严格模式与检查边界仓库采用严格 TypeScript 配置。根pnpm typecheck使用 tsconfig.check.json该文件明确排除了test/e2e、test/browser、test/typescript、docs、examples这些目录的类型错误不会从根命令暴露。根 typecheck 也不覆盖 UI client 的 Vue 代码修改packages/ui/client时还需运行pnpm -C packages/ui typecheck:client。tsconfig.base.json中值得注意的细节customConditions: [__vitest_source__]tsconfig.base.json让 TypeScript 与 rollup 的__vitest_source__导出条件保持一致源码路径映射paths把vitest/*各包直接指到src/目录这印证了typecheck 解析源码、测试解析 dist的双轨机制。代码注释政策避免为每次改动写注释代码表达力足够就不需要注释只有公共方法必须有注释导出的内部函数、属性、常量不应有注释命名应足够自解释只有当某行代码处理了上下文不明显的边界情况时才可以留注释如果为了解释逻辑需要在多个文件间拆散并写大段注释应重新考虑是否还有更简单的方案注释要简短、避免过于专业的行话禁止写仅为对比先前实现做辩护的注释。通用工作流与文档维护新增功能的标准流程在packages/中定位合适的包遵循既有代码模式使用测试工具添加测试运行pnpm build pnpm typecheck pnpm lint:fix在相关测试套件中补齐测试。调试使用 VS Code⇧⌘BShiftCmdB或CtrlShiftB启动开发任务也可参考scripts/目录中的专项开发工具。文档规范文档位于docs/VitePress 驱动动手前先读 docs/AGENTS.md改动 CLI 选项或其描述后文件在packages/vitest/src/node/cli/cli-config.ts必须运行pnpm -C docs run cli-table并提交重新生成的 docs/guide/cli-generated.md该文件绝不可手改。生成文件与 CI 检查过期产物会让 CI 挂掉CI 会构建全部内容然后执行git diff --exit-code因此过期的生成文件会导致 CI 失败。规则是提交重新生成的文件而不是回滚它们绝不手改。需要关注的生成文件包括文件生成方式packages/vitest/LICENSE.mdpnpm --filter vitest build在打包依赖变化时重写docs/guide/cli-generated.md从packages/vitest/src/node/cli/cli-config.ts生成pnpm-workspace.yamlpnpm install可能改动cleanupUnusedCatalogs、minimumReleaseAgeExcludedocs/.vitepress/contributor-names.json由pnpm docs:contributors生成其他会阻塞 CI 的任务Knippnpm knip会检测未使用的文件、导出和依赖失败即阻塞。应删除死代码而不是保留未用导出例外统一维护在 knip.jsonc.github/workflows/的改动受 actionlint 和 zizmor 门禁。uses:必须锁定到完整 commit SHAzizmor 误报用行内# zizmor: ignore[rule]加理由注释抑制——不要自动加注释改 workflow 文件前必须先跑 zizmor。依赖管理约定关键依赖AGENTS.md 列出的核心依赖Vite构建工具与 dev server、Rollup打包器、ESLintlint、TypeScript类型检查、Playwright浏览器测试、Chai/Expect断言、Tinybench基准测试。新增与升级依赖的规则packages/*的新运行时依赖通常放入devDependenciesRollup 只把dependencies视为 external其余全部打包。只有types/*包、无法打包的依赖二进制、或类型出现在 Vitest 公共类型中的依赖才用dependencies详见 CONTRIBUTING.md 的 Notes on Dependencies用pnpm add pkg在目标包内添加依赖catalogMode: prefer会把catalog:写进 package.json并自动把版本加入 pnpm-workspace.yaml 的默认 catalog。升级共享依赖时改 catalog 条目不要改各包的版本范围pnpm-workspace.yaml 的overrides在整个 workspace 强制vite、rollup、types/node、acorn、mlly各只有一个版本改单个 package.json 的 range 只会影响发布内容不影响本地安装仓库针对最新的受支持 Vite 主版本开发但vitest支持完整的 peer 范围packages/vitest/package.json 中vite: ^6.4.0 || ^7.0.0 || ^8.0.0CI 有专门针对上一主版本的 job本地用pnpm override-vite7复现不要依赖只有最新 Vite 才有的 API 而不留 fallbackpatchedDependencies中列出的依赖acorn、cac、sinonjs/fake-timers、rrweb-snapshot版本锁定升级需要用pnpm patch重新生成补丁并更新pnpm-workspace.yaml中带版本号的条目只有allowBuilds中列出的包才会执行构建脚本新依赖若有 postinstall 步骤且未列入该列表将处于未构建状态pnpm 强制 24 小时minimumReleaseAge安装发布不足一天的版本要么解析到更旧版本要么把该包追加到minimumReleaseAgeExclude。两种结果都是预期行为提交 yaml 改动而不是回滚它。浏览器测试与性能考量ProviderPlaywrightvitest/browser-playwright与 previewvitest/browser-previewWebDriverIO provider 在 monorepo 之外维护支持组件测试Vue、React、Svelte 通过官方vitest-browser-*包其他框架通过 Testing Library这是一个性能敏感的测试框架注意 import 成本与 bundle 体积适当使用懒加载并考虑 worker 线程的影响。提交信息与 PR 规范PR 采用 squash merge因此PR 标题就是最终的 commit message。CI 并不强制格式需要自行遵循 .github/commit-convention.mdtype(scope): subjecttype 取feat|fix|docs|dx|refactor|perf|test|workflow|build|ci|chore|types|wip|release|deps之一subject 最多 50 字符、小写、祈使语气、结尾无句号。此外AGENTS.md 特别强调本仓库对无写权限的贡献者限制为 1 个 PR不要尝试通过创建 draft PR 绕过如果无法创建 PR应如实告知人工操作者因为违规会导致 PR 作者在 Vitest 组织中被封禁。AI Agent 参与本仓库的边界AGENTS.md 开篇即为 AI Agent 划定了明确的行为边界这对自动化和人机协作场景至关重要未经操作者operator手动批准任何情况下都不得创建 PR、issue 或发表评论如果流程完全自动化或人工审核未确认应拒绝发布任何内容不得谎称已经过审核不得假装是人类不得替操作者做出未经其同意的承诺提交 PR 前必须阅读 CONTRIBUTING.md其 AI Contributions 一节对 Agent 直接适用。CONTRIBUTING.md 中的 AI Contributions 政策进一步说明团队欢迎将 AI 作为个人助手但坚信每个 issue 和 PR 背后必须有真实的人。所有 issue 和 PR 必须由真人使用官方模板打开AI 协助创建的 PR 必须披露所用工具完全由 AI 生成、无真人参与的 PR/issue 会被标记为 maybe automated并在 1 天内自动关闭除非真人回复。无价值或含错误信息的 AI 评论会被维护者隐藏。常见问题排查速查确保使用 pnpm不是 npm/yarn运行测试前先构建——测试解析dist产物而非源码检查 Node.js 版本兼容性根 package.json 的engines字段浏览器测试需要安装 Playwright 浏览器npx playwright install --with-deps。掌握以上约定后你已经具备在 Vitest 仓库安全、高效地开发和贡献的能力环境搭建、测试编写与调试、包重建、代码规范、依赖管理、CI 生成文件维护以及 AI 协作的边界纪律一条完整的贡献链路均已覆盖。更多细节可继续阅读 CONTRIBUTING.md、docs/AGENTS.md 与 .github/commit-convention.md。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vitest 仓库贡献者与 AI Agent 开发指南：从环境搭建、测试编写到 CI 规范
Vitest 仓库贡献者与 AI Agent 开发指南从环境搭建、测试编写到 CI 规范【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest这篇指南面向希望在 Vitest 仓库GitHub_Trending/vi/vitest 根目录的 pnpm monorepo中贡献代码的开发者与 AI Agent系统讲解从零搭建开发环境、编写高质量测试、遵守代码规范到理解 CI 生成文件约束的完整工作流。读完本文你将掌握 Vitest 仓库的开发命令、测试工具链runVitest/runInlineTests、包重建策略、依赖管理约定以及提交信息规范可以直接上手提交第一个经过验证的 PR。本文内容以仓库根目录 AGENTS.md 为骨架结合 CONTRIBUTING.md、docs/AGENTS.md、package.json、pnpm-workspace.yaml、eslint.config.js 及测试工具源码展开所有命令与配置均可在当前仓库中验证。仓库概览基于 pnpm workspaces 的 TypeScript monorepoVitest 是一个由 Vite 驱动的下一代测试框架package.json 中描述为 Next generation testing framework powered by Vite。仓库本身是一个使用 pnpm workspaces 组织的 monorepo核心特征如下语言TypeScript/JavaScript采用 ESM-first 策略包管理器pnpm强制要求见 CONTRIBUTING.md The package manager used to install and link dependencies must be pnpm构建系统Vite RollupMonorepo 结构所有核心包位于packages/目录测试按功能分散在test/目录下。pnpm-workspace.yaml明确列出了工作区成员docs、packages/*、examples/*、test/*等目录都被纳入同一个 workspace这意味着对vitest/*任意包的修改都能被其他包通过 workspace 链接即时感知。核心包职责一览AGENTS.md 将packages/下的核心包职责归纳如下理解这份地图是定位修改点的第一步包职责vitest主测试框架包含测试运行器核心除vitest/mocker外仓库内被引用的包都会被打包inline进它的 bundlebrowser浏览器模式测试支持browser-playwright/browser-preview浏览器模式的两种 providerui测试结果 Web UIexpect断言库spyMock 与 spy 工具snapshot快照测试coverage-v8/coverage-istanbul代码覆盖率utils共享工具mocker模块 Mockpretty-format值序列化web-workerNode.js 下的 Web Worker 模拟测试组织方面test/unit是核心功能测试test/e2e通过runVitest/runInlineTests运行端到端测试test/browser是浏览器专项测试test/node-runner则要求测试进程内完全无法访问 Vitest API用node --test运行。开发环境搭建与常用脚本初始设置三步走# 1. 安装依赖 pnpm install # 2. 构建所有包 pnpm build # 3. 涉及浏览器特性时安装 Playwright 浏览器 npx playwright install --with-deps值得注意仓库根 package.json 声明了 Node 版本要求^22.12.0 || ^24.0.0 || 26.0.0packageManager锁定为pnpm11.24.0。搭建环境前建议先确认本地 Node 与 pnpm 版本符合要求AGENTS.md 的 Troubleshooting 也提示了这一点。关键脚本速查脚本作用pnpm build构建所有包pnpm -r --filter vitest/ui --filter./packages/** run buildpnpm dev监听模式开发持续重建包需NODE_OPTIONS--max-old-space-size8192pnpm lint运行 ESLinteslint --cache .pnpm lint:fix自动修复 lint 问题pnpm typecheck运行 TypeScript 类型检查tsc -p tsconfig.check.json --noEmitpnpm docs启动文档站开发服务器pnpm -C docs run devpnpm docs:build构建文档站会先重新生成 CLI 表格运行测试命令、陷阱与正确姿势测试命令矩阵全部测试CItrue pnpm test:ci对应 package.json 中的test:ci会依次运行vitest/test-*下除test-browser外的所有测试包示例测试CItrue pnpm test:examples指定测试套件CItrue cd test/test-folder pnpm test test-file单元目录测试CItrue pnpm test test-file针对test/unit浏览器测试CItrue pnpm test:browser:playwright即pnpm -C test/browser run test:playwright。重要陷阱不要给 pnpm 传--AGENTS.md 特别强调了一个极易踩坑的细节向 pnpm 传测试过滤器时不要使用--。--会让 pnpm 丢弃过滤器导致过滤器失效、变成全量测试运行# 错误 —— 会运行所有测试过滤器被忽略 pnpm test -- basic.test.ts -t expect # 正确 —— 只运行匹配的测试 pnpm test basic.test.ts -t expect断言风格约定写测试时避免使用toContain做校验优先使用toMatchInlineSnapshot把测试错误及其堆栈一并纳入快照。如果快照失败应更新快照而不是改回toContain——这样做的目的是让失败信息更完整、回归可追溯。测试工具链runVitest 与 runInlineTestsAGENTS.md 指明复杂文件系统场景1 个文件必须使用runInlineTests普通场景可以使用runVitest以编程方式运行 Vitest。这两个工具都定义在 test/test-utils/index.ts是 e2e 测试的核心基础设施。runVitest 的行为约定runVitest(config)的第一个参数被当作磁盘上的配置文件处理因此 fixture 自带的配置文件优先级更高。源码注释test/test-utils/index.ts明确警告如果root中的 fixture 有配置文件其选项会覆盖这里传入的配置只有$cliOptions中的选项例外。传递 CLI-only 选项或覆盖配置的方式通过$cliOptions传 CLI 选项通过$viteConfig传 Vite 配置属性传config: false跳过配置文件发现。除非显式覆盖runVitest会强制设置watch: false、maxWorkers: 1、reporters: [verbose]传reporters: none可恢复 Vitest 真实默认值、cache: false并注入NO_COLOR环境变量见 test/test-utils/index.ts。返回的对象不会抛异常并会自动关闭启动的 Vitest 实例断言方式为expect(stderr).toBe()配合expect(testTree()).toMatchInlineSnapshot(...)失败场景用errorTree()输出已被剥离 ANSI 颜色、路径被规范化为root/。启动错误需要检查返回的thrown与stderr。runInlineTests 的临时文件系统runInlineTests会在 cwd 下创建vitest-test-uuid目录写入测试文件当目录结构中没有.config.文件时会自动补一个空的vitest.config.js测试结束后删除该目录设置VITEST_FS_CLEANUPfalse可保留目录用于调试。需要留意配置对象会用JSON.stringify序列化函数和正则会被静默丢弃这类配置应以整文件字符串的形式书写。runVitestCli 与真实 CLIrunVitestCli会启动真实的 CLI 二进制同样走dist产物并总是追加--maxWorkers1测试结束时杀掉子进程。交互方式是通过vitest.waitForStdout()和vitest.write()注意write()会清空已捕获的输出。可靠测试的纪律AGENTS.md 对测试可靠性有一组硬性要求全部可以在测试工具源码中找到对应实现绝不修改已提交的 fixture 文件e2e 测试并行运行需要可编辑目录的测试必须用runInlineTests确实需要 git 跟踪文件的测试如--changed必须加入 test/e2e/vitest.config.ts 的serialTests列表watch 模式只通过createFile/editFile修改文件它们会在测试后恢复内容和 mtime源码见 test/test-utils/index.ts防止下一个测试的 watcher 看到幻影变更restoreFile会连同 atime/mtime 一起恢复任何基于 stat 的比较都无法报告文件被修改在测试内而非 hook 中调用这些函数清理通过onTestFinished注册watch 场景要传显式的小rootrunVitest({ watch: true, root })会等待 watcher 就绪才 resolve对应源码中的waitForWatcherReady见 test/test-utils/index.tsESLint 的测试规则在本仓库被禁用eslint.config.js 中test: false因此漏网的.only不会被 lint 拦住需要自查并移除CI 在 Windows 上运行 unit、e2e、coverage 和 browser 套件并在 macOS 上运行一条 e2e 任务。Vitest 报告路径使用正斜杠比较import.meta.filename、process.execArgv等原始 OS 路径前要把\规范化为/package.json 脚本中绝不使用rm -rf、cp -r这类 Unix-only 命令改用 node 脚本或 rimraf。包重建策略测试跑的是 dist不是源码AGENTS.md 花费大量篇幅解释了一个新手最容易困惑的机制测试执行的是构建产物。测试套件通过 workspace 符号链接解析vitest而包导出指向dist/pnpm typecheck则解析 TypeScript 源码。所以 typecheck 通过绝不证明dist是最新的重跑测试前必须先重建。重建的精细化规则vitest和vitest/browser会通过__vitest_source__导出条件把其他vitest/*workspace 包从 TypeScript 源码内联进来packages/vitest/package.json 的imports字段和 packages/vitest/rollup.config.js 的exportConditions: [__vitest_source__]可佐证。因此修改vitest/utils、vitest/expect、vitest/snapshot、vitest/spy、vitest/pretty-format后只需pnpm --filter vitest build即可覆盖走 vitest bundle 的测试只有当测试直接 import 子包时例如test/unit从 dist 导入vitest/utils/*才需要单独重建该子包vitest/mocker是例外它是vitest的运行时依赖且永不内联见 packages/vitest/package.json 中vitest/mocker: workspace:*位于dependencies重建vitest不会带上 mocker 的改动必须执行pnpm --filter vitest/mocker buildpackages/vitest/src/runtime/下的 worker 端代码从构建后的dist/workers/*.js加载运行时改动同样需要重建vitestpnpm devwatch 模式只重建 JS.d.ts打包配置在 watch 模式下被跳过。修改公共类型后在对照dist/*.d.ts检查前需要跑一次完整构建。代码风格与 ESLint 硬性规则AGENTS.md 要求每次改动后运行pnpm lint:fix非自动修复的错误手动修复且在编辑器或 Agent 环境中应使用CItrue pnpm lint运行——因为配置在检测到编辑器环境时会禁用部分规则而这些规则在 CI 中仍会失败。以下规则lint:fix无法自动修复需要人工遵守禁止import ... from path这在所有文件中都是 ESLint 错误见 eslint.config.js 的no-restricted-imports。优先使用pathe仓库主流约定路径会规范化为 posixNode-only 代码允许node:pathpackages/*/src不得 importvitest或vitest/node即使仅类型导入也不行例外是声明了 vitest 为 peer dependency 的包coverage-*、ui、browser、browser-*、web-worker——eslint.config.js 的两个规则块正好对应这一约束console.log在包源码中是 ESLint 错误只允许console.warn和console.error删除调试日志有意的控制台输出需加显式的 eslint-disable 注释使用globalThis绝不用global或self仅docs/、packages/web-worker/、test/unit/例外packages/*/src禁止顶层awaittest/、scripts/和配置文件允许禁止const enum禁止export 在packages/browser中不要从未使用ivya的文件里 importivyaESLint 强制该依赖保持单一 rollup chunk见 eslint.config.js应复用既有入口点。TypeScript 严格模式与检查边界仓库采用严格 TypeScript 配置。根pnpm typecheck使用 tsconfig.check.json该文件明确排除了test/e2e、test/browser、test/typescript、docs、examples这些目录的类型错误不会从根命令暴露。根 typecheck 也不覆盖 UI client 的 Vue 代码修改packages/ui/client时还需运行pnpm -C packages/ui typecheck:client。tsconfig.base.json中值得注意的细节customConditions: [__vitest_source__]tsconfig.base.json让 TypeScript 与 rollup 的__vitest_source__导出条件保持一致源码路径映射paths把vitest/*各包直接指到src/目录这印证了typecheck 解析源码、测试解析 dist的双轨机制。代码注释政策避免为每次改动写注释代码表达力足够就不需要注释只有公共方法必须有注释导出的内部函数、属性、常量不应有注释命名应足够自解释只有当某行代码处理了上下文不明显的边界情况时才可以留注释如果为了解释逻辑需要在多个文件间拆散并写大段注释应重新考虑是否还有更简单的方案注释要简短、避免过于专业的行话禁止写仅为对比先前实现做辩护的注释。通用工作流与文档维护新增功能的标准流程在packages/中定位合适的包遵循既有代码模式使用测试工具添加测试运行pnpm build pnpm typecheck pnpm lint:fix在相关测试套件中补齐测试。调试使用 VS Code⇧⌘BShiftCmdB或CtrlShiftB启动开发任务也可参考scripts/目录中的专项开发工具。文档规范文档位于docs/VitePress 驱动动手前先读 docs/AGENTS.md改动 CLI 选项或其描述后文件在packages/vitest/src/node/cli/cli-config.ts必须运行pnpm -C docs run cli-table并提交重新生成的 docs/guide/cli-generated.md该文件绝不可手改。生成文件与 CI 检查过期产物会让 CI 挂掉CI 会构建全部内容然后执行git diff --exit-code因此过期的生成文件会导致 CI 失败。规则是提交重新生成的文件而不是回滚它们绝不手改。需要关注的生成文件包括文件生成方式packages/vitest/LICENSE.mdpnpm --filter vitest build在打包依赖变化时重写docs/guide/cli-generated.md从packages/vitest/src/node/cli/cli-config.ts生成pnpm-workspace.yamlpnpm install可能改动cleanupUnusedCatalogs、minimumReleaseAgeExcludedocs/.vitepress/contributor-names.json由pnpm docs:contributors生成其他会阻塞 CI 的任务Knippnpm knip会检测未使用的文件、导出和依赖失败即阻塞。应删除死代码而不是保留未用导出例外统一维护在 knip.jsonc.github/workflows/的改动受 actionlint 和 zizmor 门禁。uses:必须锁定到完整 commit SHAzizmor 误报用行内# zizmor: ignore[rule]加理由注释抑制——不要自动加注释改 workflow 文件前必须先跑 zizmor。依赖管理约定关键依赖AGENTS.md 列出的核心依赖Vite构建工具与 dev server、Rollup打包器、ESLintlint、TypeScript类型检查、Playwright浏览器测试、Chai/Expect断言、Tinybench基准测试。新增与升级依赖的规则packages/*的新运行时依赖通常放入devDependenciesRollup 只把dependencies视为 external其余全部打包。只有types/*包、无法打包的依赖二进制、或类型出现在 Vitest 公共类型中的依赖才用dependencies详见 CONTRIBUTING.md 的 Notes on Dependencies用pnpm add pkg在目标包内添加依赖catalogMode: prefer会把catalog:写进 package.json并自动把版本加入 pnpm-workspace.yaml 的默认 catalog。升级共享依赖时改 catalog 条目不要改各包的版本范围pnpm-workspace.yaml 的overrides在整个 workspace 强制vite、rollup、types/node、acorn、mlly各只有一个版本改单个 package.json 的 range 只会影响发布内容不影响本地安装仓库针对最新的受支持 Vite 主版本开发但vitest支持完整的 peer 范围packages/vitest/package.json 中vite: ^6.4.0 || ^7.0.0 || ^8.0.0CI 有专门针对上一主版本的 job本地用pnpm override-vite7复现不要依赖只有最新 Vite 才有的 API 而不留 fallbackpatchedDependencies中列出的依赖acorn、cac、sinonjs/fake-timers、rrweb-snapshot版本锁定升级需要用pnpm patch重新生成补丁并更新pnpm-workspace.yaml中带版本号的条目只有allowBuilds中列出的包才会执行构建脚本新依赖若有 postinstall 步骤且未列入该列表将处于未构建状态pnpm 强制 24 小时minimumReleaseAge安装发布不足一天的版本要么解析到更旧版本要么把该包追加到minimumReleaseAgeExclude。两种结果都是预期行为提交 yaml 改动而不是回滚它。浏览器测试与性能考量ProviderPlaywrightvitest/browser-playwright与 previewvitest/browser-previewWebDriverIO provider 在 monorepo 之外维护支持组件测试Vue、React、Svelte 通过官方vitest-browser-*包其他框架通过 Testing Library这是一个性能敏感的测试框架注意 import 成本与 bundle 体积适当使用懒加载并考虑 worker 线程的影响。提交信息与 PR 规范PR 采用 squash merge因此PR 标题就是最终的 commit message。CI 并不强制格式需要自行遵循 .github/commit-convention.mdtype(scope): subjecttype 取feat|fix|docs|dx|refactor|perf|test|workflow|build|ci|chore|types|wip|release|deps之一subject 最多 50 字符、小写、祈使语气、结尾无句号。此外AGENTS.md 特别强调本仓库对无写权限的贡献者限制为 1 个 PR不要尝试通过创建 draft PR 绕过如果无法创建 PR应如实告知人工操作者因为违规会导致 PR 作者在 Vitest 组织中被封禁。AI Agent 参与本仓库的边界AGENTS.md 开篇即为 AI Agent 划定了明确的行为边界这对自动化和人机协作场景至关重要未经操作者operator手动批准任何情况下都不得创建 PR、issue 或发表评论如果流程完全自动化或人工审核未确认应拒绝发布任何内容不得谎称已经过审核不得假装是人类不得替操作者做出未经其同意的承诺提交 PR 前必须阅读 CONTRIBUTING.md其 AI Contributions 一节对 Agent 直接适用。CONTRIBUTING.md 中的 AI Contributions 政策进一步说明团队欢迎将 AI 作为个人助手但坚信每个 issue 和 PR 背后必须有真实的人。所有 issue 和 PR 必须由真人使用官方模板打开AI 协助创建的 PR 必须披露所用工具完全由 AI 生成、无真人参与的 PR/issue 会被标记为 maybe automated并在 1 天内自动关闭除非真人回复。无价值或含错误信息的 AI 评论会被维护者隐藏。常见问题排查速查确保使用 pnpm不是 npm/yarn运行测试前先构建——测试解析dist产物而非源码检查 Node.js 版本兼容性根 package.json 的engines字段浏览器测试需要安装 Playwright 浏览器npx playwright install --with-deps。掌握以上约定后你已经具备在 Vitest 仓库安全、高效地开发和贡献的能力环境搭建、测试编写与调试、包重建、代码规范、依赖管理、CI 生成文件维护以及 AI 协作的边界纪律一条完整的贡献链路均已覆盖。更多细节可继续阅读 CONTRIBUTING.md、docs/AGENTS.md 与 .github/commit-convention.md。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
