com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/.llm/skills/testing/test-coverage-unity-anti-patterns.md

@@ -0,0 +1,232 @@
+---
+title: "Unity Test Considerations and Anti-Patterns"
+id: "test-coverage-unity-anti-patterns"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "Tests/Runtime/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "testing"
+  - "unity"
+  - "anti-patterns"
+  - "nunit"
+
+complexity:
+  level: "basic"
+  reasoning: "Applies Unity-specific test constraints and common pitfalls"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Testing guidance only"
+  maintainability:
+    rating: "high"
+    details: "Avoids invalid or flaky Unity tests"
+  testability:
+    rating: "high"
+    details: "Ensures tests align with Unity Test Framework limitations"
+
+prerequisites:
+  - "Understanding of Unity Test Framework"
+
+dependencies:
+  packages: []
+  skills:
+    - "comprehensive-test-coverage"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - "NUnit"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Unity test rules"
+
+related:
+  - "comprehensive-test-coverage"
+  - "test-coverage-organization-assertions"
+
+status: "stable"
+---
+
+# Unity Test Considerations and Anti-Patterns
+
+> **One-line summary**: Follow Unity-specific testing constraints and avoid common anti-patterns.
+
+## Overview
+
+Unity Test Framework has specific rules: use `[UnityTest]` for coroutine-based tests, avoid `async Task`, and handle `UnityEngine.Object` null checks correctly.
+
+## Problem Statement
+
+Tests that violate Unity constraints fail unpredictably or provide false results.
+
+## Solution
+
+### Test vs UnityTest
+
+```csharp
+[Test]
+public void PureLogicTestWithNoUnityDependencies()
+{
+    MessageBus bus = new MessageBus();
+    Assert.That(bus.HandlerCount, Is.EqualTo(0));
+}
+
+[UnityTest]
+public IEnumerator ComponentRegistersOnStart()
+{
+    GameObject go = new GameObject("Test", typeof(MessageAwareComponent));
+
+    yield return null;
+
+    MessageAwareComponent component = go.GetComponent<MessageAwareComponent>();
+    Assert.That(component.IsRegistered, Is.True);
+
+    Object.DestroyImmediate(go);
+}
+```
+
+### No Async Task Tests
+
+```csharp
+// BAD: Unity doesn't support async Task tests
+[Test]
+public async Task AsyncTestMethod()
+{
+    await SomeAsyncOperation();
+}
+
+// GOOD: IEnumerator with UnityTest
+[UnityTest]
+public IEnumerator OperationCompletesAfterDelay()
+{
+    AsyncOperation operation = StartAsyncOperation();
+
+    while (!operation.IsComplete)
+    {
+        yield return null;
+    }
+
+    Assert.That(operation.Result, Is.Not.Null);
+}
+```
+
+### Testing Exception Throwing
+
+```csharp
+[Test]
+public void ThrowsOnInvalidInput()
+{
+    Assert.Throws<ArgumentNullException>(
+        () => _messageBus.Register(null),
+        "Should throw ArgumentNullException for null handler");
+}
+```
+
+### Proper UnityEngine.Object Null Checks
+
+```csharp
+// BAD: Unity overrides == semantics
+Assert.That(component, Is.Null);
+
+// GOOD: Direct comparison respects Unity null semantics
+Assert.That(component == null, Is.True, "Component should be null");
+Assert.That(gameObject != null, Is.True, "GameObject should exist");
+```
+
+## Anti-Patterns to Avoid
+
+### Don't Use Underscores in Test Names
+
+```csharp
+// BAD
+[Test]
+public void Message_Bus_Should_Handle_Null_Input() { }
+
+// GOOD
+[Test]
+public void MessageBusHandlesNullInput() { }
+```
+
+### Don't Use Regions
+
+```csharp
+// BAD
+#region Happy Path Tests
+[Test]
+public void Test1() { }
+#endregion
+```
+
+### Avoid var - Use Explicit Types
+
+```csharp
+// BAD
+var result = GetSomething();
+
+// GOOD
+MessageRegistrationToken token = messageBus.Register(handler);
+```
+
+### Don't Ignore Test Failures
+
+```csharp
+[Test]
+[Ignore("Flaky")]
+public void SometimesFailingTest() { }
+```
+
+### Don't Use Description Annotations
+
+```csharp
+[Test]
+[Description("Tests that messages are delivered to handlers")]
+public void TestMessageDelivery() { }
+```
+
+### Don't Create Tests Without Assertions
+
+```csharp
+[Test]
+public void CreateMessageBus()
+{
+    MessageBus bus = new MessageBus();
+    // No assertions
+}
+```
+
+## Testing Checklist
+
+- [ ] Happy path tests exist for all new public methods
+- [ ] Negative tests cover null/invalid inputs
+- [ ] Edge cases test boundaries
+- [ ] Unexpected usage is handled gracefully
+- [ ] No underscores in test names
+- [ ] No regions in test code
+- [ ] Explicit types used (avoid var)
+- [ ] Clear failure messages on assertions
+- [ ] IEnumerator used for UnityTest, not async Task
+- [ ] Unity Object null checks use direct comparison
+
+## See Also
+
+- [Comprehensive Test Coverage](comprehensive-test-coverage.md)
+- [Test Organization and Assertions](test-coverage-organization-assertions.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/testing/test-diagnostics-patterns.md

@@ -0,0 +1,189 @@
+---
+title: "Test Diagnostics Patterns"
+id: "test-diagnostics-patterns"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "diagnostics"
+  - "logging"
+  - "debugging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on diagnostic collector usage"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Diagnostics add minor overhead when enabled"
+  maintainability:
+    rating: "high"
+    details: "Improves failure investigation"
+  testability:
+    rating: "high"
+    details: "Makes failures easier to reproduce"
+
+prerequisites:
+  - "Understanding of test diagnostics"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-diagnostics"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+
+aliases:
+  - "Test diagnostics patterns"
+
+related:
+  - "test-diagnostics"
+
+status: "stable"
+---
+
+# Test Diagnostics Patterns
+
+> **One-line summary**: Toggleable diagnostics and edge-case markers for test debugging.
+
+## Overview
+
+This skill documents toggleable diagnostics and edge-case markers.
+
+## Solution
+
+Apply the patterns below to collect targeted diagnostics safely.
+
+### Toggleable Diagnostics Pattern
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Diagnostics
+{
+    using UnityEngine;
+
+    /// <summary>
+    /// Zero-overhead diagnostics with name filtering.
+    /// </summary>
+    internal static class EditorDiagnostics
+    {
+        /// <summary>
+        /// Enable/disable all diagnostics.
+        /// </summary>
+        internal static bool Enabled { get; set; } = false;
+
+        /// <summary>
+        /// Only log for components matching this filter (null = all).
+        /// </summary>
+        internal static string NameFilter { get; set; }
+
+        private const string LogPrefix = "[Diagnostics] ";
+
+        private static bool ShouldLog(string name)
+        {
+            if (!Enabled) return false;
+
+            if (!string.IsNullOrEmpty(NameFilter))
+            {
+                if (name == null) return false;
+                if (name.IndexOf(NameFilter, System.StringComparison.OrdinalIgnoreCase) < 0)
+                    return false;
+            }
+
+            return true;
+        }
+
+        internal static void Log(string name, string message)
+        {
+            if (!ShouldLog(name)) return;
+            Debug.Log($"{LogPrefix}[{name}] {message}");
+        }
+
+        internal static void LogFormat(string name, string format, params object[] args)
+        {
+            if (!ShouldLog(name)) return;
+            Debug.LogFormat($"{LogPrefix}[{name}] {format}", args);
+        }
+
+        internal static void LogStateChange(string name, string from, string to)
+        {
+            if (!ShouldLog(name)) return;
+            Debug.Log($"{LogPrefix}[{name}] State: {from} -> {to}");
+        }
+
+        internal static void LogMethodEntry(string name, string method, string parameters = null)
+        {
+            if (!ShouldLog(name)) return;
+            string msg = string.IsNullOrEmpty(parameters)
+                ? $"-> {method}()"
+                : $"-> {method}({parameters})";
+            Debug.Log($"{LogPrefix}[{name}] {msg}");
+        }
+
+        internal static void LogMethodExit(string name, string method, object result = null)
+        {
+            if (!ShouldLog(name)) return;
+            string msg = result == null
+                ? $"<- {method}()"
+                : $"<- {method}() = {result}";
+            Debug.Log($"{LogPrefix}[{name}] {msg}");
+        }
+    }
+}
+```
+
+### Intentional Edge Case Markers
+
+```csharp
+/// <summary>
+/// Marker comments for test linter to ignore intentional patterns.
+/// </summary>
+public static class TestMarkers
+{
+    // Comment pattern: // UNH-SUPPRESS: <reason>
+    //
+    // Used when tests intentionally do things that would trigger warnings:
+    // - DestroyImmediate in tests
+    // - Null access testing
+    // - Exception testing
+}
+
+// Usage in tests:
+[Test]
+public void GetGameObjectHandlesDestroyedComponent()
+{
+    GameObject go = CreateGameObject("Test");
+    SpriteRenderer sr = go.AddComponent<SpriteRenderer>();
+
+    // UNH-SUPPRESS: Test verifies behavior after intentional destruction
+    Object.DestroyImmediate(sr);
+
+    // Should handle destroyed component gracefully
+    GameObject result = sr.GetGameObject();
+    Assert.IsTrue(result == null);
+}
+
+[Test]
+public void HandleNullGracefully()
+{
+    // UNH-SUPPRESS: Intentional null testing
+    string nullString = null;
+
+    Assert.DoesNotThrow(() => processor.Process(nullString));
+}
+```

package/.llm/skills/testing/test-diagnostics-usage.md

@@ -0,0 +1,196 @@
+---
+title: "Test Diagnostics Usage"
+id: "test-diagnostics-usage"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "diagnostics"
+  - "logging"
+  - "debugging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on diagnostic collector usage"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Diagnostics add minor overhead when enabled"
+  maintainability:
+    rating: "high"
+    details: "Improves failure investigation"
+  testability:
+    rating: "high"
+    details: "Makes failures easier to reproduce"
+
+prerequisites:
+  - "Understanding of test diagnostics"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-diagnostics"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+
+aliases:
+  - "Test diagnostics patterns"
+
+related:
+  - "test-diagnostics"
+
+status: "stable"
+---
+
+# Test Diagnostics Usage
+
+> **One-line summary**: How to apply diagnostics in tests, with performance guidance.
+
+## Overview
+
+This skill explains how to use diagnostics in tests and CI.
+
+## Solution
+
+Follow the guidance below to enable diagnostics without noise.
+
+## Usage
+
+### Using Diagnostics in Tests
+
+```csharp
+[TestFixture]
+public sealed class SpatialQueryTests : CommonTestBase
+{
+    [Test]
+    public void QueryReturnsAllPointsInBounds()
+    {
+        // Enable diagnostics for this test
+        var diagnostics = new SpatialQueryDiagnosticsCollector();
+        tree.SetQueryLogger(diagnostics);
+
+        // Setup
+        var points = new List<Vector3>();
+        for (int i = 0; i < 100; i++)
+        {
+            var point = Random.insideUnitSphere * 10;
+            points.Add(point);
+            tree.Insert(point);
+        }
+
+        // Query
+        Bounds queryBounds = new Bounds(Vector3.zero, Vector3.one * 5);
+        diagnostics.BeginQuery(queryBounds);
+        var results = tree.Query(queryBounds);
+
+        // Calculate expected
+        var expected = points.Where(p => queryBounds.Contains(p)).ToList();
+
+        // Assert with diagnostics on failure
+        if (results.Count != expected.Count)
+        {
+            string report = diagnostics.BuildReport(expected, results);
+            Assert.Fail($"Query returned wrong count.\n\n{report}");
+        }
+
+        Assert.AreEqual(expected.Count, results.Count);
+    }
+}
+```
+
+### Enabling Diagnostics for Debugging
+
+```csharp
+[TestFixture]
+public sealed class StateMachineTests : CommonTestBase
+{
+    [SetUp]
+    public override void CommonSetUp()
+    {
+        base.CommonSetUp();
+
+        // Enable diagnostics for this specific component
+        EditorDiagnostics.Enabled = true;
+        EditorDiagnostics.NameFilter = "PlayerStateMachine";
+    }
+
+    [TearDown]
+    public override void TearDown()
+    {
+        EditorDiagnostics.Enabled = false;
+        EditorDiagnostics.NameFilter = null;
+        base.TearDown();
+    }
+
+    [Test]
+    public void TransitionsCorrectly()
+    {
+        // Now all PlayerStateMachine logs will appear
+        stateMachine.TransitionTo(State.Running);
+    }
+}
+```
+
+## Performance Notes
+
+- **Disabled Diagnostics**: Zero overhead (early return before string formatting)
+- **Enabled Diagnostics**: ~1us per log call
+- **Collectors**: Memory proportional to events collected
+
+## Best Practices
+
+### Do
+
+- Disable diagnostics by default
+- Use collectors for complex algorithms (spatial, pathfinding)
+- Include all relevant context in diagnostic reports
+- Use consistent prefixes for log filtering
+- Document UNH-SUPPRESS markers with reasons
+
+### Don't
+
+- Don't leave diagnostics enabled in production
+- Don't collect unbounded data (limit with maxItems)
+- Don't use diagnostics for simple pass/fail tests
+- Don't suppress warnings without documenting why
+
+### Diagnostic Collector Template
+
+```csharp
+public sealed class MyAlgorithmDiagnostics
+{
+    private readonly List<StepRecord> _steps = new List<StepRecord>();
+
+    public void RecordStep(string description, object state)
+    {
+        _steps.Add(new StepRecord(description, state.ToString()));
+    }
+
+    public string BuildReport()
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("=== ALGORITHM TRACE ===");
+        foreach (var step in _steps)
+        {
+            sb.AppendLine($"[{step.Index}] {step.Description}: {step.State}");
+        }
+        return sb.ToString();
+    }
+}
+```