Vitest attachmentsDir 配置详解管理 context.annotate 附件存储目录【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestattachmentsDir是 Vitest 中用于指定测试附件attachments存储目录的核心配置项它决定了由context.annotate创建的文件附件最终落盘的路径。本文将从配置参数、解析机制、CLI 用法、projects 模式下的共享行为到源码级实现原理全面讲解这一配置项帮助你正确规划测试产物的输出位置与目录结构。配置项概览attachmentsDir是test配置下的一个顶层选项其定义如下类型Typestring默认值Default.vitest/attachments作用指定由context.annotate创建的文件附件file attachments的存储目录路径在 配置类型定义 中该选项的 TypeScript 声明为/** * Directory path for storing attachments created by context.annotate * * default .vitest/attachments */ attachmentsDir?: string也就是说当你使用context.annotate(message, { path: ... })为测试附加文件时Vitest 会把这个文件复制到attachmentsDir指向的目录中供 reporter 读取与展示。如何配置 attachmentsDir在 vitest.config 中配置如果你使用独立的 Vitest 配置文件配置入口参考import { defineConfig } from vitest/config export default defineConfig({ test: { attachmentsDir: .vitest/attachments, }, })在 vite.config 中配置如果项目已有 Vite 配置可以直接在test属性中声明并借助类型引用获得补全提示/// reference typesvitest/config / import { defineConfig } from vite export default defineConfig({ test: { attachmentsDir: ./test-results/attachments, }, })通过 CLI 配置该选项也暴露为 CLI 参数定义见 cli-config.tsvitest --attachmentsDir .vitest/attachmentsCLI 参数描述为The directory where attachments fromcontext.annotateare stored in (default:.vitest/attachments)接收一个dir参数。CLI 传入的值与配置文件中的值都会进入统一的配置解析流程。解析规则相对于 root 解析attachmentsDir是一个相对于 Vitest root 配置解析的相对路径。在配置解析阶段resolveConfig.tsVitest 会将其与resolved.root拼接为绝对路径resolved.attachmentsDir resolve( resolved.root, resolved.attachmentsDir ?? .vitest/attachments, )这意味着如果不配置该选项默认会生成root/.vitest/attachments目录如果配置为相对路径如artifacts最终会解析为root/artifacts如果配置为绝对路径则直接使用该路径resolve对绝对路径原样返回。解析后的结果会被写入 resolved config并通过 serializeConfig.ts 序列化后下发到 worker 运行时运行时侧的类型定义见 runtime/config.ts。路径命名规则与目录创建当测试通过annotate附加本地文件path形式的附件时Vitest 负责把文件复制进attachmentsDir。核心实现位于 test-run.ts 的resolveTestAttachment方法const currentPath resolve(project.config.root, path) const hash createHash(sha1).update(currentPath).digest(hex) const newPath resolve( project.config.attachmentsDir, ${filename ? ${sanitizeFilePath(filename)}- : }${hash}${extname(currentPath)}, ) if (!existsSync(project.config.attachmentsDir)) { await mkdir(project.config.attachmentsDir, { recursive: true }) } await copyFile(currentPath, newPath)从中可以提炼出几个关键行为源文件解析附件源路径基于该测试所属项目的root解析为绝对路径命名防冲突目标文件名由「可选的文件名前缀 源路径的 SHA-1 哈希 原始扩展名」组成避免并发测试之间互相覆盖自动建目录若目录不存在会以recursive: true递归创建即支持多级路径内容类型推断复制完成后会通过mime.getType根据源文件名推断contentType外部链接例外如果附件path以http://或https://开头则视为外部链接不会复制到attachmentsDir。与 context.annotate 的协作流程attachmentsDir的价值体现在完整的测试注解流程中注解指南。典型用法如下test(creates a file attachment, async ({ annotate }) { const file createTestSpecificFile() await annotate(creates a file, { body: file }) await annotate(attaches an existing file, { path: ./report.json }) })使用body时附件内容直接由 Vitest 序列化无需经过attachmentsDir使用path时Vitest 会按上文所述将文件复制到attachmentsDir并把附件的path重写为复制后的新路径同时通过onTestCaseAnnotate上报给 reportertest-run.ts。注意annotate返回的是 Promise建议始终await它即使不 awaitVitest 也会在测试结束前自动等待所有未完成的注解。各类 reporter 对附件/注解的呈现方式不同defaultreporter 仅在测试失败时打印注解verbose是唯一在测试通过时也展示注解的终端 reporterjunit与tap只输出类型和消息并忽略附件。下图展示了注解在 HTML reporter即 Vitest UI中的呈现效果projects 模式仅根配置生效、全局共享attachmentsDir是一个带有CRoot /标记的配置项参见 docs/config/index.md 中的说明意味着它只能在根 Vitest 配置中设置不能按 project 单独配置。在配置解析时resolveConfig.ts当存在全局root配置时每个 project 都会继承根配置中的attachmentsDir// These options are resolved once for the whole run using the root config. if (globalConfig) { resolved.coverage globalConfig.coverage resolved.attachmentsDir globalConfig.attachmentsDir resolved.mergeReportsLabel globalConfig.mergeReportsLabel }也就是说所有 project 共享同一个attachmentsDir即使某个 project 在自己的配置里写了attachmentsDir该值也会被忽略。这一行为有对应的端到端测试验证见 test/e2e/test/annotations.test.ts 中的attachmentsDir is root only用例该测试在projects: [./packages/*]的配置下让client与server两个 project 分别注解各自的本地文件最终断言两个附件都出现在根目录的.vitest/attachments中const files readdirSync(path.join(result.root, .vitest/attachments)) const contents files.sort().map(file result.fs.readFile(path.join(.vitest/attachments, file)), ) // 断言结果为 [HELLO, WORLD]这条测试从实践层面确认附件目录是按整个测试运行统一管理的而不是按 project 分散存放。实践建议与注意事项加入版本控制忽略列表附件目录通常是测试运行产物建议在.gitignore中加入**/.vitest/attachments避免把测试中间产物提交进仓库。注意磁盘占用每个path型附件都会在attachmentsDir中被复制一份大量或大体积附件会显著增加磁盘消耗可通过集中清理脚本或在 CI 结束后清理该目录。区分附件与注解只有文件类path附件会落盘到attachmentsDir纯消息与body型附件由 reporter 直接消费不产生文件。projects 下的全局规划由于所有 project 共享该目录且命名带有 SHA-1 哈希不同 project 的文件不会冲突但若需要按 project 隔离产物应通过 reporter 层或其他机制如测试文件名自行区分无法通过 per-project 的attachmentsDir实现。配合 reporter 使用附件最终由 reporters 消费若你的 reporter 未实现附件展示逻辑该目录中的文件仅作为原始产物保留。相关资源Test Contextcontext.annotate 用法Test Annotations测试注解指南Projectsworkspace 项目模式配置类型定义配置解析实现附件复制与命名实现CLI 参数定义附件目录共享行为测试【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vitest attachmentsDir 配置详解：管理 context.annotate 附件存储目录
Vitest attachmentsDir 配置详解管理 context.annotate 附件存储目录【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestattachmentsDir是 Vitest 中用于指定测试附件attachments存储目录的核心配置项它决定了由context.annotate创建的文件附件最终落盘的路径。本文将从配置参数、解析机制、CLI 用法、projects 模式下的共享行为到源码级实现原理全面讲解这一配置项帮助你正确规划测试产物的输出位置与目录结构。配置项概览attachmentsDir是test配置下的一个顶层选项其定义如下类型Typestring默认值Default.vitest/attachments作用指定由context.annotate创建的文件附件file attachments的存储目录路径在 配置类型定义 中该选项的 TypeScript 声明为/** * Directory path for storing attachments created by context.annotate * * default .vitest/attachments */ attachmentsDir?: string也就是说当你使用context.annotate(message, { path: ... })为测试附加文件时Vitest 会把这个文件复制到attachmentsDir指向的目录中供 reporter 读取与展示。如何配置 attachmentsDir在 vitest.config 中配置如果你使用独立的 Vitest 配置文件配置入口参考import { defineConfig } from vitest/config export default defineConfig({ test: { attachmentsDir: .vitest/attachments, }, })在 vite.config 中配置如果项目已有 Vite 配置可以直接在test属性中声明并借助类型引用获得补全提示/// reference typesvitest/config / import { defineConfig } from vite export default defineConfig({ test: { attachmentsDir: ./test-results/attachments, }, })通过 CLI 配置该选项也暴露为 CLI 参数定义见 cli-config.tsvitest --attachmentsDir .vitest/attachmentsCLI 参数描述为The directory where attachments fromcontext.annotateare stored in (default:.vitest/attachments)接收一个dir参数。CLI 传入的值与配置文件中的值都会进入统一的配置解析流程。解析规则相对于 root 解析attachmentsDir是一个相对于 Vitest root 配置解析的相对路径。在配置解析阶段resolveConfig.tsVitest 会将其与resolved.root拼接为绝对路径resolved.attachmentsDir resolve( resolved.root, resolved.attachmentsDir ?? .vitest/attachments, )这意味着如果不配置该选项默认会生成root/.vitest/attachments目录如果配置为相对路径如artifacts最终会解析为root/artifacts如果配置为绝对路径则直接使用该路径resolve对绝对路径原样返回。解析后的结果会被写入 resolved config并通过 serializeConfig.ts 序列化后下发到 worker 运行时运行时侧的类型定义见 runtime/config.ts。路径命名规则与目录创建当测试通过annotate附加本地文件path形式的附件时Vitest 负责把文件复制进attachmentsDir。核心实现位于 test-run.ts 的resolveTestAttachment方法const currentPath resolve(project.config.root, path) const hash createHash(sha1).update(currentPath).digest(hex) const newPath resolve( project.config.attachmentsDir, ${filename ? ${sanitizeFilePath(filename)}- : }${hash}${extname(currentPath)}, ) if (!existsSync(project.config.attachmentsDir)) { await mkdir(project.config.attachmentsDir, { recursive: true }) } await copyFile(currentPath, newPath)从中可以提炼出几个关键行为源文件解析附件源路径基于该测试所属项目的root解析为绝对路径命名防冲突目标文件名由「可选的文件名前缀 源路径的 SHA-1 哈希 原始扩展名」组成避免并发测试之间互相覆盖自动建目录若目录不存在会以recursive: true递归创建即支持多级路径内容类型推断复制完成后会通过mime.getType根据源文件名推断contentType外部链接例外如果附件path以http://或https://开头则视为外部链接不会复制到attachmentsDir。与 context.annotate 的协作流程attachmentsDir的价值体现在完整的测试注解流程中注解指南。典型用法如下test(creates a file attachment, async ({ annotate }) { const file createTestSpecificFile() await annotate(creates a file, { body: file }) await annotate(attaches an existing file, { path: ./report.json }) })使用body时附件内容直接由 Vitest 序列化无需经过attachmentsDir使用path时Vitest 会按上文所述将文件复制到attachmentsDir并把附件的path重写为复制后的新路径同时通过onTestCaseAnnotate上报给 reportertest-run.ts。注意annotate返回的是 Promise建议始终await它即使不 awaitVitest 也会在测试结束前自动等待所有未完成的注解。各类 reporter 对附件/注解的呈现方式不同defaultreporter 仅在测试失败时打印注解verbose是唯一在测试通过时也展示注解的终端 reporterjunit与tap只输出类型和消息并忽略附件。下图展示了注解在 HTML reporter即 Vitest UI中的呈现效果projects 模式仅根配置生效、全局共享attachmentsDir是一个带有CRoot /标记的配置项参见 docs/config/index.md 中的说明意味着它只能在根 Vitest 配置中设置不能按 project 单独配置。在配置解析时resolveConfig.ts当存在全局root配置时每个 project 都会继承根配置中的attachmentsDir// These options are resolved once for the whole run using the root config. if (globalConfig) { resolved.coverage globalConfig.coverage resolved.attachmentsDir globalConfig.attachmentsDir resolved.mergeReportsLabel globalConfig.mergeReportsLabel }也就是说所有 project 共享同一个attachmentsDir即使某个 project 在自己的配置里写了attachmentsDir该值也会被忽略。这一行为有对应的端到端测试验证见 test/e2e/test/annotations.test.ts 中的attachmentsDir is root only用例该测试在projects: [./packages/*]的配置下让client与server两个 project 分别注解各自的本地文件最终断言两个附件都出现在根目录的.vitest/attachments中const files readdirSync(path.join(result.root, .vitest/attachments)) const contents files.sort().map(file result.fs.readFile(path.join(.vitest/attachments, file)), ) // 断言结果为 [HELLO, WORLD]这条测试从实践层面确认附件目录是按整个测试运行统一管理的而不是按 project 分散存放。实践建议与注意事项加入版本控制忽略列表附件目录通常是测试运行产物建议在.gitignore中加入**/.vitest/attachments避免把测试中间产物提交进仓库。注意磁盘占用每个path型附件都会在attachmentsDir中被复制一份大量或大体积附件会显著增加磁盘消耗可通过集中清理脚本或在 CI 结束后清理该目录。区分附件与注解只有文件类path附件会落盘到attachmentsDir纯消息与body型附件由 reporter 直接消费不产生文件。projects 下的全局规划由于所有 project 共享该目录且命名带有 SHA-1 哈希不同 project 的文件不会冲突但若需要按 project 隔离产物应通过 reporter 层或其他机制如测试文件名自行区分无法通过 per-project 的attachmentsDir实现。配合 reporter 使用附件最终由 reporters 消费若你的 reporter 未实现附件展示逻辑该目录中的文件仅作为原始产物保留。相关资源Test Contextcontext.annotate 用法Test Annotations测试注解指南Projectsworkspace 项目模式配置类型定义配置解析实现附件复制与命名实现CLI 参数定义附件目录共享行为测试【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考