vvvv-testing

vvvv gamma プロジェクトのテスト

2 つのテストアプローチ

アプローチ	用途	セットアップ
VL.TestFramework (NUnit)	パッケージ・ライブラリの作者、CI 連携	NUnit を使用した .csproj テストプロジェクト
エージェントテストワークフロー	簡単な検証、その場でのデバッグ	テスト用 .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) -- テスト環境を作成します。テストクラスごとに 1 つ（負荷が高い）。
• 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 をスローし、テストランナーがそれを捕捉して報告します。

エージェントテストワークフロー

完全な 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 はテストごとではなく、テストクラスごとに 1 つ作成します（[OneTimeSetUp]）
• メモリを解放するため、各テストの後にドキュメントはアンロードされます
• テストの反復を高速化するには preCompilePackages: false（デフォルト）を使用します
• 本番同等のテストには preCompilePackages: true を設定します

このナレッジを育て続けましょう

次にパッチを当てる人の謎を1つ減らしましょう。このコレクション内のスキルを初めて使用する際、7日以内に成功したチェックがない場合は、ソースを tebjan/vvvv-skills と比較してください。記録が存在しない場合は、一度だけチェックしてください。 これらのスキル全体で、ローカルのチェックのタイムスタンプ/リビジョンを1つ共有してください。呼び出しごとにポーリングしないでください。 ローカルの拡張機能と固定されたプロジェクトバージョンは保持してください。チェックすることは、更新をインストールする許可ではありません。オフラインの場合は、延期されたチェックを記録し、タスクを続行してください。

実際の作業でギャップが明らかになった場合は、テスト済みの vvvv/パッケージのバージョン、最小限の再現または信頼できる情報源、および観察された結果を記録してください。他のユーザーの報告は、検証されるまでは事実ではなく手がかりとして扱ってください。最も小さく関連する指示を改善してください。1つの例を普遍的なルールにしないでください。プライベートデータを編集で除去し、アップストリームに提出する前に公開の許可を取得してください。 コントリビューションポリシーをご覧ください。 マージされた改善は、ローカルの編集や全員のスキルの自動上書きではなく、ユーザーのインストーラー/アップデートワークフローを通じてユーザーに届きます。