slang-coverage-html 视觉一致性清单解读从 genhtml 到零依赖静态 HTML 覆盖报告【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang本文面向 Slang 生态的覆盖率工作流slang-coverage-html是一个纯 Python 3 标准库实现的静态 HTML 覆盖率渲染器它把 LCOV.info/.lcov或llvm-cov export -formatjson输出渲染为完全自包含的 HTML 报告目录作为genhtml的零安装替代。仓库中的 tools/coverage-html/tests/fixtures/VISUAL-PARITY.md 是该渲染器的视觉一致性验收清单Visual-parity checklist定义了输出 HTML 与genhtml在视觉上的对齐标准、必须复刻的页面结构与 CSS 类名、明确的不匹配范围以及可执行的验证步骤。读完本文你将掌握这套渲染器输出规范的每一处细节并能依据该清单亲手校验生成结果。一、这份清单的定位匹配外观不匹配功能全集VISUAL-PARITY.md开篇就划定了范围它是HTML 生成步骤的验收标准Acceptance criteria目标是复刻genhtml输出存放在tests/fixtures/genhtml-reference/目录中的视觉观感而不是实现 genhtml 的每一个功能。Phase 1 明确列出的**非目标non-goals**包括分支 / 函数视图branch/function view测试用例详情test-case detailTLA 基线差异视图TLA/baseline diff额外的排序变体页面extra sort-variant pages。也就是说这一阶段的验收只关心看起来像 genhtml功能层面的深度留到后续 phase详见 tools/coverage-html/README.md 的 Phase matrixbranch/function 摘要已在 phase 2 上线。需要镜像的四个参考文件均在tests/fixtures/genhtml-reference/下参考文件对应页面genhtml-reference/index.html顶层目录汇总页genhtml-reference/shader-coverage-demo/index.html单目录内的文件汇总页genhtml-reference/shader-coverage-demo/physics.slang.gcov.html单文件源码标注视图genhtml-reference/gcov.css类名来源phase 1 决策将精简子集内联到每个页面二、三级页面层级与 phase 1 的扁平化决策当 LCOV 跨多个目录时genhtml 会生成三级结构顶层index.html—— 每行是一个目录每目录一个index.html—— 每行是该目录下的文件每个文件一个name.gcov.html—— 带标注的源码视图。VISUAL-PARITY.md给出的 phase 1 决策是把第 1、2 级折叠进单个index.html除非 LCOV 本身包含多个目录。理由很实际绝大多数输入shader demo、shader-coverage-to-lcov 的输出的文件都来自同一个目录只有当检测到多于一个目录时才回退到 genhtml 的按目录分组布局。文档也标注这是可延后的打磨Deferrable polish——先做两级只有必要时再嵌套。从实现看折叠逻辑确实体现在渲染器中slang-coverage-html.py 的_index_dir_tree()约 L384-L410把所有FileRecord按其显示路径的父目录分组render_index()L649-L746对目录生成dirHeader行使用coverDirectory类 #b8d0ff背景对文件生成fileSummary行并用_indent_style()L431-L434按目录深度增加左内边距让树形结构在纯静态 HTML 中也能直观呈现。三、所有页面的公共 ChromeCommon chrome清单对每一页都要求的统一头部/尾部元素如下上下标尺table classruler横向色条位于头部块的上方与下方。genhtml 用的是 3 像素蓝色图片glass.pngphase 1 改用border-top样式、不引入图片。标题栏td classtitleLCOV - code coverage report/td。头部汇总表使用 genhtml 的类名体系headerItem/headerValue—— 标签 / 值对headerCovTableHead—— 列头Coverage、Total、HitheaderCovTableEntry—— 数值单元格覆盖率单元格按阈值分档headerCovTableEntryHi≥90%绿色#a7fc9dheaderCovTableEntryMed≥75%琥珀色#ffea20headerCovTableEntryLo75%红色#ff0000阈值采用 genhtml 默认的90 / 75文档注明如果有人要求以后再做成 CLI 可覆盖。头部展示字段Current view:面包屑子页面带返回链接、Test:取自输入文件名、Test Date:UTC 时间戳、Lines:rate total hit、Functions:phase 2 先照 genhtml 现状输出-/0/0。页脚单行表格td classversionInfoGenerated by: slang-coverage-html/td镜像 genhtml 的versionInfo模式但署上自己的名字。对照 genhtml-reference/index.html 的真实输出可以逐行看到这套类名headerItem/headerValue组成的Current view:与Test:行、headerCovTableHead三列头、以及84.6 %headerCovTableEntryMed这样的分档数值。这些类名同时是gcov.css中定义的样式见 gcov.css 的td.headerCovTableEntryHi/Med/Lo规则分别对应#a7fc9d、#ffea20、#ff0000背景。值得注意的是实现层面的演进slang-coverage-html.py的_render_page_header()L145-L229虽然保留了headerItem/headerValue与ruler类但把 genhtml 的转置汇总表改成了metricCards弹性卡片布局每个指标Lines / Functions / Branches / Regions一张卡片含标签、百分比、迷你进度条和hit / total计数style.css 中的标尺也改用 Slang 品牌青--slang-teal: #105f65而非 genhtml 的#6688d4。测试 test_renderer.py约 L481-L495明确断言输出 CSS 使用 Slang 青/橙 token、且不再包含#6688d4这一旧的 genhtml 标尺/表头蓝。这意味着类名体系向后兼容 genhtml 生态但视觉风格已品牌化。四、Index 页面index.html结构规范清单对目录/文件汇总表的要求非常具体centertable width80%布局配宽度型列分隔符遵循 genhtml 的40/15/15/15/15模式表头td classtableHead rowspan2File/tdtd colspan4Line Coverage/td随后是子行Rate | Total | Hit每一行的单元格构成td classcoverFile内含a href...filename/a目录行改用coverDirectory类 #b8d0ff背景td classcoverBar覆盖率条由两个定高span构成不用图片。外层coverBarOutline背景黑色#000000内层按档位取琥珀 / 祖母绿 / 红宝石色宽度与覆盖率百分比成比例td classcoverPerHi/Med/Lo分档颜色的比率单元格两个td classcoverNumDflt分别放 Total 与 Hit。不做排序变体不生成index-sort-l.html、index-sort-f.html按文件名朴素渲染客户端排序推迟到 phase 2。在genhtml-reference/index.html中可以看到 84.6% 的琥珀色条amber.png宽 85px snow.png宽 15px、coverPerMed单元格和coverNumDflt的 Total/Hit26 / 22。而实现侧 slang-coverage-html.py 用_render_rate_bar()L297-L307生成两个spancoverBarFill内联background-color 像素宽度与coverBarRest填充宽度由BAR_PIXEL_WIDTH 100L62按百分比线性计算_rate_cell()L286-L294则用 HSL 渐变背景色代替分档纯色其色相由GRADIENT_HUE_WATERMARKSL71-L76定义的分段线性插值决定0% → 红色、70% → 红橙、80% → 黄绿、100% → 绿色。这样低于 70% 一律红、80% 以上才进入绿区的视觉效果与 genhtml 的 90/75 分档在观感上等价但更连续。五、单文件源码视图name.html这是最精细的部分清单逐条规定了源码标注的渲染规则复用头部 chrome面包屑带返回 index 的链接源码区前固定输出一行列头pre classsourceHeading Line data Source code/pre即双列 gutter行号、命中数加源码源码块包在pre classsource中每个物理源文件行渲染为span idL{n}span classlineNum{n:8}/span{GUTTER}{LINE}/span其中lineNumspan 是行号 gutter背景#efe383已覆盖行span classtlaGNC{hits:12} : {code}/span类tlaGNC背景#CAD7FE。GNC Gained New Coverage是未提供基线时 genhtml 的默认 TLA 状态未覆盖行span classtlaUNC{0:12} : {code}/span类tlaUNC背景#FF6230不可执行行lineNum与\n之间的纯文本 —— 14 个空格填充后接: {code}。源码中的、、必须做 HTML 转义精确保留缩进genhtml 的做法是把 tab 按 tab size 8 转成空格保留原始 tab 也完全可以pre中天然成立源码解析失败时的降级如果源文件无法定位源码块退化为(line, hits)元组表格顶部加source unavailable横幅其余 chrome 保持不变。对照genhtml-reference/shader-coverage-demo/physics.slang.gcov.html的真实输出第 17 行688 : return velocity ...使用tlaGNC蓝底命中 688 次第 45-46 行tlaUNC红底显示0非可执行行如第 1-16 行的注释与声明则只有lineNum加 14 空格填充。实现侧 slang-coverage-html.py 的_render_source_view()L1033-L1110完整复刻了这套模板lineNum右对齐 8 位、命中数右对齐 12 位、html.escape()转义、非可执行行 14 空格占位phase 2b 之后若文件带分支记录还会在命中数与源码之间插入 10 字符宽的BRANCH_COL_WIDTHL83分支列。_render_placeholder_view()L1113-L1141则实现了source unavailable横幅 (line, hits) 表格的降级视图并在横幅中提示用--source-root重新解析。六、CSS 策略单页内联精简子集清单规定的样式策略是每个页面只内联一个style块且只包含实际用到的类。预估约 30 个选择器而 genhtml 在剥离 TLA 状态、分支、MC/DC 与测试属主样式后约有 300 个。动机有四条自包含需求 M2——双击index.html即可查看无需服务器无外部引用——不链接gcov.css不引入图片资源amber/emerald/snow/glass 等 png 全部用 CSSbackground-color替代页面更小、加载更快类名保持一致——凡是能对 genhtml 输出做 grep 的工具通常也能继续 grep 我们的输出。实现上slang-coverage-html.py 在模块加载时直接读取同目录的 style.css 全文L95INLINE_CSS ...read_text(...)由_render_page_header()把它嵌入每个页面的head中script.js 也以同样方式内联L232-L233用于测量吸顶 chrome 高度和目录/函数行的展开切换。七、明确不匹配的清单What were explicitly NOT matching这份清单的价值不仅在于要做什么还在于明确不做什么防止实现时不知不觉被 genhtml 的丰富功能带偏genhtml 元素phase 1 处理amber.png/snow.png条状图替换为两个 CSSspanglass.png3px 分隔符替换为 CSSborder-topupdown.png排序图标省略无排序变体gcov.css外部链接内联排序变体页index-sort-l.html、index-sort-f.html省略coverLegend*图例条省略延后打磨分支 / 函数列省略phase 2Test-owner / TLA 基线状态除tlaGNC/tlaUNC外省略逐测试钻取testName、testPer、testNum省略phase 3顺带一提README.md 的 Phase matrix 显示后续演进phase 2 已上线分支/函数摘要列phase 2b 加入逐行内联分支列branchAll绿、branchPart琥珀、branchNone红 逐分支 tooltipphase 2c 把函数表折叠进 index 的可展开行phase 2d 支持 JSON 输入与 Region 列phase 3按TN:逐测试钻取目前以 max-across 聚合方式实现。八、调色板逐字取自gcov.css清单附上了完整调色板对照表是渲染实现中颜色语义的权威来源用途颜色类高覆盖率背景#a7fc9dcoverPerHi、tlaGNCheader 模式中覆盖率背景#ffea20coverPerMed低覆盖率背景#ff0000coverPerLo已覆盖行背景#CAD7FEtlaGNC未覆盖行背景#FF6230tlaUNC行号 gutter#efe383lineNum数值行默认背景#dae7fecoverNumDflt文件名链接色#284fa8coverFile a标尺#6688d4ruler表头#6688d4tableHead可以在 gcov.css 中逐条核实如td.coverPerHi的#a7fc9d、td.coverDirectory的#b8d0ff、td.tableHead的#6688d4等。九、验证流程渲染器实现后如何验收清单最后给出了完整的手动验证步骤基于真实数据 fixturedemo-cpu.info它是运行shader-coverage-demo --modedispatch --backendcpu生成的真实 LCOV见 README.md 的 fixture 更新说明用渲染器处理demo-cpu.info输出到/tmp/slang-coverage-html-out/并排打开/tmp/slang-coverage-html-out/index.html与genhtml-reference/index.html逐项比对总体覆盖率84.6%一致文件列表physics.slang、simulate.slang齐全单文件覆盖率85.7%、83.3%一致每个比率的颜色档位一致都应为 Med/琥珀色打开每个单文件页并比对physics.slang第 17 行688 次命中已覆盖蓝physics.slang第 45-46 行0 次命中未覆盖红gutter 行号与源文件一致wc -c对比参考.html与我们的输出预期我们的更小无图片标签、CSS 内联2 倍以内可接受若大 10 倍则视为需要调查的回归。这些预期数值都能在仓库中找到直接证据genhtml-reference/index.html顶部即84.6 %/ 26 / 22genhtml-reference/shader-coverage-demo/index.html中physics.slang为85.7 %14/12、simulate.slang为83.3 %12/10physics.slang.gcov.html中 L17 的tlaGNC688 命中与 L45-L46 的tlaUNC0 命中清晰可见。十、fixture 与测试的维护方式验收清单配套的参考输出是可以再生成的。README.md给出了两条维护命令# 重新生成 demo fixturedemo 变化后 cmake --build --preset debug --target shader-coverage-demo cd examples/shader-coverage-demo ./../../build/Debug/bin/shader-coverage-demo --modedispatch --backendcpu cp coverage.lcov ../../tools/coverage-html/tests/fixtures/demo-cpu.info # 重新生成 genhtml 视觉目标genhtml 有实质性变化后 cd examples/shader-coverage-demo genhtml $(git rev-parse --show-toplevel)/tools/coverage-html/tests/fixtures/demo-cpu.info \ -o $(git rev-parse --show-toplevel)/tools/coverage-html/tests/fixtures/genhtml-reference/运行全部测试python3 -m unittest discover -s tools/coverage-html/tests -v测试套件覆盖范围包括 LCOV 解析、llvm-cov report文本解析与 auth-summary 覆盖、llvm-cov export -formatjson解析、源码解析与降级、过滤规则、分档阈值、逐行分支单元格渲染、phase-1 回归检查对照真实数据的 phase-2 fixture等。结语VISUAL-PARITY.md是一份少见的视觉验收规格它把和 genhtml 长得像这件事拆解成了可测试、可逐行核对的工程规范——页面层级、类名体系、阈值分档、颜色语义、明确的排除范围以及带具体数字的验收步骤。对 Slang 生态而言它保证了 shader coverage 报告与编译器 C 覆盖率报告在跨平台 CI 上呈现一致、可 grep、零安装依赖对维护者而言它让视觉一致性不再是主观审美而是有 fixture、有测试、可再生成的客观标准。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考