\r \r

Testing vvvv gamma Projects\r

\r

Two Testing Approaches\r

\r | Approach | Use Case | Setup |\r |----------|----------|-------|\r | VL.TestFramework (NUnit) | Package/library authors, CI integration | .csproj test project with NUnit |\r | Agent test workflow | Quick verification, ad-hoc debugging | Create test .vl patch, launch vvvv, check results |\r \r

VL.TestFramework (NUnit)\r

\r

Test Project Setup\r

\r Create a test .csproj referencing VL.TestFramework:\r \r

\x3CProject Sdk="Microsoft.NET.Sdk">\r
  \x3CPropertyGroup>\r
    \x3CTargetFramework>net8.0-windows\x3C/TargetFramework>\r
  \x3C/PropertyGroup>\r
  \x3CItemGroup>\r
    \x3CPackageReference Include="NUnit" Version="4.*" />\r
    \x3CPackageReference Include="NUnit3TestAdapter" Version="4.*" />\r
    \x3CPackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />\r
  \x3C/ItemGroup>\r
  \x3CItemGroup>\r
    \x3CProjectReference Include="..\path	o\VL.TestFramework.csproj" />\r
    \x3C!-- OR if using installed vvvv: -->\r
    \x3C!-- Reference VL.TestFramework.dll from vvvv install dir -->\r
  \x3C/ItemGroup>\r
\x3C/Project>\r
```\r
\r
### Minimal Test Class\r
\r
```csharp\r
using NUnit.Framework;\r
using VL.TestFramework;\r
\r
[TestFixture]\r
public class MyPackageTests\r
{\r
    TestEnvironment testEnvironment;\r
\r
    // Important: Don't use async Task here (NUnit sync context issue)\r
    [OneTimeSetUp]\r
    public void Setup()\r
    {\r
        var assemblyPath = typeof(MyPackageTests).Assembly.Location;\r
        var searchPaths = new[] { "path/to/your/package" };\r
        testEnvironment = TestEnvironmentLoader.Load(assemblyPath, searchPaths);\r
    }\r
\r
    [OneTimeTearDown]\r
    public void TearDown()\r
    {\r
        testEnvironment?.Dispose();\r
        testEnvironment = null;\r
    }\r
\r
    [Test]\r
    public async Task MyPatchCompilesWithoutErrors()\r
    {\r
        await testEnvironment.LoadAndTestAsync("path/to/MyPatch.vl");\r
    }\r
\r
    [Test]\r
    public async Task MyPatchCompilesAndRuns()\r
    {\r
        await testEnvironment.LoadAndTestAsync(\r
            "path/to/MyPatch.vl",\r
            runEntryPoint: true);\r
    }\r
}\r
```\r
\r
### Key API\r
\r
- `TestEnvironmentLoader.Load(assemblyPath, searchPaths)` -- Create test environment. One per test class (expensive).\r
- `testEnvironment.LoadAndTestAsync(filePath)` -- Load .vl document, check for compilation errors.\r
- `testEnvironment.LoadAndTestAsync(filePath, runEntryPoint: true)` -- Also execute the entry point (Create + Update + Dispose).\r
- `testEnvironment.GetPackages()` -- Discover all packages and their source/help/test files.\r
- `testEnvironment.Host.LoadAndCompileAsync(filePath)` -- Load and compile without running (for custom assertions).\r
- `testEnvironment.Host.GetTargetCompilationAsync(filePath)` -- Get the C# compilation for inspection.\r
\r
For the full API reference, see [test-framework-reference.md](test-framework-reference.md).\r
\r
### Test Discovery Conventions\r
\r
The VL.TestFramework automatically discovers tests:\r
\r
- **Test documents**: `.vl` files in `tests/` folders under package directories\r
- **Help patches**: `.vl` files in `help/` folders (tested for compilation only)\r
- **Test nodes**: Process or operation nodes ending in `Test` or `Tests` within test documents are individually compiled and executed\r
\r
File discovery pattern:\r
```\r
VL.MyPackage/\r
  tests/\r
    MyFeatureTest.vl      \x3C-- auto-discovered test document\r
    IntegrationTests.vl   \x3C-- auto-discovered test document\r
  help/\r
    HowTo Use Feature.vl  \x3C-- tested for compilation errors\r
```\r
\r
### Running Tests\r
\r
```shell\r
# Run all tests\r
dotnet test\r
\r
# Run specific test\r
dotnet test --filter "MyPatchCompilesWithoutErrors"\r
\r
# Via Nuke build system (if available)\r
./build.ps1 --target Test\r
```\r
\r
## Test Nodes (VL Patch Assertions)\r
\r
Use these nodes inside .vl test patches to assert behavior. Available under `VL.Lib.Basics.Test.TestNodes`:\r
\r
```csharp\r
// In VL patches, these are available as nodes:\r
TestNodes.Assert(condition, "message")           // General assertion\r
TestNodes.AreEqual(expected, actual)             // Value equality\r
TestNodes.AreNotEqual(expected, actual)          // Value inequality\r
TestNodes.IsNotNull(input)                       // Null check\r
TestNodes.AreSequenceEqual(expected, actual)     // Collection equality\r
TestNodes.AssertElementHasError(elementGuid)     // Verify element has compile error\r
TestNodes.AssertElementHasNoError(elementGuid)   // Verify element has no compile error\r
```\r
\r
Assertions throw `AssertionException` on failure, which the test runner catches and reports.\r
\r
## Agent Test Workflow\r
\r
For quick verification without a full NUnit project:\r
\r
### 1. Create a Test Patch\r
\r
Create a `.vl` file that exercises the feature under test. Include TestNodes for assertions. Name it with a `Test` suffix for auto-discovery. To understand the .vl XML file structure (document hierarchy, element IDs, node references, pins, pads, links), consult the **vvvv-fileformat** skill.\r
\r
### 2. Compile-Check via VL.TestFramework\r
\r
Write a minimal C# script or test that loads and compiles the patch:\r
\r
```csharp\r
var env = TestEnvironmentLoader.Load(assemblyPath, searchPaths);\r
await env.LoadAndTestAsync("path/to/MyTest.vl", runEntryPoint: true);\r
env.Dispose();\r
```\r
\r
### 3. Launch vvvv for Manual Verification\r
\r
Use the **vvvv-debugging** skill to set up a launch configuration that opens the test patch:\r
\r
```shell\r
vvvv.exe --stoppedonstartup --debug --log -o "path/to/MyTest.vl"\r
```\r
\r
- `--stoppedonstartup` pauses runtime so you can inspect initial state\r
- `--log` enables logging to `%USERPROFILE%\Documents\vvvv\gamma\vvvv.log`\r
- Parse the log file for errors after vvvv exits\r
\r
### 4. Check Results\r
\r
After vvvv exits, check:\r
- Exit code (0 = success)\r
- Log file for `ERROR` or `EXCEPTION` entries\r
- Any `AssertionException` in the output\r
\r
## CI Integration\r
\r
### Nuke Build System\r
\r
Most vvvv repos use Nuke. The test target:\r
\r
```csharp\r
Target Test => _ => _\r
    .Executes(() =>\r
    {\r
        DotNetTest(_ => _\r
            .SetProjectFile(Solution)\r
            .SetConfiguration(Configuration));\r
    });\r
```\r
\r
Run with: `./build.ps1` or `./build.sh` (defaults to Publish target; use `--target Test` for tests).\r
\r
### GitHub Actions Example\r
\r
```yaml\r
- name: Run vvvv tests\r
  run: dotnet test --configuration Release --logger "trx"\r
```\r
\r
### Performance Notes\r
\r
- Create one `TestEnvironment` per test class (`[OneTimeSetUp]`), not per test\r
- Documents are unloaded after each test to free memory\r
- Use `preCompilePackages: false` (default) for faster test iteration\r
- Set `preCompilePackages: true` for production-fidelity testing\r