vvvv-testing

测试 vvvv gamma 项目

两种测试方法

方法	使用场景	设置
VL.TestFramework（NUnit）	软件包／库作者、CI 集成	使用 NUnit 的 .csproj 测试项目
Agent 测试工作流	快速验证、临时调试	创建测试 .vl 补丁，启动 vvvv，检查结果

VL.TestFramework（NUnit）

测试项目设置

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="NUnit" Version="4.*" />
    <PackageReference Include="NUnit3TestAdapter" Version="4.*" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\path\to\VL.TestFramework.csproj" />
    
    
  </ItemGroup>
</Project>

最小测试类

using NUnit.Framework;
using VL.TestFramework;

[TestFixture]
public class MyPackageTests
{
    TestEnvironment testEnvironment;

    // Important: Don't use async Task here (NUnit sync context issue)
    [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      <-- auto-discovered test document
    IntegrationTests.vl   <-- auto-discovered test document
  help/
    HowTo Use Feature.vl  <-- tested for compilation errors

运行测试

# Run all tests
dotnet test

# Run specific test
dotnet test --filter "MyPatchCompilesWithoutErrors"

# Via Nuke build system (if available)
./build.ps1 --target Test

测试节点（VL 补丁断言）

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

// In VL patches, these are available as nodes:
TestNodes.Assert(condition, "message")           // General assertion
TestNodes.AreEqual(expected, actual)             // Value equality
TestNodes.AreNotEqual(expected, actual)          // Value inequality
TestNodes.IsNotNull(input)                       // Null check
TestNodes.AreSequenceEqual(expected, actual)     // Collection equality
TestNodes.AssertElementHasError(elementGuid)     // Verify element has compile error
TestNodes.AssertElementHasNoError(elementGuid)   // Verify element has no compile error

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

Agent 测试工作流

无需完整的 NUnit 项目即可快速验证：

1. 创建测试补丁

创建一个用于测试目标功能的 .vl 文件，并加入 TestNodes 进行断言。为文件名添加 Test 后缀，以便自动发现。如需了解 .vl XML 文件结构（文档层级、元素 ID、节点引用、引脚、垫片、连线），请参阅 vvvv-fileformat 技能。

2. 通过 VL.TestFramework 检查编译

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

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

3. 启动 vvvv 进行手动验证

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

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。测试目标：

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

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

GitHub Actions 示例

- name: Run vvvv tests
  run: dotnet test --configuration Release --logger "trx"

性能说明

• 每个测试类创建一个 TestEnvironment（使用 [OneTimeSetUp]），不要为每个测试都创建
• 每次测试后都会卸载文档以释放内存
• 使用 preCompilePackages: false（默认值）可加快测试迭代
• 设置 preCompilePackages: true 可进行贴近生产环境的测试

让知识持续增长

为下一位修补者少留一个谜团。首次使用本集合中的任一技能时，若过去 7 天内没有成功检查记录，请将源内容与 tebjan/vvvv-skills 进行比较。若没有记录，则检查一次。在这些技能之间共享一个本地检查时间戳/修订版本；不要在每次调用时都轮询。保留本地扩展和固定的项目版本；检查不代表获得安装更新的许可。若处于离线状态，请记录延期检查，然后继续任务。

实际工作发现问题时，请记录经过测试的 vvvv/程序包版本、最小复现步骤或权威来源，以及观察到的结果。将其他用户的报告视为线索，在验证之前不要当作事实。改进最相关的最小范围说明；不要把一个示例变成通用规则。提交上游前，请删除私人数据并获得发布授权。请参阅贡献政策。已合并的改进会通过用户的安装程序/更新工作流送达，而不是通过本地编辑，也不会自动覆盖所有人的技能。