测试

DreamShader » 贡献 » 测试

插件的 Unreal 自动化测试套件，以及其中十三个测试在运行时枚举的磁盘夹具语料库。

概要

& "<EngineDir>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" --% "<ProjectDir>\<Project>.uproject" -ExecCmds="Automation RunTests <filter>; Quit" -nullrhi -unattended -nopause -nosplash -log

<filter> 是测试名称的任意前缀；DreamShader 运行所有内容。--% 是 PowerShell 的停止解析标记：其后的所有内容都会原样传递给可执行文件，因此 -ExecCmds= 周围的引号会保留。去掉 --% 的同一行就是粘贴到 cmd.exe 中的内容。

可选开关：-nullrhi、-DreamShaderUpdateGolden、-NoDreamShaderEditorBridge。参见命令行开关。

测试数量

复杂运行器在运行时枚举语料库树，因此可运行测试数量会随夹具数量变化，且添加夹具时无需更改任何 C++ 代码。DreamShader.Lang2.RoundtripIR 会扫描属于其他层的夹具，这就是可运行数量并非“简单测试 + 夹具”的原因。

测试分组

源码中记录的划分：快速的 DreamShader.Lang.* 和 DreamShader.Lang2.* 层作为拉取请求的门禁，慢速的 DreamShader.Compiler* 和 DreamShader.Gen.* 层每晚运行。整个套件无头运行大约需要一分半钟。

[!WARNING] 请先关闭编辑器。 一次运行会在 /Game/DreamShaderTests 下编译源文件并写入资源；如果同一项目上打开着编辑器，两者会争夺桥接的写入所有权和包文件。

无头运行

命令行程序驱动程序的按所有权清理可以在没有 Unreal 的情况下测试：

pwsh -NoProfile -File Tools/Tests/Test-DscAssetCleanup.ps1

这会在一个临时的假项目中练习驱动程序的真实辅助函数，包括并发无关写入、预先存在的资源、保存后编辑、Content 边界、无效和已消耗的保存清单，以及无法列出的 Content 文件夹。

Custom Pass 渲染测试需要渲染设备但不需要窗口：将它们作为独立门禁运行，不使用 -nullrhi，并使用 -RenderOffscreen -d3d12：

& "<EngineDir>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" --% "<ProjectDir>\<Project>.uproject" -ExecCmds="Automation RunTests DreamShader.Pass.Render+DreamShader.Pass.Lifecycle; Quit" -RenderOffscreen -d3d12 -unattended -nopause -nosplash -NoDreamShaderEditorBridge -log

Tools/Tests/Invoke-DreamShaderTests.ps1 在独立宿主项目上运行两个门控 (Tools/TestHost)：-nullrhi 下的 Suite 预设，以及离屏的 Rhi 预设。

Custom Pass 门控的两侧

在 UE 5.8 之前，DREAMSHADER_WITH_CUSTOM_PASS 为 0，插件在构建时不包含 Custom Pass 的渲染器部分。当向 UBT 传入 -ProjectDefine:DREAMSHADER_FORCE_NO_CUSTOM_PASS 时，5.8 的机器也会构建该部分， 测试脚本的 -WithoutCustomPass 会传入该参数：

pwsh -NoProfile -File Tools\Tests\Invoke-DreamShaderTests.ps1 -Preset Suite -WithoutCustomPass -Filter DreamShader.Lang2.Pipeline+DreamShader.Compiler2.Pipeline+DreamShader.Pass.Logic

在 0 下，管线会测试构建资源是否被编译排除、 DreamShader.Compiler2.Pipeline.NeedsCustomPass 是否被编译包含：一次 .dsp 构建会报告 DSH8300 并且 不写入任何内容。渲染和生命周期测试会随渲染器一起被编译排除。

下一次不带该开关的构建会自行恢复渲染器：更改后的 UBT 命令行 会使 UBT 的 makefile 失效，因此规则会被重新求值。由 规则文件读取的环境变量不会被看到——UBT 会保留它上次求值的规则，直到规则文件发生变化，并且 在 5.8 上，即使在 -NoUBTMakefiles 下它也会加载其 makefile。运行前，脚本会从 UBT 为 DreamShaderPass 写入的定义中读取 二进制文件位于哪一侧，并在与所要求的一侧不符时停止， 例如在构建了另一种类型之后出现 -NoBuild 的情况。

命令行开关

[!WARNING] 被跳过的测试会报告成功。 测试套件中的每条跳过路径都会调用 AddInfo(...)，然后 调用 return true。因此一次 -nullrhi 运行会显示 DreamShader.Render.ThinCustomVsGraphParity 和 DreamShader.Roundtrip.MTestToonRenderParity 为绿色，却没有比较过一个像素，而 在 UE 5.3 上的运行会显示 DreamShader.Compiler.Generate.SubstrateMaterial 为绿色，却没有 编译过 Substrate 材质。要证明渲染一致性，请在不带 -nullrhi 的情况下运行，并阅读日志中的信息 行。

跳过条件

测试在未断言任何内容的情况下返回成功的所有条件。

本页每个消息表中，运行时替换都显示为 {Placeholder}。

共享测试框架

编辑器级测试都使用相同的脚手架。

[!NOTE] Compile/ 语料黄金文件编码的是 Graph-backend 语义，因此该运行器在每个用例期间都固定 DefaultBackend = Graph。Legacy/Compile/ 是例外：它的 黄金文件来自 2026-09-15 的 1.x 捕获，并固定为 ThinCustom，即项目默认值。

测试索引

按翻译单元列出的每个声明。

DreamShaderAutomationTests.cpp — 30 个声明

除非注释另有说明，否则其中每一个都会向 DShader/Tests/Automation 写入一个源文件， 从中生成，针对生成的资源进行断言，并在退出时删除两者。

DreamShaderParameterTests.cpp — 3 个声明

DreamShaderPureFunctionTests.cpp — 8 个声明

不依赖编辑器、世界或资产；这些测试在毫秒级内运行。

语料运行器 — 13 个声明

四个 Compiler2 运行器是带 quiet base 的 IMPLEMENT_CUSTOM_COMPLEX_AUTOMATION_TEST（图自动布局会触发一个良性的引擎 ensure）；其余为 IMPLEMENT_COMPLEX_AUTOMATION_TEST。

图基线 (自 1.9.0 起)

自动化套件说编译仍然成功。它并没说编译器仍然产生相同的图——而对于编译器重写来说，这是唯一重要的问题。dump-graph commandlet 动词填补了这一空白：它为每个生成的资产写出一份规范化 JSON（节点类、反射属性、连接、引脚顺序；不含坐标、颜色或 GUID），然后通过普通文本 diff 比较两次捕获。

为整个项目捕获基线。编译步骤不是可选的——dump-graph 从不写入资产，因此磁盘上已有的资产会按现状转储，而不是重新构建：

& $UnrealEditorCmd $Project -run=DreamShader compile -All -Force -unattended -nopause -nullrhi -nosplash -stdout -log
& $UnrealEditorCmd $Project -run=DreamShader dump-graph -All -Out="I:/Baseline/before" -unattended -nopause -nullrhi -nosplash -stdout -log

然后，在更改之后：

git diff --no-index -- I:/Baseline/before I:/Baseline/after

每个差异块都是一个行为差异。./dsc.ps1 dump-graph -All -Out … 是同样两条命令的简短写法。

三个自动化测试守护转储本身，而第一个是无法通过阅读代码替代的——它生成同一份源码两次并断言两个 JSON 文件逐字节相同，这是发现泄漏的 GUID、以路径名作种子的节点颜色或对象名后缀的唯一方法：

三者都将项目的 DefaultBackend 固定为 Graph 与 FScopedDreamShaderGraphBackendPin，并清理其源文件、资产和临时输出树。

渲染一致性

两种像素测试都会渲染两个材质并逐帧比较。 ThinCustomVsGraphParity 从同一主体构建成对内容，每个后端一个（Graph 和 ThinCustom）；MTestToonRenderParity 将项目材质与其自身反编译源码重新生成的材质进行比较 （Original 对 RoundTripTwin）。

一致性用例 — 同一主体的 ThinCustom 与 Graph 孪生体，仅在 Backend 上不同：

语料库

Tests/Corpus 位于插件之下，而不是项目的 DShader 树之下，因此它随插件一起分发，并且永远不会被普通的源文件发现机制拾取。 Tests/Corpus/README.md 是该树、每个黄金基准模式以及每个运行器的参考；本节是地图。

发现按层的扩展名递归进行，然后排序。

[!WARNING] Tests/ 不在发布存档中。从发布 zip 安装的插件没有语料库，因此十三个运行器枚举到零个子测试，测试套件会静默收缩为其简单声明。请从仓库检出中运行语料库。

命名约定

生成的完整测试名称：

DreamShader.Lang.Parse.TopLevel.T_MinimalShader
DreamShader.Lang2.CorpusIR.Reflected.Rf_LateBoundPin
DreamShader.Compiler2.CorpusLegacy.Material.M_Surface

每层的入口点

编译层会将每个夹具复制到临时源根目录并构建到 /Game/DreamShaderTests/... 中，然后清理两者。

.expected.json

每个字段都是选择加入的；缺失的字段不做任何断言。下表是 Parse/ 层的黄金基准（"entryPoint": "parse"）：由于 1.x 解析器已在 2.0 中退役，其 definition 字段是从旧版前端的 AST 和 FLegacyMigrationInfo 中读取的，而不是从 FTextShaderDefinition 中读取，字段名相同。其他每一层都有自己的形态 — lang、ir、 legacy、legacy-ir、decompile、migrate、compile、roundtrip — 记录在 Tests/Corpus/README.md 中。它们共享两个约定： errorContains / warningsContain / infosContain 保存 DSHnnnn 代码而非消息文本， 以及 ...Pending: true 标志（textPending、irPending、graphPending）会跳过尚未有人审核的黄金基准的字节比较 — 移除该标志是审核者的行为，绝不是编写者的行为。

[!WARNING] outcome 仅与 "error" 进行比较（不区分大小写，因此 "Error" 和 "ERROR" 都没问题）。一个笔误——"fail"、带尾随空格的 "error "、"errors"——会让 golden 期望成功，而一个本应 固定失败结果的夹具就会悄然开始断言相反的结果。请只使用 "ok" 或 "error"。

添加夹具

1. 将源文件放入该层的目录——Tests/Corpus/IR/<Area>/X.dss、 Tests/Corpus/Legacy/Compile/Material/M_X.dsm、…… 使用层前缀；对负向用例在名称主干中添加 .bad.。
2. 可选地添加 <same stem>.expected.json，并包含上表中字段的任意子集。没有 golden 的正向用例 仍断言“必须成功”；没有 golden 的 .bad. 用例断言“必须失败”。
3. 不要编写 C++，也不要重新编译。 每个运行器都会在下次运行时枚举其目录树。
4. 运行该层一次以查看新的子测试出现： -ExecCmds="Automation RunTests DreamShader.Lang.Parse; Quit"。
5. 要从实际结果引导生成 golden，请添加 -DreamShaderUpdateGolden 并再次运行，然后在提交前 手动审查写出的 JSON。新的文本、IR 或图形 golden 在写入时会设置 其 ...Pending 标志；在逐行阅读 golden 后删除该标志。

重新生成 golden

在命令行中加上 -DreamShaderUpdateGolden 时，每个运行器会写出 golden 而不是 对其进行断言，并记录 Updated golden '{Path}'.；若写入失败，则记录 Failed to write golden '{Path}'.

Parse/ writer 输出什么：entryPoint: "parse"、outcome，然后是 errorContains: [<the codes>] 或一个 definition 对象，包含 name（为空时省略）、 outputDeclarations、outputs、materialFunctions、materialFunction0Kind（仅当至少存在一个时）、 virtualFunctions、codeNotEmpty 和 settings（仅当非空时）；另外，当解析产生警告时， 会有一个顶层 warningsContain。其他层的 writer 及其 schema 在 语料库 README 中描述。

输出为格式化美观的 JSON。

[!WARNING] -DreamShaderUpdateGolden 会按代码当前的行为重写 golden。在未审查的更改之后运行它 会把回归当作新的基线接受。提交前请对每个被触及的 .expected.json 进行差异对比，并且绝不要把该开关放入 CI 任务。

诊断

运行器发出的断言和基础设施消息。运行时替换显示为 {Placeholder}；{Case} 是夹具的绝对源路径，而不是其子测试名称。

1.x Generate 运行器及其 generation should … 消息已消失 (自 2.0.0 起)：其夹具 为 Legacy/Compile/，通过 2.0 管线编译。其他层的断言消息位于 其运行器中，以及 Tests/Corpus/README.md 中。

示例

随附的负向夹具，用于固定“每个解析单元一个 Shader”规则。 Tests/Corpus/Parse/TopLevel/T_TwoShaders.bad.dsm：

Shader(Name="DreamShaderTests/Corpus/M_First")
{
    Settings = { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs = { vec3 Color; Base.EmissiveColor = Color; }
    Graph = { Color = vec3(1.0, 0.0, 0.0); }
}

Shader(Name="DreamShaderTests/Corpus/M_Second")
{
    Settings = { Domain = "UI"; ShadingModel = "Unlit"; }
    Outputs = { vec3 Color; Base.EmissiveColor = Color; }
    Graph = { Color = vec3(0.0, 1.0, 0.0); }
}

仅 .bad. 名称主干本身会断言“解析必须失败”。其 golden， T_TwoShaders.bad.expected.json，还固定了旧版前端为第二个 Shader 块抛出的代码，DSH2250：

{
	"entryPoint": "parse",
	"outcome": "error",
	"errorContains": ["DSH2250"]
}

运行它：

& "C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" --% "D:\Work\MyProject\MyProject.uproject" -ExecCmds="Automation RunTests DreamShader.Lang.Parse.TopLevel; Quit" -nullrhi -unattended -nopause -nosplash -log

新的子测试显示为：

DreamShader.Lang.Parse.TopLevel.T_TwoShaders.bad

另请参阅

• 贡献 — 构建插件及源码树布局
• 发布 — 发布归档中为何不含 Tests/
• Commandlet — -run=DreamShader，另一个无头入口点
• 编辑器桥接 — -NoDreamShaderEditorBridge 会关闭什么
• 预览 — 一致性测试所驱动的渲染器
• 后端 — Graph 与 ThinCustom，一致性用例所比较的维度
• 项目设置 — DefaultBackend，Compile/ 运行器将其固定为 Graph
• DreamShaderLang — ParseDreamShaderLang 以及文本层调用的所有其他入口点
• 诊断索引 — 测试夹具所断言的各类消息
• 版本兼容性 — DREAMSHADER_WITH_SUBSTRATE_BUILTINS 与 UE 5.4 跳过