开发工具文档【免费下载链接】quarto-cliOpen-source scientific and technical publishing system built on Pandoc.项目地址https://gitcode.com/gh_mirrors/qu/quarto-cli点击查看免费下载本篇指南以 Quarto CLI 仓库中的测试基础设施为核心系统讲解如何为这一基于 Deno 构建的科学出版工具编写可靠的 smoke 测试。你将掌握testQuartoCmd/testRender两种入口的使用边界、验证器与路径辅助函数的完整语义、Dev 模式与 Binary 模式的行为差异、引擎环境与跨平台陷阱以及 YAML 内嵌测试的转义规则——全部知识点均有仓库源码与真实测试文件作为依据。测试架构总览四个核心文件Quarto CLI 的测试体系建立在四个相互协作的文件之上tests/文件职责tests/test.ts核心测试运行器导出testQuartoCmd、unitTest、TestContext等基础设施tests/quarto-cmd.tsQuarto 调用分发runQuarto()统一处理进程内 Dev 模式与子进程 Binary 模式tests/verify.ts验证辅助函数如fileExists、noErrors、ensureHtmlElements等tests/utils.ts通用工具如docs()、outputForInput()、withTempDir()testQuartoCmd是 smoke 测试的统一入口tests/test.ts它会自动以quarto cmd args生成测试名调用runQuarto()执行命令并通过throwOnFailure: false把失败留给验证器从日志中报告。日志默认以json-stream格式写入临时文件验证器Verify随后逐条解析这些 JSON 记录见 readExecuteOutput。Dev 模式与 Binary 模式runQuarto()通过是否存在QUARTO_TEST_BIN环境变量来决定运行方式tests/quarto-cmd.tsDev 模式默认直接以进程内方式调用从 src/quarto.ts 导入的quarto()入口函数无退出码概念失败通过 Promise 拒绝reject来表达。Binary 模式QUARTO_TEST_BIN指向 checkout 之外已安装的 Quarto 发行版。runQuarto()以子进程方式启动它并通过--log、--log-format json-stream、--log-level参数捕获 JSON 流日志启动前会用buildBinaryEnv()清除 dev 树环境变量清单见 tests/binary-mode-strip-env.txt。assertTestBinary()会预检该二进制拒绝报告99.9.9dev 版本哨兵的二进制说明它解析到了 TS 源码而非已构建发行版也支持用QUARTO_TEST_EXPECTED_VERSION校验精确版本tests/quarto-cmd.ts。Binary 模式下默认只运行tests/smoke/目录下的测试。CI 行为与设计决策详见 llm-docs/built-version-testing-architecture.md。写 smoke 测试时应遵循的纪律一律通过testQuartoCmd()或runQuarto()调用 Quarto不要直接从src/quarto.ts导入quarto()。需要在测试中直接启动子进程时用quartoDevCmd()解析可执行文件路径tests/utils.ts并传入quartoSpawnEnvOptions()tests/quarto-cmd.ts保证 Binary 模式下的环境清洗。TestContext.requiresDevQuarto: true只用于确实依赖进程内实现细节的测试Binary 模式下会被自动忽略见 tests/test.ts能用单元测试解决的就不要写 smoke 测试。常用测试模式一简单渲染测试最简形式测试单个文档渲染并自动清理import { docs } from ../../utils.ts; import { testRender } from ./render.ts; // 最简形式——只渲染并验证输出已创建 testRender(docs(test-plain.md), html, false);testRender()定义在 tests/smoke/render/render.ts它会自动向验证列表追加outputCreated检查日志中存在 Output created: 消息且输出文件存在以及noSupportingFiles/hasSupportingFiles断言并在 teardown 中调用cleanoutput()清理输出与_files/目录。真实示例见 tests/smoke/render/render-plain.test.ts。带附加验证器import { docs, outputForInput } from ../../utils.ts; import { testRender } from ./render.ts; import { ensureHtmlElements } from ../../verify.ts; const input docs(minimal.qmd); const output outputForInput(input, html); testRender(input, html, true, [ ensureHtmlElements(output.outputPath, [], [script#quarto-html-after-body]), ]);真实示例见 tests/smoke/render/render-minimal.test.ts。ensureHtmlElements使用仓库内置的deno-dom解析 HTMLsrc/core/deno-dom.ts第一个数组是必须存在的选择器第二个是必须不存在的选择器。关键点testRender()自动处理输出验证与清理QUARTO_TEST_KEEP_OUTPUTS环境变量可保留输出用于调试tests/smoke/render/render.ts。noSupporting参数要与实际输出匹配true——真正自包含的 HTML无_files/目录全部内联仅用于self-contained: true之类的格式false——存在支持文件目录的 HTMLOJS 运行时、widget 依赖、图表等。绝大多数 HTML 输出应使用false。附加验证器通过数组参数传入可选。常用测试模式二项目渲染测试网站类项目渲染是 smoke 测试的高频场景import { docs } from ../../utils.ts; import { join } from ../../../src/deno_ral/path.ts; import { existsSync } from ../../../src/deno_ral/fs.ts; import { testQuartoCmd } from ../../test.ts; import { fileExists, pathDoNotExists, noErrors } from ../../verify.ts; const projectDir docs(project/my-test); // 通过 docs() 得到相对路径 const outputDir join(projectDir, _site); // 网站项目追加 _site 输出目录 testQuartoCmd( render, [projectDir], [ noErrors, // 检查无错误 fileExists(join(outputDir, index.html)), // 验证期望的文件存在 pathDoNotExists(join(outputDir, ignored.html)), // 验证文件不存在 ], { teardown: async () { if (existsSync(outputDir)) { await Deno.remove(outputDir, { recursive: true }); } }, }, );关键点用docs()辅助函数基于tests/docs/构造相对路径。网站项目输出到_site子目录用join()构造绝对路径用于文件验证。在teardown中清理输出目录。真实示例见 tests/smoke/project/project-website.test.ts 与 tests/smoke/project/project-ignore-dirs.test.ts。常用测试模式三性能预算渲染超时testQuartoCmd默认给每次渲染 10 分钟600000ms超时tests/quarto-cmd.ts。如果测试是在守卫性能回归某个渲染不应挂起应通过TestContext.timeout毫秒设置更紧的预算让回归快速失败而不是耗满 10 分钟testQuartoCmd(render, [projectDir], [noErrors /*, ... */], { timeout: 120000, // 健康渲染远低于此值挂起会触发 setup: () { writeProject(); // 在临时目录生成 fixture 项目 return Promise.resolve(); }, teardown: () { safeRemoveSync(projectDir, { recursive: true }); return Promise.resolve(); }, });关键点给慢机器留足余量同时为该修复配一个确定性的单元测试。Dev进程内模式下超时的渲染不会被 harness 杀死超时只是 reject Promise因此在 Windows 上可能仍占用输出目录请在 teardown 中使用safeRemoveSync并把清理视为尽力而为。Binary 模式QUARTO_TEST_BIN下超时时会杀死派生的进程树killProcessTree通过 Windowstaskkill /T /F或 Unixpgrep -P枚举后 SIGKILL见 tests/quarto-cmd.ts但 kill 仍是尽力而为——保持同样的防御性 teardown。超时错误以QuartoTimeoutError区分于普通失败renderCancelled标识渲染是否已知被停止tests/quarto-cmd.ts。常用测试模式四扩展模板测试测试quarto use templateimport { testQuartoCmd } from ../../test.ts; import { fileExists, noErrorsOrWarnings, pathDoNotExists, } from ../../verify.ts; import { join } from ../../../src/deno_ral/path.ts; import { ensureDirSync } from ../../../src/deno_ral/fs.ts; const tempDir Deno.makeTempDirSync(); // 创建 mock 模板源 const templateSourceDir join(tempDir, template-source); ensureDirSync(templateSourceDir); Deno.writeTextFileSync(join(templateSourceDir, template.qmd), ...); Deno.writeTextFileSync(join(templateSourceDir, config.yml), ...); const templateFolder my-test-template; const workingDir join(tempDir, templateFolder); ensureDirSync(workingDir); testQuartoCmd( use, [template, templateSourceDir, --no-prompt], [ noErrorsOrWarnings, fileExists(${templateFolder}.qmd), // 相对路径——模板文件被重命名为文件夹名 pathDoNotExists(join(workingDir, README.md)), // 绝对路径——被排除的文件 ], { cwd: () workingDir, // 设置工作目录 teardown: () { try { Deno.removeSync(tempDir, { recursive: true }); } catch { // 忽略清理错误 } return Promise.resolve(); }, }, );关键点用Deno.makeTempDirSync()获得隔离的测试环境。创建带测试文件的 mock 模板源。模板文件会被重命名为目标目录名。用cwd()函数设置命令执行的工作目录。清理整个临时目录含源文件。验证位于cwd()内的文件时使用相对路径。真实示例见 tests/smoke/use/template.test.ts。常用测试模式五工作目录敏感测试某些测试依赖特定工作目录例如复现依赖进程 cwd 的 bug。不要在测试体内调用Deno.chdir()——它会修改进程全局 cwd泄漏到同一进程中的其他测试。应使用TestContext选项harness 在测试前切换 cwd测试后恢复tests/test.ts、tests/test.tsconst workingDir Deno.makeTempDirSync(); unitTest(runs from workingDir, async () { // 此处 cwd 是 workingDir由 harness 设置 }, { setup: () { Deno.writeTextFileSync(.env.example, ...); return Promise.resolve(); }, cwd: () workingDir, teardown: () { try { Deno.removeSync(workingDir, { recursive: true }); } catch { /* 尽力而为 */ } return Promise.resolve(); }, });关键点harness先调用cwd()再调用setup()所以cwd()执行时目录必须已存在——要在模块作用域创建目录而不是在setup中创建。teardown在 harness 恢复 cwd之前执行因此 Windows 上临时目录可能仍是当前 cwd 而无法删除。请用 try/catch 包裹删除操作尽力而为——参考 tests/smoke/use/template.test.ts 与 tests/unit/dotenv-config.test.ts。若临时目录不需要作为运行目录优先使用withTempDirtests/utils.ts它在finally中创建并递归删除。只需相对输入不需要特定 cwd的测试可直接传相对于当前 cwd 的路径relative(Deno.cwd(), absFile)完全不需要切换目录。验证器辅助函数速查核心验证器tests/verify.ts// 输出中无错误 noErrors // 无错误或警告 noErrorsOrWarnings // 路径存在文件 fileExists(path: string) // 路径不存在 pathDoNotExists(path: string) // 路径存在文件夹 folderExists(path: string) // 目录只包含允许的路径 directoryEmptyButFor(dir: string, allowedFiles: string[])noErrors的实现按日志记录的levelName是否为error判定tests/verify.tsnoErrorsOrWarnings额外把warn计入失败tests/verify.ts。仓库还提供了shouldError期望渲染失败、printsMessage匹配指定级别日志、ensureHtmlElements/ensureHtmlElementContents/ensureHtmlElementCountDOM 断言、ensureFileRegexMatches/ensureCssRegexMatches文本正则、ensureSnapshotMatches快照对比diff 保存在.diff文件、ensurePdfRegexMatches依赖 PATH 上的pdftotext、verifyDocXDocument/verifyEpubDocument/verifyPptxDocument解压 OOXML 检查以及 JATS/Odt/Docx/Pptx 的 XPath 断言族按需选用。路径辅助函数tests/utils.ts// 从 tests/docs/ 构造相对路径 docs(path: string): string // 示例docs(project/site) → tests/docs/project/site // 计算输入文件的期望输出 outputForInput(input: string, to: string, projectOutDir?: string, projectRoot?: string) // 查找项目目录向上查找 _quarto.yml/_quarto.yaml findProjectDir(input: string, until?: RegExp) // 查找项目输出目录_site、_book 等 findProjectOutputDir(projectdir: string)findProjectOutputDir读取项目_quarto.ymlbook→_bookwebsite→project.output-dir或默认_sitemanuscript→project.output-dir或默认_manuscript其余按project.output-dir或空字符串处理tests/utils.ts。outputForInput会根据目标格式推断扩展名如pdf→.pdf、revealjs→.html、jats→.xml、typst→.pdf等tests/utils.ts。输出目录模式不同项目类型使用不同输出目录// 网站项目 const outputDir join(projectDir, _site); // 书籍项目 const outputDir join(projectDir, _book); // 手稿项目 const outputDir join(projectDir, _manuscript); // 普通项目未指定类型 // 输出直接在项目目录内 const outputDir projectDir;测试文件组织tests/ ├── docs/ # 测试 fixtures │ └── project/ │ └── my-test/ │ ├── _quarto.yml │ ├── index.qmd │ └── other-files.qmd ├── smoke/ # smoke 测试 │ ├── project/ │ │ └── project-my-test.test.ts │ ├── render/ │ ├── use/ │ └── ... ├── test.ts # 测试运行器 ├── verify.ts # 验证辅助函数 └── utils.ts # 通用工具函数通用模式清理模式始终在 teardown 中清理生成的文件teardown: async () { if (existsSync(outputPath)) { await Deno.remove(outputPath, { recursive: true }); } };多测试用例测试多个场景时在模块级声明常量const tempDir Deno.makeTempDirSync(); // 用例 1 const folder1 test-case-1; const workingDir1 join(tempDir, folder1); ensureDirSync(workingDir1); testQuartoCmd(...); // 用例 2 const folder2 test-case-2; const workingDir2 join(tempDir, folder2); ensureDirSync(workingDir2); testQuartoCmd(...);路径构造绝对路径所有路径操作使用join()跨平台安全。相对 docs用docs()辅助函数。相对 cwd在模板测试中用普通字符串或模板字面量。仓库中的真实示例场景参考文件最简渲染测试无附加验证器tests/smoke/render/render-plain.test.ts带 HTML 元素自定义验证的渲染tests/smoke/render/render-minimal.test.ts目录排除模式tests/smoke/project/project-ignore-dirs.test.ts网站项目渲染tests/smoke/project/project-website.test.ts扩展模板使用tests/smoke/use/template.test.ts引擎特定测试注意事项共享测试环境quarto-cli 测试的关键约束Quarto-cli 测试基础设施为所有测试使用单一托管环境Juliatests/Project.tomltests/Manifest.tomlPythontests/.venv/由 uv/pyproject.toml 管理Rtests/renv/tests/renv.lockconfigure-test-env脚本tests/configure-test-env.sh / tests/configure-test-env.ps1只管理上述主环境CI 构建依赖此结构。不要在测试子目录中创建语言环境文件tests/docs/my-test/ ├── Project.toml # ❌ 错误——破坏测试基础设施 ├── .venv/ # ❌ 错误——破坏测试基础设施 ├── renv.lock # ❌ 错误——破坏测试基础设施 └── test.qmd为什么会失败Julia 向上查找Project.toml并使用找到的第一个。Python/R 若存在本地环境会优先使用。CI 脚本不会配置这些本地环境。测试在本地能过、在 CI 必然失败。添加新的包依赖对任意引擎Julia、Python、R都添加到tests/主环境# Julia在 tests/ 目录使用 Pkg cd tests julia --project. -e using Pkg; Pkg.add(PackageName) # 然后运行 configure 更新环境 ./configure-test-env.sh # Windows 用 .ps1 # Python在 tests/ 目录使用 uv cd tests uv add packagename # R编辑 tests/DESCRIPTION然后 cd tests Rscript -e renv::install(); renv::snapshot()注意虽然 Quarto 生产使用支持文档目录中的本地Project.toml但 quarto-cli 测试基础设施明确不支持这种模式。所有测试依赖必须放在tests/主环境中。改变工作目录的 R 测试R 从精确的进程 cwd 解析.Rprofile不向上搜索父目录。在 CI 上rmarkdown/knitr 只存在于tests/renv的项目库中当 cwd 为tests/时通过tests/.Rprofilesource 的renv/activate.R激活。大多数 knitr 测试从不离开tests/——它们传入相对当前 cwd 的路径而不是切换目录——因此激活自动发生。通过TestContext.cwd()切换 cwd 的测试会失去该激活R 子进程在tests/之外启动包加载可能失败并报there is no package called rmarkdown。开发者机器上若 rmarkdown 位于默认.libPaths()可能掩盖这个 CI 失败。修复在 fixture 的 cwd 中写一个.Rprofile让 renv 指向测试项目Sys.setenv(RENV_PROJECT tests/ 的绝对路径) source(tests/ 的绝对路径/renv/activate.R)renv/activate.R使用RENV_PROJECT作为项目根而不是当前目录。最佳实践清单始终清理用 teardown 删除生成的文件。使用辅助函数用docs()、fileExists()等而不是手写检查。绝对路径所有路径构造用join()处理平台差异。测试隔离创建文件的测试使用临时目录。清晰命名使用描述性变量名如projectDir、outputDir、templateFolder。注释意图添加注释说明应该/不应该发生什么。处理错误用 try-catch 包裹清理避免清理问题导致测试套件失败。环境变量测试陷阱Deno.env.set()修改进程全局状态。Deno 默认并行运行测试文件同一 OS 进程因此并发测试可能看到被修改的值。保存/恢复模式也无济于事——其他测试在修改窗口期内仍会看到该值。执行模式风险原因./run-tests.sh默认竞态条件文件并行运行共享Deno.env./run-parallel-tests.sh无独立 OS 进程推荐做法通过TestContext.env传入每个测试的变量。这在两种模式下都有效且不修改进程全局状态harness 会把它作为 overlay 传给runQuarto。例外tests/smoke/website/drafts-env.test.ts 在模块加载时设置QUARTO_PROFILE并在context.env中重复设置。Dev 模式在缓存基础 profile 时读取模块级值Binary 模式接收 context 值。新测试的替代方案单元测试 env 读取函数、重构代码接受参数、或使用子进程隔离。测试文件排除测试文件被排除如 AI 配置文件时// 测试文件 NOT 被渲染 testQuartoCmd( render, [projectDir], [ noErrors, fileExists(join(outputDir, expected.html)), // 应存在 pathDoNotExists(join(outputDir, excluded.html)), // 不应存在 ], // ... );先在没有修复时运行测试确认它失败再验证修复后通过。Smoke-All 测试YAML 内嵌Smoke-all 测试通过_quarto.tests元数据把测试规格直接嵌入.qmd文件tests/smoke/smoke-all.test.ts完整文档见.claude/rules/testing/smoke-all-tests.md。YAML 正则转义关键规则核心规则在 YAML 单引号字符串中\(与\\(等价——都产生正则中的字面量\(。常见错误过度转义为\\(会产生\\(两个反斜杠导致正则失败。_quarto: tests: pdf: ensureLatexFileRegexMatches: # 正确——YAML 单引号中单个反斜杠 - [\(1\), \\circled\{1\}, Variable assignment] - [\\CommentTok, \\begin\{Shaded\}] # 错误——过度转义正则中产生 \\( - [\\(1\\), \\\\circled\\{1\\}]YAML 转义速查表要在文件中匹配单引号...双引号...\(\(\\(\begin{\\begin\{\\\\begin\\{\\字面量\\\\\\\\\\\\[正则\[\\[建议使用单引号字符串——它更简单只有本身需要转义写成。探测足够的键以暴露深层合并 bug如果优先级测试的模板只读取被覆盖的那一个键那么在深层合并deep-mergebug 下测试可能通过被丢弃的兄弟键永远不会被解析但没有断言会发现。示例用户提供的variables.quarto.language.crossref-ch-prefix: Bouquin与 Quarto 内置的format.language表在variables.quarto.language下合并。在浅层展开{ ...a, ...b }下b.language会替换整个本地化映射——所有其他$quarto.language.key$的解析静默返回空。只读取$quarto.language.crossref-ch-prefix$的模板仍断言 Bouquin因此回归测试通过了。修复方式是让模板至少探测一个未被覆盖的兄弟键。具体地回归守卫 tests/docs/smoke-all/markdown/lang-fr-user-override-deep-merge.qmd 使用模板$quarto.language.crossref-ch-prefix$|$quarto.language.toc-title-document$并断言完整字符串^Bouquin\|Table des matières\s*$。修复前输出是Bouquin|修复后是Bouquin|Table des matières。启发式规则为任意两个结构化配置树的合并编写优先级 smoke 测试时确保断言至少覆盖一条用户没有覆盖的路径。否则测试只证明被覆盖的值生效了——而没有证明其余部分存活。赞分享开发工具文档【免费下载链接】quarto-cliOpen-source scientific and technical publishing system built on Pandoc.项目地址https://gitcode.com/gh_mirrors/qu/quarto-cli点击查看免费下载相关推荐mockery 的 include-auto-generated 配置让 mock 生成器正确处理自动生成源码mockery 的 include auto generated 配置让 mock 生成器正确处理自动生成源码 导读 Go 生态中存在大量由代码生成器产出的源开发工具文档Quarto CLI 的 TypeScript 测试体系Smoke 与 Unit 测试编写实战指南Quarto CLI 的 TypeScript 测试体系Smoke 与 Unit 测试编写实战指南 Quarto 是一个基于 Pandoc 的开源科学出版系统开发工具文档抖音批量下载工具教程从单个视频到整站存档的完整上手指南抖音批量下载工具教程从单个视频到整站存档的完整上手指南 douyin downloader 是一个开源免费的抖音批量下载工具基于 Python 编写核心能CLI开发工具上一篇一文搞外文视频的中文字幕PotPlayer 字幕翻译免费配置完整指南下一篇League Director 快速上手指南把 LOL 回放剪成电影级运镜视频只需这 6 步创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
开发工具文档【免费下载链接】quarto-cliOpen-source scientific and technical publishing system built on Pandoc.项目地址https://gitcode.com/gh_mirrors/qu/quarto-cli点击查看免费下载本篇指南以 Quarto CLI 仓库中的测试基础设施为核心系统讲解如何为这一基于 Deno 构建的科学出版工具编写可靠的 smoke 测试。你将掌握testQuartoCmd/testRender两种入口的使用边界、验证器与路径辅助函数的完整语义、Dev 模式与 Binary 模式的行为差异、引擎环境与跨平台陷阱以及 YAML 内嵌测试的转义规则——全部知识点均有仓库源码与真实测试文件作为依据。测试架构总览四个核心文件Quarto CLI 的测试体系建立在四个相互协作的文件之上tests/文件职责tests/test.ts核心测试运行器导出testQuartoCmd、unitTest、TestContext等基础设施tests/quarto-cmd.tsQuarto 调用分发runQuarto()统一处理进程内 Dev 模式与子进程 Binary 模式tests/verify.ts验证辅助函数如fileExists、noErrors、ensureHtmlElements等tests/utils.ts通用工具如docs()、outputForInput()、withTempDir()testQuartoCmd是 smoke 测试的统一入口tests/test.ts它会自动以quarto cmd args生成测试名调用runQuarto()执行命令并通过throwOnFailure: false把失败留给验证器从日志中报告。日志默认以json-stream格式写入临时文件验证器Verify随后逐条解析这些 JSON 记录见 readExecuteOutput。Dev 模式与 Binary 模式runQuarto()通过是否存在QUARTO_TEST_BIN环境变量来决定运行方式tests/quarto-cmd.tsDev 模式默认直接以进程内方式调用从 src/quarto.ts 导入的quarto()入口函数无退出码概念失败通过 Promise 拒绝reject来表达。Binary 模式QUARTO_TEST_BIN指向 checkout 之外已安装的 Quarto 发行版。runQuarto()以子进程方式启动它并通过--log、--log-format json-stream、--log-level参数捕获 JSON 流日志启动前会用buildBinaryEnv()清除 dev 树环境变量清单见 tests/binary-mode-strip-env.txt。assertTestBinary()会预检该二进制拒绝报告99.9.9dev 版本哨兵的二进制说明它解析到了 TS 源码而非已构建发行版也支持用QUARTO_TEST_EXPECTED_VERSION校验精确版本tests/quarto-cmd.ts。Binary 模式下默认只运行tests/smoke/目录下的测试。CI 行为与设计决策详见 llm-docs/built-version-testing-architecture.md。写 smoke 测试时应遵循的纪律一律通过testQuartoCmd()或runQuarto()调用 Quarto不要直接从src/quarto.ts导入quarto()。需要在测试中直接启动子进程时用quartoDevCmd()解析可执行文件路径tests/utils.ts并传入quartoSpawnEnvOptions()tests/quarto-cmd.ts保证 Binary 模式下的环境清洗。TestContext.requiresDevQuarto: true只用于确实依赖进程内实现细节的测试Binary 模式下会被自动忽略见 tests/test.ts能用单元测试解决的就不要写 smoke 测试。常用测试模式一简单渲染测试最简形式测试单个文档渲染并自动清理import { docs } from ../../utils.ts; import { testRender } from ./render.ts; // 最简形式——只渲染并验证输出已创建 testRender(docs(test-plain.md), html, false);testRender()定义在 tests/smoke/render/render.ts它会自动向验证列表追加outputCreated检查日志中存在 Output created: 消息且输出文件存在以及noSupportingFiles/hasSupportingFiles断言并在 teardown 中调用cleanoutput()清理输出与_files/目录。真实示例见 tests/smoke/render/render-plain.test.ts。带附加验证器import { docs, outputForInput } from ../../utils.ts; import { testRender } from ./render.ts; import { ensureHtmlElements } from ../../verify.ts; const input docs(minimal.qmd); const output outputForInput(input, html); testRender(input, html, true, [ ensureHtmlElements(output.outputPath, [], [script#quarto-html-after-body]), ]);真实示例见 tests/smoke/render/render-minimal.test.ts。ensureHtmlElements使用仓库内置的deno-dom解析 HTMLsrc/core/deno-dom.ts第一个数组是必须存在的选择器第二个是必须不存在的选择器。关键点testRender()自动处理输出验证与清理QUARTO_TEST_KEEP_OUTPUTS环境变量可保留输出用于调试tests/smoke/render/render.ts。noSupporting参数要与实际输出匹配true——真正自包含的 HTML无_files/目录全部内联仅用于self-contained: true之类的格式false——存在支持文件目录的 HTMLOJS 运行时、widget 依赖、图表等。绝大多数 HTML 输出应使用false。附加验证器通过数组参数传入可选。常用测试模式二项目渲染测试网站类项目渲染是 smoke 测试的高频场景import { docs } from ../../utils.ts; import { join } from ../../../src/deno_ral/path.ts; import { existsSync } from ../../../src/deno_ral/fs.ts; import { testQuartoCmd } from ../../test.ts; import { fileExists, pathDoNotExists, noErrors } from ../../verify.ts; const projectDir docs(project/my-test); // 通过 docs() 得到相对路径 const outputDir join(projectDir, _site); // 网站项目追加 _site 输出目录 testQuartoCmd( render, [projectDir], [ noErrors, // 检查无错误 fileExists(join(outputDir, index.html)), // 验证期望的文件存在 pathDoNotExists(join(outputDir, ignored.html)), // 验证文件不存在 ], { teardown: async () { if (existsSync(outputDir)) { await Deno.remove(outputDir, { recursive: true }); } }, }, );关键点用docs()辅助函数基于tests/docs/构造相对路径。网站项目输出到_site子目录用join()构造绝对路径用于文件验证。在teardown中清理输出目录。真实示例见 tests/smoke/project/project-website.test.ts 与 tests/smoke/project/project-ignore-dirs.test.ts。常用测试模式三性能预算渲染超时testQuartoCmd默认给每次渲染 10 分钟600000ms超时tests/quarto-cmd.ts。如果测试是在守卫性能回归某个渲染不应挂起应通过TestContext.timeout毫秒设置更紧的预算让回归快速失败而不是耗满 10 分钟testQuartoCmd(render, [projectDir], [noErrors /*, ... */], { timeout: 120000, // 健康渲染远低于此值挂起会触发 setup: () { writeProject(); // 在临时目录生成 fixture 项目 return Promise.resolve(); }, teardown: () { safeRemoveSync(projectDir, { recursive: true }); return Promise.resolve(); }, });关键点给慢机器留足余量同时为该修复配一个确定性的单元测试。Dev进程内模式下超时的渲染不会被 harness 杀死超时只是 reject Promise因此在 Windows 上可能仍占用输出目录请在 teardown 中使用safeRemoveSync并把清理视为尽力而为。Binary 模式QUARTO_TEST_BIN下超时时会杀死派生的进程树killProcessTree通过 Windowstaskkill /T /F或 Unixpgrep -P枚举后 SIGKILL见 tests/quarto-cmd.ts但 kill 仍是尽力而为——保持同样的防御性 teardown。超时错误以QuartoTimeoutError区分于普通失败renderCancelled标识渲染是否已知被停止tests/quarto-cmd.ts。常用测试模式四扩展模板测试测试quarto use templateimport { testQuartoCmd } from ../../test.ts; import { fileExists, noErrorsOrWarnings, pathDoNotExists, } from ../../verify.ts; import { join } from ../../../src/deno_ral/path.ts; import { ensureDirSync } from ../../../src/deno_ral/fs.ts; const tempDir Deno.makeTempDirSync(); // 创建 mock 模板源 const templateSourceDir join(tempDir, template-source); ensureDirSync(templateSourceDir); Deno.writeTextFileSync(join(templateSourceDir, template.qmd), ...); Deno.writeTextFileSync(join(templateSourceDir, config.yml), ...); const templateFolder my-test-template; const workingDir join(tempDir, templateFolder); ensureDirSync(workingDir); testQuartoCmd( use, [template, templateSourceDir, --no-prompt], [ noErrorsOrWarnings, fileExists(${templateFolder}.qmd), // 相对路径——模板文件被重命名为文件夹名 pathDoNotExists(join(workingDir, README.md)), // 绝对路径——被排除的文件 ], { cwd: () workingDir, // 设置工作目录 teardown: () { try { Deno.removeSync(tempDir, { recursive: true }); } catch { // 忽略清理错误 } return Promise.resolve(); }, }, );关键点用Deno.makeTempDirSync()获得隔离的测试环境。创建带测试文件的 mock 模板源。模板文件会被重命名为目标目录名。用cwd()函数设置命令执行的工作目录。清理整个临时目录含源文件。验证位于cwd()内的文件时使用相对路径。真实示例见 tests/smoke/use/template.test.ts。常用测试模式五工作目录敏感测试某些测试依赖特定工作目录例如复现依赖进程 cwd 的 bug。不要在测试体内调用Deno.chdir()——它会修改进程全局 cwd泄漏到同一进程中的其他测试。应使用TestContext选项harness 在测试前切换 cwd测试后恢复tests/test.ts、tests/test.tsconst workingDir Deno.makeTempDirSync(); unitTest(runs from workingDir, async () { // 此处 cwd 是 workingDir由 harness 设置 }, { setup: () { Deno.writeTextFileSync(.env.example, ...); return Promise.resolve(); }, cwd: () workingDir, teardown: () { try { Deno.removeSync(workingDir, { recursive: true }); } catch { /* 尽力而为 */ } return Promise.resolve(); }, });关键点harness先调用cwd()再调用setup()所以cwd()执行时目录必须已存在——要在模块作用域创建目录而不是在setup中创建。teardown在 harness 恢复 cwd之前执行因此 Windows 上临时目录可能仍是当前 cwd 而无法删除。请用 try/catch 包裹删除操作尽力而为——参考 tests/smoke/use/template.test.ts 与 tests/unit/dotenv-config.test.ts。若临时目录不需要作为运行目录优先使用withTempDirtests/utils.ts它在finally中创建并递归删除。只需相对输入不需要特定 cwd的测试可直接传相对于当前 cwd 的路径relative(Deno.cwd(), absFile)完全不需要切换目录。验证器辅助函数速查核心验证器tests/verify.ts// 输出中无错误 noErrors // 无错误或警告 noErrorsOrWarnings // 路径存在文件 fileExists(path: string) // 路径不存在 pathDoNotExists(path: string) // 路径存在文件夹 folderExists(path: string) // 目录只包含允许的路径 directoryEmptyButFor(dir: string, allowedFiles: string[])noErrors的实现按日志记录的levelName是否为error判定tests/verify.tsnoErrorsOrWarnings额外把warn计入失败tests/verify.ts。仓库还提供了shouldError期望渲染失败、printsMessage匹配指定级别日志、ensureHtmlElements/ensureHtmlElementContents/ensureHtmlElementCountDOM 断言、ensureFileRegexMatches/ensureCssRegexMatches文本正则、ensureSnapshotMatches快照对比diff 保存在.diff文件、ensurePdfRegexMatches依赖 PATH 上的pdftotext、verifyDocXDocument/verifyEpubDocument/verifyPptxDocument解压 OOXML 检查以及 JATS/Odt/Docx/Pptx 的 XPath 断言族按需选用。路径辅助函数tests/utils.ts// 从 tests/docs/ 构造相对路径 docs(path: string): string // 示例docs(project/site) → tests/docs/project/site // 计算输入文件的期望输出 outputForInput(input: string, to: string, projectOutDir?: string, projectRoot?: string) // 查找项目目录向上查找 _quarto.yml/_quarto.yaml findProjectDir(input: string, until?: RegExp) // 查找项目输出目录_site、_book 等 findProjectOutputDir(projectdir: string)findProjectOutputDir读取项目_quarto.ymlbook→_bookwebsite→project.output-dir或默认_sitemanuscript→project.output-dir或默认_manuscript其余按project.output-dir或空字符串处理tests/utils.ts。outputForInput会根据目标格式推断扩展名如pdf→.pdf、revealjs→.html、jats→.xml、typst→.pdf等tests/utils.ts。输出目录模式不同项目类型使用不同输出目录// 网站项目 const outputDir join(projectDir, _site); // 书籍项目 const outputDir join(projectDir, _book); // 手稿项目 const outputDir join(projectDir, _manuscript); // 普通项目未指定类型 // 输出直接在项目目录内 const outputDir projectDir;测试文件组织tests/ ├── docs/ # 测试 fixtures │ └── project/ │ └── my-test/ │ ├── _quarto.yml │ ├── index.qmd │ └── other-files.qmd ├── smoke/ # smoke 测试 │ ├── project/ │ │ └── project-my-test.test.ts │ ├── render/ │ ├── use/ │ └── ... ├── test.ts # 测试运行器 ├── verify.ts # 验证辅助函数 └── utils.ts # 通用工具函数通用模式清理模式始终在 teardown 中清理生成的文件teardown: async () { if (existsSync(outputPath)) { await Deno.remove(outputPath, { recursive: true }); } };多测试用例测试多个场景时在模块级声明常量const tempDir Deno.makeTempDirSync(); // 用例 1 const folder1 test-case-1; const workingDir1 join(tempDir, folder1); ensureDirSync(workingDir1); testQuartoCmd(...); // 用例 2 const folder2 test-case-2; const workingDir2 join(tempDir, folder2); ensureDirSync(workingDir2); testQuartoCmd(...);路径构造绝对路径所有路径操作使用join()跨平台安全。相对 docs用docs()辅助函数。相对 cwd在模板测试中用普通字符串或模板字面量。仓库中的真实示例场景参考文件最简渲染测试无附加验证器tests/smoke/render/render-plain.test.ts带 HTML 元素自定义验证的渲染tests/smoke/render/render-minimal.test.ts目录排除模式tests/smoke/project/project-ignore-dirs.test.ts网站项目渲染tests/smoke/project/project-website.test.ts扩展模板使用tests/smoke/use/template.test.ts引擎特定测试注意事项共享测试环境quarto-cli 测试的关键约束Quarto-cli 测试基础设施为所有测试使用单一托管环境Juliatests/Project.tomltests/Manifest.tomlPythontests/.venv/由 uv/pyproject.toml 管理Rtests/renv/tests/renv.lockconfigure-test-env脚本tests/configure-test-env.sh / tests/configure-test-env.ps1只管理上述主环境CI 构建依赖此结构。不要在测试子目录中创建语言环境文件tests/docs/my-test/ ├── Project.toml # ❌ 错误——破坏测试基础设施 ├── .venv/ # ❌ 错误——破坏测试基础设施 ├── renv.lock # ❌ 错误——破坏测试基础设施 └── test.qmd为什么会失败Julia 向上查找Project.toml并使用找到的第一个。Python/R 若存在本地环境会优先使用。CI 脚本不会配置这些本地环境。测试在本地能过、在 CI 必然失败。添加新的包依赖对任意引擎Julia、Python、R都添加到tests/主环境# Julia在 tests/ 目录使用 Pkg cd tests julia --project. -e using Pkg; Pkg.add(PackageName) # 然后运行 configure 更新环境 ./configure-test-env.sh # Windows 用 .ps1 # Python在 tests/ 目录使用 uv cd tests uv add packagename # R编辑 tests/DESCRIPTION然后 cd tests Rscript -e renv::install(); renv::snapshot()注意虽然 Quarto 生产使用支持文档目录中的本地Project.toml但 quarto-cli 测试基础设施明确不支持这种模式。所有测试依赖必须放在tests/主环境中。改变工作目录的 R 测试R 从精确的进程 cwd 解析.Rprofile不向上搜索父目录。在 CI 上rmarkdown/knitr 只存在于tests/renv的项目库中当 cwd 为tests/时通过tests/.Rprofilesource 的renv/activate.R激活。大多数 knitr 测试从不离开tests/——它们传入相对当前 cwd 的路径而不是切换目录——因此激活自动发生。通过TestContext.cwd()切换 cwd 的测试会失去该激活R 子进程在tests/之外启动包加载可能失败并报there is no package called rmarkdown。开发者机器上若 rmarkdown 位于默认.libPaths()可能掩盖这个 CI 失败。修复在 fixture 的 cwd 中写一个.Rprofile让 renv 指向测试项目Sys.setenv(RENV_PROJECT tests/ 的绝对路径) source(tests/ 的绝对路径/renv/activate.R)renv/activate.R使用RENV_PROJECT作为项目根而不是当前目录。最佳实践清单始终清理用 teardown 删除生成的文件。使用辅助函数用docs()、fileExists()等而不是手写检查。绝对路径所有路径构造用join()处理平台差异。测试隔离创建文件的测试使用临时目录。清晰命名使用描述性变量名如projectDir、outputDir、templateFolder。注释意图添加注释说明应该/不应该发生什么。处理错误用 try-catch 包裹清理避免清理问题导致测试套件失败。环境变量测试陷阱Deno.env.set()修改进程全局状态。Deno 默认并行运行测试文件同一 OS 进程因此并发测试可能看到被修改的值。保存/恢复模式也无济于事——其他测试在修改窗口期内仍会看到该值。执行模式风险原因./run-tests.sh默认竞态条件文件并行运行共享Deno.env./run-parallel-tests.sh无独立 OS 进程推荐做法通过TestContext.env传入每个测试的变量。这在两种模式下都有效且不修改进程全局状态harness 会把它作为 overlay 传给runQuarto。例外tests/smoke/website/drafts-env.test.ts 在模块加载时设置QUARTO_PROFILE并在context.env中重复设置。Dev 模式在缓存基础 profile 时读取模块级值Binary 模式接收 context 值。新测试的替代方案单元测试 env 读取函数、重构代码接受参数、或使用子进程隔离。测试文件排除测试文件被排除如 AI 配置文件时// 测试文件 NOT 被渲染 testQuartoCmd( render, [projectDir], [ noErrors, fileExists(join(outputDir, expected.html)), // 应存在 pathDoNotExists(join(outputDir, excluded.html)), // 不应存在 ], // ... );先在没有修复时运行测试确认它失败再验证修复后通过。Smoke-All 测试YAML 内嵌Smoke-all 测试通过_quarto.tests元数据把测试规格直接嵌入.qmd文件tests/smoke/smoke-all.test.ts完整文档见.claude/rules/testing/smoke-all-tests.md。YAML 正则转义关键规则核心规则在 YAML 单引号字符串中\(与\\(等价——都产生正则中的字面量\(。常见错误过度转义为\\(会产生\\(两个反斜杠导致正则失败。_quarto: tests: pdf: ensureLatexFileRegexMatches: # 正确——YAML 单引号中单个反斜杠 - [\(1\), \\circled\{1\}, Variable assignment] - [\\CommentTok, \\begin\{Shaded\}] # 错误——过度转义正则中产生 \\( - [\\(1\\), \\\\circled\\{1\\}]YAML 转义速查表要在文件中匹配单引号...双引号...\(\(\\(\begin{\\begin\{\\\\begin\\{\\字面量\\\\\\\\\\\\[正则\[\\[建议使用单引号字符串——它更简单只有本身需要转义写成。探测足够的键以暴露深层合并 bug如果优先级测试的模板只读取被覆盖的那一个键那么在深层合并deep-mergebug 下测试可能通过被丢弃的兄弟键永远不会被解析但没有断言会发现。示例用户提供的variables.quarto.language.crossref-ch-prefix: Bouquin与 Quarto 内置的format.language表在variables.quarto.language下合并。在浅层展开{ ...a, ...b }下b.language会替换整个本地化映射——所有其他$quarto.language.key$的解析静默返回空。只读取$quarto.language.crossref-ch-prefix$的模板仍断言 Bouquin因此回归测试通过了。修复方式是让模板至少探测一个未被覆盖的兄弟键。具体地回归守卫 tests/docs/smoke-all/markdown/lang-fr-user-override-deep-merge.qmd 使用模板$quarto.language.crossref-ch-prefix$|$quarto.language.toc-title-document$并断言完整字符串^Bouquin\|Table des matières\s*$。修复前输出是Bouquin|修复后是Bouquin|Table des matières。启发式规则为任意两个结构化配置树的合并编写优先级 smoke 测试时确保断言至少覆盖一条用户没有覆盖的路径。否则测试只证明被覆盖的值生效了——而没有证明其余部分存活。赞分享开发工具文档【免费下载链接】quarto-cliOpen-source scientific and technical publishing system built on Pandoc.项目地址https://gitcode.com/gh_mirrors/qu/quarto-cli点击查看免费下载相关推荐mockery 的 include-auto-generated 配置让 mock 生成器正确处理自动生成源码mockery 的 include auto generated 配置让 mock 生成器正确处理自动生成源码 导读 Go 生态中存在大量由代码生成器产出的源开发工具文档Quarto CLI 的 TypeScript 测试体系Smoke 与 Unit 测试编写实战指南Quarto CLI 的 TypeScript 测试体系Smoke 与 Unit 测试编写实战指南 Quarto 是一个基于 Pandoc 的开源科学出版系统开发工具文档抖音批量下载工具教程从单个视频到整站存档的完整上手指南抖音批量下载工具教程从单个视频到整站存档的完整上手指南 douyin downloader 是一个开源免费的抖音批量下载工具基于 Python 编写核心能CLI开发工具上一篇一文搞外文视频的中文字幕PotPlayer 字幕翻译免费配置完整指南下一篇League Director 快速上手指南把 LOL 回放剪成电影级运镜视频只需这 6 步创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
