RenderDoc 自动化测试系统完全指南demos 构建、测试运行与用例编写【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址: https://gitcode.com/gh_mirrors/re/renderdoc本指南以 util/test/README.md 为骨架结合仓库内 util/test/run_tests.py、util/test/rdtest、util/test/demos 与 util/test/tests 等源码系统讲解 RenderDoc 图形调试工具的自动化测试体系。你将掌握如何在不同平台构建 demos 测试程序、如何用run_tests.py精确筛选并运行测试、如何理解测试产物与报告以及如何从零添加一个属于自己的渲染回归测试。测试体系总览demos Python 用例的双层架构RenderDoc 的自动化测试不是一个单体程序而是由两层紧密配合的组件构成demos 程序C一个包含大量小而全的 API 用法演示的独立可执行文件。每个 demo 用某一种图形 APID3D11、D3D12、OpenGL、Vulkan完成一件简单的事例如画一个三角形、测试常量缓冲区或验证纹理格式。demos 的源码位于 util/test/demos按 API 分目录组织d3d11/、d3d12/、gl/、vk/其构建脚本是 util/test/demos/CMakeLists.txt。Python 测试用例tests/位于 util/test/tests每个用例通常与一个 demo 一一对应。用例驱动 RenderDoc 的 Python 模块renderdoc与pyrenderdoc打开 demo 产生的捕获文件对回放结果进行断言——例如检查顶点着色器输出、像素拾取值、着色器调试轨迹等。两者通过测试名关联Python 用例类中的demos_test_name属性指向 demos 中的同名 demo例如 tests/Vulkan/VK_Simple_Triangle.py 中的demos_test_name VK_Simple_Triangle。测试运行时框架会调用 demos 程序执行对应 demo 并自动捕获若干帧生成 .rdc 捕获文件交给 Python 用例回放校验。从 util/test/rdtest/runner.py 的get_tests()可以看出测试的收集机制框架扫描所有已加载模块凡是testcase.TestCase的子类且未标记internal的类都会被视为一个测试用例并按慢测试优先、名字排序排列。构建 demos 测试程序大多数测试都依赖 demos 程序因此第一步是把它编译出来。Windows 平台直接打开 util/test/demos/demos.sln实际文件为util/test/demos/demos.vcxproj所在的解决方案用 Visual Studio 编译即可。官方说明没有必须的外部依赖开箱即用。Linux 与 Apple 平台使用 CMake 构建命令如下cmake -Bbuild -Hdemos make -C build在 Linux 上需要安装以下库它们同时也是编译带 GL 支持的 RenderDoc 所需通常你已经装好libX11libxcblibX11-xcb从 util/test/demos/CMakeLists.txt 可以看到Unix 构建会通过target_compile_definitions启用VK_USE_PLATFORM_XCB_KHR并链接-lX11 -lxcb -lX11-xcb。可选的 shaderc 软依赖注意目前存在一个软性外部依赖。如果 demos 程序没有链接 shaderc它会在运行时调用glslc命令把着色器编译为 SPIR-V缺少 shaderc 时依赖运行时着色器编译的部分测试会被自动禁用。目前只有Windows支持链接 shaderc并且是自动的——只要在$VULKAN_SDK环境变量指定的目录下能找到 shaderc 即可。对于 Linux/Appleutil/test/demos/CMakeLists.txt 也保留了探测3rdparty/shaderc/linux64|linux32目录的逻辑若存在libshaderc_combined.a则定义HAVE_SHADERC并链接进去否则回退到运行时调用glslc。Android 平台demos 也支持构建为 Android APK对应 util/test/demos/android 目录。CMake 逻辑要求设置JAVA_HOME、Android SDK 与 NDK 环境变量默认 ABI 为arm64-v8a并通过 util/test/README.md 中描述的--adb-device参数在真机/模拟器上运行测试。让测试能找到 demos 二进制Linux/Apple 上运行测试前需要把demos_x64的构建输出目录加入PATH或者更推荐使用--demos-binary参数直接指定demos_x64的文件路径。在 util/test/run_tests.py 中该参数默认值为空字符串运行时若给出则会被os.path.realpath解析为绝对路径util/test/run_tests.py。运行测试run_tests.py 详解运行测试的命令行入口是 util/test/run_tests.py。注意运行测试所用的 Python 版本必须与构建被测 RenderDoc 时使用的 Python 版本一致Windows 上还必须匹配位数——64 位 RenderDoc 需要 64 位 Python32 位同理。仓库在 Windows 上默认随附 Python 3.6。常用参数参数简写说明--renderdoc-rRenderDoc 原生库所在路径用于修改操作系统库搜索路径。Windows 示例--renderdoc /path/to/renderdoc/x64/Development--pyrenderdoc-prenderdocPython 模块所在路径。Windows 示例--pyrenderdoc /path/to/renderdoc/x64/Development/pymodules--list-l列出全部可用测试后退出--test_include-t用正则表达式筛选要运行的测试只运行匹配的用例省略则运行全部--test_exclude-x用正则表达式排除测试省略则不做排除--in-process-在同一个 Python 进程内运行测试默认每个测试派生子进程主要用于调试--slow-tests-包含标记为可能长时间运行的测试默认排除保证快速回归--data-参考数据目录默认为脚本旁的data/--artifacts-输出产物目录默认为脚本旁的artifacts/--temp-临时工作目录默认为脚本旁的tmp/--data-extra-额外数据目录存放无法提交进仓库的大体积捕获文件默认data_extra/--demos-binary-构建好的 demos 二进制路径--adb-device-指定 ADB 设备运行测试代替本机设置后--demos-binary应指向 demo APK这些参数在 util/test/run_tests.py 中均有对应的 argparse 定义除上表外还支持--parallel N-j并行运行 N 个子进程测试util/test/run_tests.py--test-timeout等待测试输出的超时秒数默认 90util/test/run_tests.py--demos-timeout等待 demos 运行完成的超时--debugger开启调试器模式框架不再捕获异常便于在 IDE 中单步调试测试本身util/test/run_tests.py。Windows 上的典型调用方式python run_tests.py --pyrenderdoc /path/to/renderdoc/x64/Development/pymodules \ --renderdoc /path/to/renderdoc/x64/Development库与模块路径的解析逻辑源码层面--renderdoc与--pyrenderdoc的处理值得注意util/test/run_tests.py两者都既接受文件也接受目录传入文件时会取所在目录。--renderdoc指定后会把目录追加到PATH在 Python 3.8 的 Windows 上还会调用os.add_dll_directory加入 DLL 搜索路径因为 Python 3.8 不再搜索 PATH。若只给了--renderdoc而未给--pyrenderdocWindows 下会默认尝试renderdoc/pymodules其他平台则默认使用renderdoc本身。如果两者都没指定Windows 下还会尝试从仓库默认构建位置x64/Development/pymodules或x64/Release/pymodules自动导入。如果rdtest模块导入失败脚本会在 artifacts 目录生成一个output.log.html并提示用--pyrenderdoc或--renderdoc指定路径后退出util/test/run_tests.py。运行时的内部机制进程隔离默认情况下每个测试在独立子进程中运行util/test/rdtest/runner.py通过--internal_run_test与--internal_thread内部参数重新启动自身执行单个测试这样即使测试崩溃也不会拖垮整个测试运行。超时与崩溃处理主进程持续监控子进程输出超过--test-timeout无输出则杀掉子进程并标记超时返回码非 0/1/100 会被判定为可能崩溃util/test/rdtest/runner.py。测试筛选test_include/test_exclude会被编译为正则表达式逐一匹配测试类名做大小写不敏感过滤util/test/rdtest/runner.py。Vulkan 图层注册运行前会检查是否需要注册 Vulkan 层必要时自动注册Windows 上若需要提权会触发 UAC 提示util/test/rdtest/runner.py。目录清理每次运行开始tmp/与artifacts/都会被彻底清空util/test/rdtest/runner.py所以不要在这两个目录放任何想保留的东西。理解测试产物与报告运行结束后--artifacts指向的目录默认artifacts/保存全部输出主日志文件output.log.html内容大部分是纯文本但内嵌了少量 JavaScript 以便在浏览器中友好展示日志渲染所需的 CSS/JStestresults.css、testresults.js见 util/test/rdtest/testresults.css与所有图片 diff 都会复制到同一目录因此artifacts 目录是自包含的可以直接打包或拷贝到其他机器上用浏览器打开。日志头部会记录被测 RenderDoc 的版本号、Git 提交哈希、平台信息、各 API 驱动版本以及 demos 二进制路径util/test/rdtest/runner.py结尾输出汇总统计total/fail/skip/time若有失败用例会列出名字并以退出码 1 表示存在失败util/test/rdtest/runner.py。添加一个测试从 demo 到 Python 用例编写 demos 示例demos 项目自带辅助库util/test/demos/test_common.h、util/test/demos/test_common.cpp因此最佳实践是复制一个现有 demo 再修改而不是从零开始。官方建议避免uber-demo——一个 demo 只做一件简单的事便于定位问题demo 与 Python 测试通常 1:1 对应例如 util/test/demos/vk/vk_simple_triangle.cpp 对应 util/test/tests/Vulkan/VK_Simple_Triangle.py。demos 可执行文件支持--list-raw参数util/test/demos/main.cpp以纯文本列出可用测试名util/test/rdtest/runner.py 的fetch_tests()就是调用它解析出Name、Available、AvailMessage三列的 TSV用于在运行前检查某个 demo 是否已编译进 demos 程序。编写 Python 测试用例同样复制现有用例修改。一个典型用例继承rdtest.TestCase并实现check_capture()见 util/test/rdtest/testcase.py 基类定义import renderdoc as rd import rdtest class VK_Simple_Triangle(rdtest.TestCase): demos_test_name VK_Simple_Triangle def check_capture(self): # 获取最后一个 action设置帧事件然后校验三角形像素颜色 last_action self.get_last_action() self.set_event(last_action.eventId, True) self.check_triangle(outlast_action.copyDestination) ...框架提供的两种用例编写模式util/test/rdtest/testcase.py实现run()完全自定义执行流程实现get_capture()check_capture()使用默认的run()它自动运行 demo、捕获指定帧、打开捕获文件并调用check_capture()校验。demos_test_name非空时默认的get_capture()会通过capture.run_and_capture执行 demos 并抓取demos_frame_cap默认 5帧util/test/rdtest/testcase.py。用例还可以通过类属性调整行为slow_test标记慢测试、demos_frame_count、demos_captures_expected、demos_timeout等。基类提供了大量开箱即用的断言工具例如check_triangle()默认期望深灰背景上的绿色三角形util/test/rdtest/testcase.py、check_pixel_value()、check_mesh_data()对比后 VS 顶点数据util/test/rdtest/testcase.py、check_final_backbuffer()与参考图对比最终后备缓冲util/test/rdtest/testcase.py等。添加参考图片对比测试需要与参考图片对比的测试流程是第一次不带参考图运行测试会输出它将要对比的图片用pngcrush压缩这张图务必保证 RGBA 输出被保留以减少仓库体积将处理后的图片放入--data目录下以测试类名命名的子目录中——util/test/rdtest/testcase.py 的get_ref_path()会拼出data/ClassName/name的参考路径。参考数据目录在运行时不会被修改而tmp/与artifacts/会被清空重建util/test/run_tests.py 的参数注释也明确说明了这一点。许可与第三方依赖RenderDoc 以 MIT 许可证发布见仓库根目录 LICENSE.md。测试体系涉及的第三方组件及许可证如下详见 util/test/README.md 末尾GLAD扩展加载MITLZ4压缩BSDvolkVulkan 加载MITnukleardemos 启动器 UIMITshadercSPIR-V 着色器编译Apache-2.0pypngPython 测试的 PNG 读写库纯依赖MITdemo 视频片段来自 CaminandesCreative Commons Attribution 3.0 许可。常见问题速查测试说找不到renderdoc模块检查--pyrenderdoc是否指向正确的pymodules目录或--renderdoc是否指向构建输出目录util/test/run_tests.py。部分测试被跳过且提示 demo 未编译fetch_tests()通过--list-raw探测每个 demo 是否可用util/test/rdtest/runner.py未编译的 demo 对应测试会被跳过重新构建 demos 并确保路径正确即可。Vulkan 测试报图层注册失败需要在有管理员权限的环境运行或先手动注册 Vulkan 层util/test/rdtest/runner.py。想跑完整回归但时间不够默认会排除慢测试需要时可加--slow-tests显式包含。在 Android 设备上运行使用--adb-device 设备ID并把--demos-binary指向构建出的 demo APK。以上内容完整覆盖了 RenderDoc 测试体系从构建、运行到扩展的闭环。如需深入某个细节可直接阅读 util/test/run_tests.py、util/test/rdtest/testcase.py 与 util/test/demos/CMakeLists.txt 的对应源码。【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址: https://gitcode.com/gh_mirrors/re/renderdoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
