Typst Test Helper用 VS Code 扩展让 Typst 测试套件“一键运行、比对与更新”【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typstTypst 的集成测试由tests/目录下的测试运行器驱动而tools/test-helper是一个小型 VS Code 扩展它把“运行测试、查看输出与参考图、更新参考输出”这些高频操作内联到编辑器中每个测试名的上方会出现 View / Run / Save / Terminal 四个 Code Lens 按钮点击即可在侧边面板中并排查看实时输出与参考结果。读完本文你将理解该扩展的四个按钮各自背后的命令与源码实现、它如何调用cargo test驱动 Typst 测试运行器以及完整的构建与安装步骤可以在 Typst 仓库中直接上手用它来调试和更新测试参考输出。扩展的定位为 Typst 测试套件打造的开发助手按照 README 的描述Test Helper 是“帮助管理 Typst 测试套件的小型 VS Code 扩展”。它的核心工作方式是对工作区中tests目录下的所有.typ文件在每个测试名称所在行的上方注入一组 Code Lens 按钮。从 package.json 可以确认其身份扩展名为typst-test-helper发布者为typst描述是 “Helps to run, compare and update Typst tests.”入口文件为./dist/extension.js即src/extension.ts经tsc编译后的产物声明的activationEvents为workspaceContains:tests/suite/playground.typ—— 也就是说只有当工作区是 Typst 仓库本身存在 playground.typ 这个哨兵文件时扩展才会被激活。这一设计保证了对普通用户无侵入只有打开 Typst 源码仓库的开发者才会看到这些测试辅助按钮。四个 Code Lens 按钮View、Run、Save、TerminalREADME 中列出的四个按钮及其行为如下按钮行为View在侧边打开该测试的输出与参考图像Run运行测试并在侧边显示结果Save以--update参数运行测试保存参考输出Terminal在集成终端中运行该测试这些按钮并非手写配置而是由 extension.ts 中的lens()方法动态生成的。它对文档逐行扫描用正则表达式识别测试头const re /^--- ([\d\w-])(( [\d\w-\(\)])*) ---$/;这正对应 Typst 测试套件--- {name} {attr} ---的测试语法如 array.typ 中的--- array-basic-syntax paged ---。正则第一组捕获测试名name第二组捕获测试属性如paged、html、eval随后为每一行测试名生成四个CodeLens分别绑定命令typst-test-helper.viewFromLensViewtypst-test-helper.runFromLensRuntypst-test-helper.saveFromLensSavetypst-test-helper.runInTerminalTerminal从源码结构看各命令的分工非常清晰见 extension.tsrunFromLens与saveFromLens都是先调用viewFromLens打开或复用预览面板再触发runFromPreview/saveFromPreviewrunInTerminal则直接在集成终端中发送一条命令cargo test --workspace --test tests -- --exact 测试名这与 tests/README.md 中介绍的cargo testit别名是等价的——仓库根目录的 .cargo/config.toml 定义了testit run --quiet --packagetest-wrapper --而 test wrapper 最终就是运行cargo test --workspace --test tests这条集成测试入口。因此 Terminal 按钮相当于把“精确运行单个测试”的 CLI 操作搬进了编辑器。侧边预览面板输出与参考并排比对点击 View / Run / Save 后扩展会通过vscode.window.createWebviewPanel创建一个标题为测试名的 Webview 面板列于编辑器旁边ViewColumn.Beside。面板内容不是静态截图而是一份动态生成的 HTML 页面其展示内容由测试属性决定见 extension.ts 的getWebviewContent测试带paged属性时并排显示renderPNG 位图与svg两个格式的输出图与参考图测试带html属性时显示 HTML 输出的着色源码用 shiki 高亮与iframe实时预览测试带pdftags属性时显示 PDF 标签树的 YAML 格式输出若刚刚执行过 Run则页面底部还会附上完整的 Standard output / Standard error。每个格式都有 “Output” 与 “Reference” 两列分别对应当前运行产生的实时输出与仓库中提交的参考文件。文件定位逻辑在getUri函数中extension.ts常规格式实时输出位于tests/store/{format}/{name}.{ext}参考位于tests/ref/{format}/{name}.{ext}哈希参考格式svg、pdf参考不存文件本体只把哈希记录在tests/ref/{format}/hashes.txt中例如 pdf 哈希实时文件则按{hash}_{name}.{ext}存放于tests/store/by-hash/下。这与 Typst 测试运行器的参考策略完全一致tests/src/run.rs 中区分了FileOutputType文件参考如 render、html与HashOutputType哈希参考如 svg、pdf、pdftags、bundle后者通过稳定哈希比对来避免仓库膨胀。预览面板读取hashes.txt的方式readHashedRefs按空格拆分hash name两列也与 tests/src/tests.rs 中的HashedRefs解析保持一致。面板右上角还有若干工具栏按钮。README 提到的三个是Refresh重新加载面板内容以反映图像变化对应命令typst-test-helper.refreshFromPreviewRun重新运行测试并显示结果typst-test-helper.runFromPreviewSave以--update运行测试以保存参考输出typst-test-helper.saveFromPreview。在 package.json 的contributes.menus[editor/title]中还能看到另外两个 README 未提及的按钮放大 / 缩小分辨率typst-test-helper.increaseResolution/decreaseResolution仅在预览面板激活时显示。从 extension.ts 的adjustResolution可以看到缩放系数在 1.0 到 8.0 之间取整调整后会自动重新执行一次测试Webview 内图片上右键可执行Copy file pathtypst-test-helper.copyFilePathFromPreviewContext把图像的本地路径写入剪贴板便于在 diff 工具中定位文件。此外扩展在右下角状态栏挂了一个 “Running” 旋转指示器因为cargo test会先重建相关 crate测试启动可能有较长的编译等待点击状态栏条目会弹出一个进度通知持续展示测试运行器 stderr 的最新一行截断到 50 字符缓解等待焦虑见 extension.ts 的createStatusItem与showTestProgress。底层执行链扩展如何驱动 cargo 测试运行器README 中 “Run: 运行测试” 这一句背后是一条完整的进程调用链。核心实现在runCargoTestextension.tsconst proc cp.spawn(cargo, [ test, --manifest-path, ${dir}/Cargo.toml, --workspace, --test, tests, --, ...(this.scale ! 1.0 ? [--scale, ${this.scale}] : []), --exact, --verbose, name, ...(update ? [--update] : []), ]);拆开看--manifest-path 仓库根/Cargo.toml强制使用工作区根目录的 Cargo.toml保证无论从哪个子目录激活扩展都在正确的 workspace 上执行--workspace --test tests运行集成测试目标即 tests/src/tests.rs 中main定义的测试运行器--exact name按测试名精确匹配单个测试对应 README 中 “Running a test with the exact test name” 的用法--scale N仅在面板缩放不为 1 时追加让 render 输出按指定缩放渲染配合预览面板的放大功能--update仅 Save 按钮追加。测试运行器收到该标志后会把不匹配的参考输出render PNG、html 文件、svg/pdf/pdftags/html 的哈希表重新写入磁盘——这正是 run.rs 中check_file_ref/check_hash_ref里ARGS.update分支的行为同时 tests/README.md 也提到更新参考时会自动生成压缩后的参考图像以控制体积。进程运行期间Run/Save 按钮会通过setContext被禁用typst-test-helper.runButtonEnabled防止重复触发进程退出close事件后再重新启用按钮并刷新 Webview把本次 stdout/stderr 一并渲染进面板。值得注意的是Save 按钮并非把参考图存到任意位置--update最终写回的仍是仓库约定的参考位置tests/ref/{format}/或tests/ref/{format}/hashes.txt这与 CLI 侧cargo testit --exact name --update的效果完全相同只是省去了手动敲命令。安装从源码构建并在 VS Code 中加载README 给出的安装流程是扩展需要由 VS Code 内建的 Node 引擎运行因此必须先本地构建。第一步进入tools/test-helper目录安装依赖并构建npm install # 安装依赖 npm run build # 从源码构建扩展其中npm run build实际执行的是 package.json 中定义的tsc -p ./即按 tsconfig.json 把src/下 TypeScript 代码目标 ES2022、nodenext模块解析、开启strict编译到dist/。构建产物即 package.json 中声明的入口./dist/extension.js。第二步通过 VS Code 的 UI 以“从位置安装”的方式加载本地目录打开命令面板View Command Palette或按Cmd/CtrlP选择命令 “Developer: Install Extension from Location”在文件选择对话框中选中tools/test-helper目录。VS Code 会把该扩展的路径登记到~/.vscode/extensions/extensions.jsonWindows 上为%USERPROFILE%\.vscode\extensions\extensions.json。由于指向的是仓库内目录后续git pull更新代码后重新npm run build即可让扩展保持最新。在 Typst 仓库中的典型工作流把扩展放到 Typst 测试体系里一个典型的参考输出更新流程是修改crates/中的排版或渲染逻辑或修复某个 bug在tests/suite/中找到相关测试文件点击测试名上方的Run查看新输出与参考图的差异面板中并排展示图像以image-rendering: pixelated显示便于逐像素检查确认差异是预期变更后点击Save等价于cargo testit --exact name --update让运行器把参考输出写回tests/ref/若需要更精细地复现或查看完整日志点击Terminal在集成终端获得一条可直接编辑的cargo test ... --exact name命令。需要说明的适用前提该扩展依赖 Typst 仓库自身的测试布局tests/suite/playground.typ哨兵、tests/store、tests/ref目录约定且运行测试要求本机具备 Rust 工具链与已安装的依赖npm install的产物在本地。参考输出的具体格式语义paged、html、pdftags等属性文件参考与哈希参考的区别建议在 tests/README.md 中对照阅读。小结Test Helper 把 Typst 测试运行器的三项核心操作——运行cargo test --workspace --test tests -- --exact、比对tests/store实时输出对tests/ref参考、更新--update——封装成编辑器内的一行按钮并额外提供了缩放分辨率、图片路径复制、运行进度提示等细节能力。它的实现约 700 行 TypeScript与 Typst 测试运行器的参考存储结构文件参考 哈希参考、by-hash软链接严格对齐是理解 tests/ 测试体系如何落地到日常开发的一个很好的切入口。核心文件索引功能说明README扩展实现extension.ts扩展清单命令、菜单、激活事件package.json测试运行器入口与--update逻辑tests.rs、run.rs测试套件文档阶段、参考策略、更新参考tests/README.md【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Typst Test Helper：用 VS Code 扩展让 Typst 测试套件“一键运行、比对与更新”
Typst Test Helper用 VS Code 扩展让 Typst 测试套件“一键运行、比对与更新”【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typstTypst 的集成测试由tests/目录下的测试运行器驱动而tools/test-helper是一个小型 VS Code 扩展它把“运行测试、查看输出与参考图、更新参考输出”这些高频操作内联到编辑器中每个测试名的上方会出现 View / Run / Save / Terminal 四个 Code Lens 按钮点击即可在侧边面板中并排查看实时输出与参考结果。读完本文你将理解该扩展的四个按钮各自背后的命令与源码实现、它如何调用cargo test驱动 Typst 测试运行器以及完整的构建与安装步骤可以在 Typst 仓库中直接上手用它来调试和更新测试参考输出。扩展的定位为 Typst 测试套件打造的开发助手按照 README 的描述Test Helper 是“帮助管理 Typst 测试套件的小型 VS Code 扩展”。它的核心工作方式是对工作区中tests目录下的所有.typ文件在每个测试名称所在行的上方注入一组 Code Lens 按钮。从 package.json 可以确认其身份扩展名为typst-test-helper发布者为typst描述是 “Helps to run, compare and update Typst tests.”入口文件为./dist/extension.js即src/extension.ts经tsc编译后的产物声明的activationEvents为workspaceContains:tests/suite/playground.typ—— 也就是说只有当工作区是 Typst 仓库本身存在 playground.typ 这个哨兵文件时扩展才会被激活。这一设计保证了对普通用户无侵入只有打开 Typst 源码仓库的开发者才会看到这些测试辅助按钮。四个 Code Lens 按钮View、Run、Save、TerminalREADME 中列出的四个按钮及其行为如下按钮行为View在侧边打开该测试的输出与参考图像Run运行测试并在侧边显示结果Save以--update参数运行测试保存参考输出Terminal在集成终端中运行该测试这些按钮并非手写配置而是由 extension.ts 中的lens()方法动态生成的。它对文档逐行扫描用正则表达式识别测试头const re /^--- ([\d\w-])(( [\d\w-\(\)])*) ---$/;这正对应 Typst 测试套件--- {name} {attr} ---的测试语法如 array.typ 中的--- array-basic-syntax paged ---。正则第一组捕获测试名name第二组捕获测试属性如paged、html、eval随后为每一行测试名生成四个CodeLens分别绑定命令typst-test-helper.viewFromLensViewtypst-test-helper.runFromLensRuntypst-test-helper.saveFromLensSavetypst-test-helper.runInTerminalTerminal从源码结构看各命令的分工非常清晰见 extension.tsrunFromLens与saveFromLens都是先调用viewFromLens打开或复用预览面板再触发runFromPreview/saveFromPreviewrunInTerminal则直接在集成终端中发送一条命令cargo test --workspace --test tests -- --exact 测试名这与 tests/README.md 中介绍的cargo testit别名是等价的——仓库根目录的 .cargo/config.toml 定义了testit run --quiet --packagetest-wrapper --而 test wrapper 最终就是运行cargo test --workspace --test tests这条集成测试入口。因此 Terminal 按钮相当于把“精确运行单个测试”的 CLI 操作搬进了编辑器。侧边预览面板输出与参考并排比对点击 View / Run / Save 后扩展会通过vscode.window.createWebviewPanel创建一个标题为测试名的 Webview 面板列于编辑器旁边ViewColumn.Beside。面板内容不是静态截图而是一份动态生成的 HTML 页面其展示内容由测试属性决定见 extension.ts 的getWebviewContent测试带paged属性时并排显示renderPNG 位图与svg两个格式的输出图与参考图测试带html属性时显示 HTML 输出的着色源码用 shiki 高亮与iframe实时预览测试带pdftags属性时显示 PDF 标签树的 YAML 格式输出若刚刚执行过 Run则页面底部还会附上完整的 Standard output / Standard error。每个格式都有 “Output” 与 “Reference” 两列分别对应当前运行产生的实时输出与仓库中提交的参考文件。文件定位逻辑在getUri函数中extension.ts常规格式实时输出位于tests/store/{format}/{name}.{ext}参考位于tests/ref/{format}/{name}.{ext}哈希参考格式svg、pdf参考不存文件本体只把哈希记录在tests/ref/{format}/hashes.txt中例如 pdf 哈希实时文件则按{hash}_{name}.{ext}存放于tests/store/by-hash/下。这与 Typst 测试运行器的参考策略完全一致tests/src/run.rs 中区分了FileOutputType文件参考如 render、html与HashOutputType哈希参考如 svg、pdf、pdftags、bundle后者通过稳定哈希比对来避免仓库膨胀。预览面板读取hashes.txt的方式readHashedRefs按空格拆分hash name两列也与 tests/src/tests.rs 中的HashedRefs解析保持一致。面板右上角还有若干工具栏按钮。README 提到的三个是Refresh重新加载面板内容以反映图像变化对应命令typst-test-helper.refreshFromPreviewRun重新运行测试并显示结果typst-test-helper.runFromPreviewSave以--update运行测试以保存参考输出typst-test-helper.saveFromPreview。在 package.json 的contributes.menus[editor/title]中还能看到另外两个 README 未提及的按钮放大 / 缩小分辨率typst-test-helper.increaseResolution/decreaseResolution仅在预览面板激活时显示。从 extension.ts 的adjustResolution可以看到缩放系数在 1.0 到 8.0 之间取整调整后会自动重新执行一次测试Webview 内图片上右键可执行Copy file pathtypst-test-helper.copyFilePathFromPreviewContext把图像的本地路径写入剪贴板便于在 diff 工具中定位文件。此外扩展在右下角状态栏挂了一个 “Running” 旋转指示器因为cargo test会先重建相关 crate测试启动可能有较长的编译等待点击状态栏条目会弹出一个进度通知持续展示测试运行器 stderr 的最新一行截断到 50 字符缓解等待焦虑见 extension.ts 的createStatusItem与showTestProgress。底层执行链扩展如何驱动 cargo 测试运行器README 中 “Run: 运行测试” 这一句背后是一条完整的进程调用链。核心实现在runCargoTestextension.tsconst proc cp.spawn(cargo, [ test, --manifest-path, ${dir}/Cargo.toml, --workspace, --test, tests, --, ...(this.scale ! 1.0 ? [--scale, ${this.scale}] : []), --exact, --verbose, name, ...(update ? [--update] : []), ]);拆开看--manifest-path 仓库根/Cargo.toml强制使用工作区根目录的 Cargo.toml保证无论从哪个子目录激活扩展都在正确的 workspace 上执行--workspace --test tests运行集成测试目标即 tests/src/tests.rs 中main定义的测试运行器--exact name按测试名精确匹配单个测试对应 README 中 “Running a test with the exact test name” 的用法--scale N仅在面板缩放不为 1 时追加让 render 输出按指定缩放渲染配合预览面板的放大功能--update仅 Save 按钮追加。测试运行器收到该标志后会把不匹配的参考输出render PNG、html 文件、svg/pdf/pdftags/html 的哈希表重新写入磁盘——这正是 run.rs 中check_file_ref/check_hash_ref里ARGS.update分支的行为同时 tests/README.md 也提到更新参考时会自动生成压缩后的参考图像以控制体积。进程运行期间Run/Save 按钮会通过setContext被禁用typst-test-helper.runButtonEnabled防止重复触发进程退出close事件后再重新启用按钮并刷新 Webview把本次 stdout/stderr 一并渲染进面板。值得注意的是Save 按钮并非把参考图存到任意位置--update最终写回的仍是仓库约定的参考位置tests/ref/{format}/或tests/ref/{format}/hashes.txt这与 CLI 侧cargo testit --exact name --update的效果完全相同只是省去了手动敲命令。安装从源码构建并在 VS Code 中加载README 给出的安装流程是扩展需要由 VS Code 内建的 Node 引擎运行因此必须先本地构建。第一步进入tools/test-helper目录安装依赖并构建npm install # 安装依赖 npm run build # 从源码构建扩展其中npm run build实际执行的是 package.json 中定义的tsc -p ./即按 tsconfig.json 把src/下 TypeScript 代码目标 ES2022、nodenext模块解析、开启strict编译到dist/。构建产物即 package.json 中声明的入口./dist/extension.js。第二步通过 VS Code 的 UI 以“从位置安装”的方式加载本地目录打开命令面板View Command Palette或按Cmd/CtrlP选择命令 “Developer: Install Extension from Location”在文件选择对话框中选中tools/test-helper目录。VS Code 会把该扩展的路径登记到~/.vscode/extensions/extensions.jsonWindows 上为%USERPROFILE%\.vscode\extensions\extensions.json。由于指向的是仓库内目录后续git pull更新代码后重新npm run build即可让扩展保持最新。在 Typst 仓库中的典型工作流把扩展放到 Typst 测试体系里一个典型的参考输出更新流程是修改crates/中的排版或渲染逻辑或修复某个 bug在tests/suite/中找到相关测试文件点击测试名上方的Run查看新输出与参考图的差异面板中并排展示图像以image-rendering: pixelated显示便于逐像素检查确认差异是预期变更后点击Save等价于cargo testit --exact name --update让运行器把参考输出写回tests/ref/若需要更精细地复现或查看完整日志点击Terminal在集成终端获得一条可直接编辑的cargo test ... --exact name命令。需要说明的适用前提该扩展依赖 Typst 仓库自身的测试布局tests/suite/playground.typ哨兵、tests/store、tests/ref目录约定且运行测试要求本机具备 Rust 工具链与已安装的依赖npm install的产物在本地。参考输出的具体格式语义paged、html、pdftags等属性文件参考与哈希参考的区别建议在 tests/README.md 中对照阅读。小结Test Helper 把 Typst 测试运行器的三项核心操作——运行cargo test --workspace --test tests -- --exact、比对tests/store实时输出对tests/ref参考、更新--update——封装成编辑器内的一行按钮并额外提供了缩放分辨率、图片路径复制、运行进度提示等细节能力。它的实现约 700 行 TypeScript与 Typst 测试运行器的参考存储结构文件参考 哈希参考、by-hash软链接严格对齐是理解 tests/ 测试体系如何落地到日常开发的一个很好的切入口。核心文件索引功能说明README扩展实现extension.ts扩展清单命令、菜单、激活事件package.json测试运行器入口与--update逻辑tests.rs、run.rs测试套件文档阶段、参考策略、更新参考tests/README.md【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考