测试 vvvv gamma 项目

两种测试方法

VL.TestFramework (NUnit)

测试项目设置

创建引用 VL.TestFramework 的测试 .csproj：

xml


net8.0-windows

最小测试类

csharp
using NUnit.Framework;
using VL.TestFramework;

[TestFixture]
public class MyPackageTests
{
TestEnvironment testEnvironment;

// 重要：不要使用 async Task（NUnit 同步上下文问题）
[OneTimeSetUp]
public void Setup()
{
var assemblyPath = typeof(MyPackageTests).Assembly.Location;
var searchPaths = new[] { path/to/your/package };
testEnvironment = TestEnvironmentLoader.Load(assemblyPath, searchPaths);
}

[OneTimeTearDown]
public void TearDown()
{
testEnvironment?.Dispose();
testEnvironment = null;
}

[Test]
public async Task MyPatchCompilesWithoutErrors()
{
await testEnvironment.LoadAndTestAsync(path/to/MyPatch.vl);
}

[Test]
public async Task MyPatchCompilesAndRuns()
{
await testEnvironment.LoadAndTestAsync(
path/to/MyPatch.vl,
runEntryPoint: true);
}
}

关键 API

• - TestEnvironmentLoader.Load(assemblyPath, searchPaths) -- 创建测试环境。每个测试类一个（开销较大）。
• testEnvironment.LoadAndTestAsync(filePath) -- 加载 .vl 文档，检查编译错误。
• testEnvironment.LoadAndTestAsync(filePath, runEntryPoint: true) -- 同时执行入口点（Create + Update + Dispose）。
• testEnvironment.GetPackages() -- 发现所有包及其源代码/帮助/测试文件。
• testEnvironment.Host.LoadAndCompileAsync(filePath) -- 加载并编译但不运行（用于自定义断言）。
• testEnvironment.Host.GetTargetCompilationAsync(filePath) -- 获取 C# 编译结果以供检查。

完整 API 参考，请参见 test-framework-reference.md。

测试发现约定

VL.TestFramework 自动发现测试：

• - 测试文档：包目录下 tests/ 文件夹中的 .vl 文件
• 帮助补丁：help/ 文件夹中的 .vl 文件（仅测试编译）
• 测试节点：测试文档中以 Test 或 Tests 结尾的 Process 或 Operation 节点会被单独编译和执行

文件发现模式：

VL.MyPackage/
tests/
MyFeatureTest.vl <-- 自动发现的测试文档
IntegrationTests.vl <-- 自动发现的测试文档
help/
HowTo Use Feature.vl <-- 测试编译错误

运行测试

shell

运行所有测试

运行特定测试

通过 Nuke 构建系统（如果可用）

测试节点（VL 补丁断言）

在 .vl 测试补丁中使用这些节点来断言行为。可在 VL.Lib.Basics.Test.TestNodes 下找到：

csharp
// 在 VL 补丁中，这些可作为节点使用：
TestNodes.Assert(condition, message) // 通用断言
TestNodes.AreEqual(expected, actual) // 值相等
TestNodes.AreNotEqual(expected, actual) // 值不相等
TestNodes.IsNotNull(input) // 空值检查
TestNodes.AreSequenceEqual(expected, actual) // 集合相等
TestNodes.AssertElementHasError(elementGuid) // 验证元素有编译错误
TestNodes.AssertElementHasNoError(elementGuid) // 验证元素无编译错误

断言失败时会抛出 AssertionException，测试运行器会捕获并报告。

Agent 测试工作流

用于无需完整 NUnit 项目的快速验证：

1. 创建测试补丁

创建一个 .vl 文件来测试目标功能。包含 TestNodes 用于断言。以 Test 后缀命名以便自动发现。要了解 .vl XML 文件结构（文档层次结构、元素 ID、节点引用、引脚、焊盘、链接），请参考 vvvv-fileformat 技能。

2. 通过 VL.TestFramework 进行编译检查

编写一个加载并编译补丁的最小 C# 脚本或测试：

csharp
var env = TestEnvironmentLoader.Load(assemblyPath, searchPaths);
await env.LoadAndTestAsync(path/to/MyTest.vl, runEntryPoint: true);
env.Dispose();

3. 启动 vvvv 进行手动验证

使用 vvvv-debugging 技能设置启动配置以打开测试补丁：

shell
vvvv.exe --stoppedonstartup --debug --log -o path/to/MyTest.vl

• - --stoppedonstartup 暂停运行时，以便检查初始状态
• --log 启用日志记录到 %USERPROFILE%\Documents\vvvv\gamma\vvvv.log
• vvvv 退出后解析日志文件中的错误

4. 检查结果

vvvv 退出后，检查：

• - 退出代码（0 = 成功）
• 日志文件中的 ERROR 或 EXCEPTION 条目
• 输出中的任何 AssertionException

CI 集成

Nuke 构建系统

大多数 vvvv 仓库使用 Nuke。测试目标：

csharp
Target Test => =>
.Executes(() =>
{
DotNetTest( =>
.SetProjectFile(Solution)
.SetConfiguration(Configuration));
});

运行方式：./build.ps1 或 ./build.sh（默认为 Publish 目标；使用 --target Test 进行测试）。

GitHub Actions 示例

yaml

• - name: Run vvvv tests

性能说明

• - 每个测试类创建一个 TestEnvironment（[OneTimeSetUp]），而不是每个测试
• 每个测试后卸载文档以释放内存
• 使用 preCompilePackages: false（默认）以获得更快的测试迭代
• 设置 preCompilePackages: true 以获得生产级保真度测试