com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/.llm/skills/testing/shared-test-fixtures.md

@@ -0,0 +1,165 @@
+---
+title: "Shared Test Fixtures with Reference Counting"
+id: "shared-test-fixtures"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/SharedTextureTestFixtures.cs"
+      lines: "628-668"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "fixtures"
+  - "performance"
+  - "shared-state"
+  - "reference-counting"
+
+complexity:
+  level: "advanced"
+  reasoning: "Requires understanding of test parallelism and reference counting"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Dramatically reduces test suite time by sharing expensive fixtures"
+  maintainability:
+    rating: "medium"
+    details: "Adds complexity but reduces per-test setup"
+  testability:
+    rating: "medium"
+    details: "Shared state requires careful handling"
+
+prerequisites:
+  - "Understanding of NUnit fixture lifecycle"
+  - "Knowledge of reference counting"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-base-class-cleanup"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Expensive fixture sharing"
+  - "Reference-counted fixtures"
+  - "Test data sharing"
+
+related:
+  - "test-base-class-cleanup"
+  - "test-categories"
+  - "shared-test-fixtures-reference-counting"
+  - "shared-test-fixtures-generic-base"
+
+status: "stable"
+---
+
+# Shared Test Fixtures with Reference Counting
+
+> **One-line summary**: Share expensive test fixtures across test classes using thread-safe reference counting.
+
+## Overview
+
+Some test fixtures are expensive to create (large textures, asset bundles, scenes). Creating them per test wastes time and memory. Shared fixtures allow multiple test classes to reuse a single instance and clean up when the last user releases it.
+
+## Problem Statement
+
+```csharp
+[TestFixture]
+public class TextureTestsA
+{
+    private Texture2D largeTexture;
+
+    [OneTimeSetUp]
+    public void Setup()
+    {
+        largeTexture = new Texture2D(4096, 4096); // 64MB, 500ms
+    }
+}
+
+[TestFixture]
+public class TextureTestsB
+{
+    private Texture2D largeTexture; // Another 64MB, another 500ms
+}
+```
+
+## Solution
+
+### Core Concept
+
+```text
+AcquireFixtures() -> refCount++ -> create on first acquire
+ReleaseFixtures() -> refCount-- -> destroy on last release
+```
+
+Use a shared static fixture with a reference count and explicit acquire/release calls from each test fixture.
+
+## Usage
+
+```csharp
+[TestFixture]
+[Category("Slow")]
+public sealed class TextureProcessingTestsA : CommonTestBase
+{
+    [OneTimeSetUp]
+    public override void CommonOneTimeSetUp()
+    {
+        base.CommonOneTimeSetUp();
+        SharedTextureTestFixtures.AcquireFixtures();
+    }
+
+    [OneTimeTearDown]
+    public override IEnumerator CommonOneTimeTearDown()
+    {
+        SharedTextureTestFixtures.ReleaseFixtures();
+        yield return base.CommonOneTimeTearDown();
+    }
+}
+```
+
+## Performance Notes
+
+- **Savings**: N test classes x fixture time -> 1 x fixture time
+- **Memory**: Peak usage reduced to a single shared instance
+- **Thread Safety**: Lock overhead is negligible
+
+## Best Practices
+
+### Do
+
+- Use shared fixtures only for expensive resources
+- Pair Acquire/Release in OneTimeSetUp/OneTimeTearDown
+- Mark tests using shared fixtures with `[Category("Slow")]`
+- Treat shared fixtures as immutable
+
+### Don't
+
+- Don't access fixtures without acquiring first
+- Don't forget to release (memory leak)
+- Don't mutate shared fixtures between tests
+
+## See Also
+
+- [Shared Fixtures: Reference Counting](shared-test-fixtures-reference-counting.md)
+- [Shared Fixtures: Generic Base](shared-test-fixtures-generic-base.md)
+- [Test Base Class Cleanup](./test-base-class-cleanup.md)
+- [Test Categories](./test-categories.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |

package/.llm/skills/testing/test-base-class-cleanup-usage.md

@@ -0,0 +1,218 @@
+---
+title: "Test Base Class Cleanup Usage"
+id: "test-base-class-cleanup-usage"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/CommonTestBase.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "cleanup"
+  - "lifecycle"
+  - "unity"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Usage patterns depend on Unity fixture lifecycles"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Cleanup adds minor overhead but prevents leaks"
+  maintainability:
+    rating: "high"
+    details: "Consistent teardown reduces flaky tests"
+  testability:
+    rating: "high"
+    details: "Encourages isolated tests"
+
+prerequisites:
+  - "Understanding of NUnit fixture lifecycle"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-base-class-cleanup"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Common test base usage"
+
+related:
+  - "test-base-class-cleanup"
+
+status: "stable"
+---
+
+# Test Base Class Cleanup Usage
+
+> **One-line summary**: Usage patterns, performance notes, and best practices for automatic test cleanup.
+
+## Overview
+
+This skill covers how to apply cleanup tracking in test fixtures.
+
+## Solution
+
+Use the usage patterns below to keep tests isolated.
+
+## Usage
+
+### Basic Test Class
+
+```csharp
+[TestFixture]
+public sealed class PlayerTests : CommonTestBase
+{
+    [Test]
+    public void PlayerTakesDamage()
+    {
+        GameObject go = CreateGameObject("Player");
+        Player player = go.AddComponent<Player>();
+
+        player.TakeDamage(10);
+
+        Assert.AreEqual(90, player.Health);
+    } // go automatically destroyed after test
+}
+```
+
+### Fluent Tracking
+
+```csharp
+[Test]
+public void EnemySpawnsCorrectly()
+{
+    // Track returns the object for chaining
+    Enemy enemy = Track(Object.Instantiate(enemyPrefab)).GetComponent<Enemy>();
+
+    Assert.IsNotNull(enemy);
+    Assert.AreEqual(100, enemy.Health);
+}
+```
+
+### Tracking Multiple Objects
+
+```csharp
+[Test]
+public void BulletHitsEnemy()
+{
+    GameObject playerGo = CreateGameObject("Player", typeof(Rigidbody));
+    GameObject enemyGo = CreateGameObject("Enemy", typeof(Rigidbody), typeof(Collider));
+    GameObject bulletGo = CreateGameObject("Bullet", typeof(Rigidbody));
+
+    // All three destroyed after test
+    // ...
+}
+```
+
+### Tracking Disposables
+
+```csharp
+[Test]
+public void CacheEvictsOldEntries()
+{
+    var cache = TrackDisposable(new CacheBuilder<string, int>()
+        .WithMaximumSize(10)
+        .Build());
+
+    for (int i = 0; i < 20; i++)
+    {
+        cache.Put($"key{i}", i);
+    }
+
+    Assert.AreEqual(10, cache.Count);
+} // cache.Dispose() called automatically
+```
+
+### Shared Fixtures (Deferred Cleanup)
+
+```csharp
+[TestFixture]
+public sealed class ExpensiveAssetTests : CommonTestBase
+{
+    protected override bool DeferAssetCleanupToOneTimeTearDown => true;
+
+    private Texture2D sharedTexture;
+
+    [OneTimeSetUp]
+    public override void CommonOneTimeSetUp()
+    {
+        base.CommonOneTimeSetUp();
+        sharedTexture = Track(new Texture2D(1024, 1024));
+        // Expensive setup done once
+    }
+
+    [Test]
+    public void Test1()
+    {
+        // Uses sharedTexture
+    }
+
+    [Test]
+    public void Test2()
+    {
+        // Also uses sharedTexture
+    }
+
+    // sharedTexture destroyed in OneTimeTearDown
+}
+```
+
+### Scene Tests
+
+```csharp
+[TestFixture]
+public sealed class SceneLoadingTests : CommonTestBase
+{
+    [UnityTest]
+    public IEnumerator SceneLoadsCorrectly()
+    {
+        Scene testScene = CreateTestScene("TestScene");
+        SceneManager.SetActiveScene(testScene);
+
+        GameObject go = CreateGameObject("TestObject");
+        SceneManager.MoveGameObjectToScene(go, testScene);
+
+        Assert.IsTrue(testScene.isLoaded);
+        yield return null;
+    } // testScene unloaded after test
+}
+```
+
+## Performance Notes
+
+- **Overhead**: ~1us per tracked object
+- **Memory**: List allocation in OneTimeSetUp only
+- **Destruction Order**: Reverse order prevents orphan issues
+
+## Best Practices
+
+### Do
+
+- Always use `CreateGameObject` or `Track` for test objects
+- Use `TrackDisposable` for caches, streams, etc.
+- Set `DeferAssetCleanupToOneTimeTearDown = true` for expensive shared fixtures
+- Destroy in reverse order (handled automatically)
+
+### Don't
+
+- Don't manually destroy tracked objects (double-destroy error)
+- Don't forget to call base methods when overriding SetUp/TearDown
+- Don't create objects in [OneTimeSetUp] without tracking
+- Don't skip tracking "temporary" objects (they leak)

package/.llm/skills/testing/test-base-class-cleanup.md

@@ -0,0 +1,323 @@
+---
+title: "Test Base Class with Automatic Resource Cleanup"
+id: "test-base-class-cleanup"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/CommonTestBase.cs"
+      lines: "185-309"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "cleanup"
+  - "lifecycle"
+  - "fixtures"
+  - "unity"
+  - "nunit"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of NUnit lifecycle and Unity object management"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Cleanup overhead is minimal and only in tests"
+  maintainability:
+    rating: "high"
+    details: "Eliminates boilerplate cleanup code in every test"
+  testability:
+    rating: "high"
+    details: "Ensures clean state between tests"
+
+prerequisites:
+  - "Understanding of NUnit test lifecycle"
+  - "Knowledge of Unity object destruction"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "CommonTestBase"
+  - "Test fixture base"
+  - "Auto cleanup tests"
+
+related:
+  - "shared-test-fixtures"
+  - "test-categories"
+  - "test-base-class-cleanup-usage"
+
+status: "stable"
+---
+
+# Test Base Class with Automatic Resource Cleanup
+
+> **One-line summary**: Create an abstract test base class that automatically tracks and destroys GameObjects, Components, and other resources created during tests.
+
+## Overview
+
+Unity tests often create GameObjects and components that must be cleaned up to avoid test pollution. This pattern provides:
+
+1. **Automatic tracking** via `Track<T>()` method
+1. **Automatic destruction** in TearDown
+1. **Scene cleanup** for integration tests
+1. **Disposable tracking** for non-Unity resources
+
+## Problem Statement
+
+```csharp
+// BAD: Manual cleanup is error-prone
+[Test]
+public void TestSomething()
+{
+    GameObject go = new GameObject("Test");
+    var component = go.AddComponent<MyComponent>();
+
+    // Test code...
+
+    Object.DestroyImmediate(go); // Easy to forget!
+}
+
+// BAD: Cleanup in finally block is verbose
+[Test]
+public void TestSomething()
+{
+    GameObject go = null;
+    try
+    {
+        go = new GameObject("Test");
+        // Test...
+    }
+    finally
+    {
+        if (go != null) Object.DestroyImmediate(go);
+    }
+}
+```
+
+## Solution
+
+### Core Concept
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│  CommonTestBase                                                  │
+├─────────────────────────────────────────────────────────────────┤
+│  List<Object> _trackedObjects                                   │
+│  List<IDisposable> _trackedDisposables                          │
+├─────────────────────────────────────────────────────────────────┤
+│  Track<T>(T obj) → adds to list, returns obj                    │
+│  TrackDisposable<T>(T d) → adds to list, returns d              │
+├─────────────────────────────────────────────────────────────────┤
+│  [TearDown] → Destroys all tracked objects                      │
+│  [UnityTearDown] → Yields for async destruction                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Tests
+{
+    using System;
+    using System.Collections;
+    using System.Collections.Generic;
+    using NUnit.Framework;
+    using UnityEngine;
+    using UnityEngine.SceneManagement;
+    using Object = UnityEngine.Object;
+
+    /// <summary>
+    /// Base class for Unity tests with automatic resource cleanup.
+    /// </summary>
+    public abstract class CommonTestBase
+    {
+        private List<Object> _trackedObjects;
+        private List<IDisposable> _trackedDisposables;
+        private List<Scene> _trackedScenes;
+
+        /// <summary>
+        /// Set to true to defer asset cleanup to OneTimeTearDown.
+        /// Useful when tests share expensive assets.
+        /// </summary>
+        protected virtual bool DeferAssetCleanupToOneTimeTearDown => false;
+
+        [OneTimeSetUp]
+        public virtual void CommonOneTimeSetUp()
+        {
+            _trackedObjects = new List<Object>(16);
+            _trackedDisposables = new List<IDisposable>(4);
+            _trackedScenes = new List<Scene>(2);
+        }
+
+        [SetUp]
+        public virtual void CommonSetUp()
+        {
+            // Clear per-test tracking if not deferring
+            if (!DeferAssetCleanupToOneTimeTearDown)
+            {
+                _trackedObjects.Clear();
+                _trackedDisposables.Clear();
+            }
+        }
+
+        /// <summary>
+        /// Track a Unity Object for automatic destruction.
+        /// Returns the object for fluent usage.
+        /// </summary>
+        protected T Track<T>(T obj) where T : Object
+        {
+            if (obj != null)
+            {
+                _trackedObjects.Add(obj);
+            }
+            return obj;
+        }
+
+        /// <summary>
+        /// Track a disposable for automatic disposal.
+        /// </summary>
+        protected T TrackDisposable<T>(T disposable) where T : IDisposable
+        {
+            if (disposable != null)
+            {
+                _trackedDisposables.Add(disposable);
+            }
+            return disposable;
+        }
+
+        /// <summary>
+        /// Create and track a GameObject.
+        /// </summary>
+        protected GameObject CreateGameObject(string name = "TestObject")
+        {
+            return Track(new GameObject(name));
+        }
+
+        /// <summary>
+        /// Create and track a GameObject with components.
+        /// </summary>
+        protected GameObject CreateGameObject(string name, params Type[] components)
+        {
+            return Track(new GameObject(name, components));
+        }
+
+        /// <summary>
+        /// Create and track a new test scene.
+        /// </summary>
+        protected Scene CreateTestScene(string name = "TestScene")
+        {
+            Scene scene = SceneManager.CreateScene(name);
+            _trackedScenes.Add(scene);
+            return scene;
+        }
+
+        [TearDown]
+        public virtual void TearDown()
+        {
+            if (DeferAssetCleanupToOneTimeTearDown)
+            {
+                return;
+            }
+
+            CleanupDisposables();
+        }
+
+        [UnityTearDown]
+        public virtual IEnumerator UnityTearDown()
+        {
+            if (DeferAssetCleanupToOneTimeTearDown)
+            {
+                yield break;
+            }
+
+            yield return CleanupTrackedObjects();
+        }
+
+        [OneTimeTearDown]
+        public virtual IEnumerator CommonOneTimeTearDown()
+        {
+            if (DeferAssetCleanupToOneTimeTearDown)
+            {
+                CleanupDisposables();
+                yield return CleanupTrackedObjects();
+            }
+
+            yield return CleanupScenes();
+        }
+
+        private void CleanupDisposables()
+        {
+            foreach (IDisposable disposable in _trackedDisposables)
+            {
+                try
+                {
+                    disposable?.Dispose();
+                }
+                catch (Exception e)
+                {
+                    Debug.LogWarning($"[CommonTestBase] Dispose failed: {e.Message}");
+                }
+            }
+            _trackedDisposables.Clear();
+        }
+
+        private IEnumerator CleanupTrackedObjects()
+        {
+            // Destroy in reverse order (children before parents)
+            for (int i = _trackedObjects.Count - 1; i >= 0; i--)
+            {
+                Object obj = _trackedObjects[i];
+                if (obj != null)
+                {
+                    if (Application.isPlaying)
+                    {
+                        Object.Destroy(obj);
+                    }
+                    else
+                    {
+                        Object.DestroyImmediate(obj);
+                    }
+                }
+            }
+            _trackedObjects.Clear();
+
+            // Yield to allow destruction to complete
+            yield return null;
+        }
+
+        private IEnumerator CleanupScenes()
+        {
+            foreach (Scene scene in _trackedScenes)
+            {
+                if (scene.isLoaded)
+                {
+                    yield return SceneManager.UnloadSceneAsync(scene);
+                }
+            }
+            _trackedScenes.Clear();
+        }
+    }
+}
+```
+
+## Related Patterns
+
+- [Shared Test Fixtures](./shared-test-fixtures.md) - Reference-counted fixtures
+- [Test Categories](./test-categories.md) - Organizing tests
+- [Test Base Class Cleanup Usage](./test-base-class-cleanup-usage.md) - Usage patterns and best practices