com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

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

@@ -0,0 +1,247 @@
+---
+title: "Test Diagnostics and Investigation Patterns"
+id: "test-diagnostics"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/SpatialDiagnosticsCollector.cs"
+    - path: "Runtime/Core/Diagnostics/WGroupIndentDiagnostics.cs"
+      lines: "24-130"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "diagnostics"
+  - "debugging"
+  - "logging"
+  - "investigation"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of diagnostic patterns and test investigation"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Diagnostics disabled by default; zero overhead when off"
+  maintainability:
+    rating: "high"
+    details: "Helps understand complex test failures"
+  testability:
+    rating: "high"
+    details: "Enables deep investigation of failing tests"
+
+prerequisites:
+  - "Understanding of debugging techniques"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Test logging"
+  - "Diagnostic collector"
+  - "Test investigation"
+
+related:
+  - "test-base-class-cleanup"
+  - "test-categories"
+  - "test-diagnostics-patterns"
+  - "test-diagnostics-usage"
+
+status: "stable"
+---
+
+# Test Diagnostics and Investigation Patterns
+
+> **One-line summary**: Implement diagnostic collectors and toggleable logging to understand complex test failures without polluting normal test output.
+
+## Overview
+
+When tests fail in complex systems (spatial queries, state machines, algorithms), stack traces aren't enough. This pattern provides:
+
+1. **Diagnostic Collectors**: Record detailed execution traces
+1. **Toggleable Diagnostics**: Zero overhead when disabled
+1. **Filtered Logging**: Focus on specific components
+1. **Investigation Markers**: Document intentional edge cases
+
+## Problem Statement
+
+```csharp
+// BAD: Test fails with unhelpful message
+[Test]
+public void SpatialQueryReturnsNearbyObjects()
+{
+    tree.Insert(point1);
+    tree.Insert(point2);
+    // ...
+    var results = tree.Query(bounds);
+
+    Assert.AreEqual(5, results.Count); // Fails: Expected 5, got 3
+    // WHY? Which points were missed? What did the query visit?
+}
+```
+
+## Solution
+
+### Diagnostic Collector Pattern
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Tests.Diagnostics
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Text;
+    using UnityEngine;
+
+    /// <summary>
+    /// Records detailed trace of spatial query execution for debugging.
+    /// </summary>
+    public sealed class SpatialQueryDiagnosticsCollector : IOctTreeQueryLogger
+    {
+        public struct NodeVisit
+        {
+            public Bounds NodeBounds;
+            public int PointCount;
+            public bool FullyContained;
+            public bool Intersects;
+            public VisitResult Result;
+        }
+
+        public enum VisitResult { Skipped, Partial, Full }
+
+        private readonly List<NodeVisit> _nodeVisits = new List<NodeVisit>(64);
+        private readonly List<Vector3> _pointsEvaluated = new List<Vector3>(128);
+        private readonly List<Vector3> _pointsIncluded = new List<Vector3>(64);
+        private readonly List<Vector3> _pointsExcluded = new List<Vector3>(64);
+        private Bounds _queryBounds;
+
+        public void BeginQuery(Bounds queryBounds)
+        {
+            _queryBounds = queryBounds;
+            _nodeVisits.Clear();
+            _pointsEvaluated.Clear();
+            _pointsIncluded.Clear();
+            _pointsExcluded.Clear();
+        }
+
+        public void LogNodeVisit(Bounds nodeBounds, int pointCount, bool fullyContained, bool intersects, VisitResult result)
+        {
+            _nodeVisits.Add(new NodeVisit
+            {
+                NodeBounds = nodeBounds,
+                PointCount = pointCount,
+                FullyContained = fullyContained,
+                Intersects = intersects,
+                Result = result
+            });
+        }
+
+        public void LogPointEvaluated(Vector3 point, bool included)
+        {
+            _pointsEvaluated.Add(point);
+            if (included)
+                _pointsIncluded.Add(point);
+            else
+                _pointsExcluded.Add(point);
+        }
+
+        /// <summary>
+        /// Build a detailed report for test failure investigation.
+        /// </summary>
+        public string BuildReport(
+            ICollection<Vector3> expected,
+            ICollection<Vector3> actual,
+            int maxItems = 32)
+        {
+            StringBuilder sb = new StringBuilder(2048);
+
+            sb.AppendLine("=== SPATIAL QUERY DIAGNOSTICS ===");
+            sb.AppendLine();
+            sb.AppendLine($"Query Bounds: {_queryBounds}");
+            sb.AppendLine($"Expected Count: {expected.Count}");
+            sb.AppendLine($"Actual Count: {actual.Count}");
+            sb.AppendLine();
+
+            // Missing points
+            var missing = new HashSet<Vector3>(expected);
+            foreach (var p in actual) missing.Remove(p);
+
+            if (missing.Count > 0)
+            {
+                sb.AppendLine($"MISSING POINTS ({missing.Count}):");
+                int shown = 0;
+                foreach (var p in missing)
+                {
+                    if (shown++ >= maxItems) { sb.AppendLine("  ..."); break; }
+                    bool inBounds = _queryBounds.Contains(p);
+                    sb.AppendLine($"  {p} (in bounds: {inBounds})");
+                }
+                sb.AppendLine();
+            }
+
+            // Extra points
+            var extra = new HashSet<Vector3>(actual);
+            foreach (var p in expected) extra.Remove(p);
+
+            if (extra.Count > 0)
+            {
+                sb.AppendLine($"EXTRA POINTS ({extra.Count}):");
+                int shown = 0;
+                foreach (var p in extra)
+                {
+                    if (shown++ >= maxItems) { sb.AppendLine("  ..."); break; }
+                    sb.AppendLine($"  {p}");
+                }
+                sb.AppendLine();
+            }
+
+            // Node visit summary
+            sb.AppendLine($"NODE VISITS ({_nodeVisits.Count}):");
+            int skipped = 0, partial = 0, full = 0;
+            foreach (var visit in _nodeVisits)
+            {
+                switch (visit.Result)
+                {
+                    case VisitResult.Skipped: skipped++; break;
+                    case VisitResult.Partial: partial++; break;
+                    case VisitResult.Full: full++; break;
+                }
+            }
+            sb.AppendLine($"  Skipped: {skipped}, Partial: {partial}, Full: {full}");
+            sb.AppendLine();
+
+            // Sample node visits
+            sb.AppendLine("SAMPLE NODE VISITS:");
+            for (int i = 0; i < Math.Min(6, _nodeVisits.Count); i++)
+            {
+                var v = _nodeVisits[i];
+                sb.AppendLine($"  [{v.Result}] points={v.PointCount} contained={v.FullyContained} intersects={v.Intersects}");
+            }
+
+            return sb.ToString();
+        }
+    }
+}
+```
+
+## Related Patterns
+
+- [Test Base Class Cleanup](./test-base-class-cleanup.md) - Test infrastructure
+- [Test Categories](./test-categories.md) - Organizing diagnostic tests
+- [Test Diagnostics Patterns](./test-diagnostics-patterns.md) - Toggleable and edge-case diagnostics
+- [Test Diagnostics Usage](./test-diagnostics-usage.md) - Applying diagnostics in tests

package/.llm/skills/testing/test-failure-investigation-procedure.md

@@ -0,0 +1,216 @@
+---
+title: "Test Failure Investigation Procedure"
+id: "test-failure-investigation-procedure"
+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"
+  - "investigation"
+  - "procedure"
+  - "debugging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires disciplined investigation and data gathering"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Investigation process; no runtime impact"
+  maintainability:
+    rating: "critical"
+    details: "Systematic investigation prevents regressions"
+  testability:
+    rating: "critical"
+    details: "Keeps test suite reliable"
+
+prerequisites:
+  - "Understanding of debugging techniques"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-failure-investigation"
+    - "test-diagnostics"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Test investigation steps"
+
+related:
+  - "test-failure-investigation"
+  - "test-failure-investigation-root-causes"
+  - "test-diagnostics"
+
+status: "stable"
+---
+
+# Test Failure Investigation Procedure
+
+> **One-line summary**: Follow a repeatable investigation process before making any fix.
+
+## Overview
+
+A structured process ensures you identify the real root cause rather than masking symptoms.
+
+## Problem Statement
+
+Ad-hoc fixes often hide underlying issues and produce flaky tests.
+
+## Solution
+
+### Step 1: Reproduce the Failure
+
+Ensure the failure can be reproduced reliably.
+
+```csharp
+// Run the specific failing test multiple times
+// Unity: Window > Test Runner > Right-click test > Run
+// CLI: dotnet test --filter "FullyQualifiedName=Namespace.TestClass.TestMethod"
+
+for i in {1..100}; do
+    echo "Run $i"
+    dotnet test --filter "TestName" || echo "FAILED on run $i"
+done
+```
+
+### Step 2: Understand the Expected Behavior
+
+Document what the test is verifying:
+
+1. What production behavior is being tested?
+1. What are the preconditions?
+1. What is the expected outcome?
+1. Why does this matter to users?
+
+### Step 3: Analyze the Failure
+
+Add diagnostic output to capture actual state at failure.
+
+```csharp
+[Test]
+public void MessageRoutedToCorrectHandler()
+{
+    MessageBus bus = new MessageBus();
+    TestHandler handler1 = new TestHandler();
+    TestHandler handler2 = new TestHandler();
+
+    bus.RegisterTargeted<TestMessage>(handler1, targetId1);
+    bus.RegisterTargeted<TestMessage>(handler2, targetId2);
+
+    bus.SendTargeted(targetId1, new TestMessage());
+
+    UnityEngine.Debug.Log($"Handler1 received: {handler1.ReceivedCount}, Handler2 received: {handler2.ReceivedCount}");
+    UnityEngine.Debug.Log($"Target1: {targetId1}, Target2: {targetId2}");
+    UnityEngine.Debug.Log($"Bus registration count: {bus.GetRegistrationCount()}");
+
+    Assert.AreEqual(1, handler1.ReceivedCount,
+        $"Handler1 should receive exactly 1 message. Target1={targetId1}, Handler1Id={handler1.Id}");
+    Assert.AreEqual(0, handler2.ReceivedCount,
+        $"Handler2 should receive no messages. Target2={targetId2}, Handler2Id={handler2.Id}");
+}
+```
+
+### Step 4: Investigate Production Code
+
+Read the code path the test exercises:
+
+- Check initialization order and assumptions
+- Inspect thread-safety and shared state
+- Identify edge cases the test might trigger
+
+### Step 5: Identify Root Cause
+
+Categorize the failure:
+
+| Category              | Description                         | Example                           |
+| --------------------- | ----------------------------------- | --------------------------------- |
+| **Production Bug**    | Code doesn't behave as intended     | Race condition in message routing |
+| **Test Bug**          | Test has incorrect expectations     | Wrong expected value              |
+| **Test Setup Bug**    | Test doesn't set up state correctly | Missing initialization            |
+| **Order Dependency**  | Test depends on execution order     | Shared static state               |
+| **Timing Issue**      | Test has race conditions            | Async operation not awaited       |
+| **Environment Issue** | Test depends on environment         | File paths, time zones            |
+
+### Step 6: Fix Comprehensively
+
+Fix the actual problem, not the symptom:
+
+```csharp
+// Fix production code for race conditions
+public void Register(IHandler handler)
+{
+    lock (_registrationLock)
+    {
+        _handlers.Add(handler);
+    }
+}
+
+// Fix test expectation after investigation
+[Test]
+public void UnregisteredHandlerReceivesNoMessages()
+{
+    handler.Unregister();
+    bus.Send(new TestMessage());
+
+    Assert.AreEqual(0, handler.ReceivedCount,
+        "Handler should receive no messages after Unregister() returns");
+}
+```
+
+### Step 7: Verify the Fix
+
+- Run the fixed test repeatedly (10x or more)
+- Run related tests to ensure no regressions
+- Run the full suite before committing
+
+```bash
+for i in {1..50}; do dotnet test --filter "TestName" || exit 1; done
+```
+
+### Step 8: Document Findings
+
+Record edge cases or behavior clarifications in code comments or docs.
+
+```csharp
+/// <remarks>
+/// Investigation (2026-01-22): This test was failing intermittently due to
+/// a race condition in handler registration. The fix ensures registration
+/// is atomic. Message delivery order now matches registration order.
+/// </remarks>
+[Test]
+public void HandlersReceiveMessagesInRegistrationOrder()
+{
+    // ...
+}
+```
+
+## See Also
+
+- [Test Failure Investigation](test-failure-investigation.md)
+- [Root Causes and Anti-Patterns](test-failure-investigation-root-causes.md)
+- [Test Diagnostics](test-diagnostics.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/testing/test-failure-investigation-root-causes.md

@@ -0,0 +1,186 @@
+---
+title: "Test Failure Root Causes and Anti-Patterns"
+id: "test-failure-investigation-root-causes"
+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"
+  - "root-cause-analysis"
+  - "anti-patterns"
+  - "flaky-tests"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires identifying patterns that produce flaky behavior"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Investigation guidance only"
+  maintainability:
+    rating: "critical"
+    details: "Preventing flaky tests keeps the suite trustworthy"
+  testability:
+    rating: "critical"
+    details: "Improves determinism across tests"
+
+prerequisites:
+  - "Understanding of debugging techniques"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-failure-investigation"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Flaky test causes"
+
+related:
+  - "test-failure-investigation"
+  - "test-failure-investigation-procedure"
+
+status: "stable"
+---
+
+# Test Failure Root Causes and Anti-Patterns
+
+> **One-line summary**: Identify common root causes of flaky tests and avoid anti-patterns that hide failures.
+
+## Overview
+
+Most flaky failures fall into a few categories. This guide helps you recognize the pattern and apply the right fix.
+
+## Problem Statement
+
+Treating symptoms instead of causes leads to recurring failures and unreliable CI results.
+
+## Solution
+
+### Timing and Race Conditions
+
+**Symptom**: Test passes locally, fails in CI.
+
+**Investigation**:
+
+- Look for async operations without synchronization
+- Check callbacks that may fire before assertions
+- Inspect thread safety of shared resources
+
+**Fix**:
+
+```csharp
+// BAD: Race between Send and assertion
+bus.SendAsync(message);
+Assert.IsTrue(handler.Received);
+
+// GOOD: Proper synchronization
+bus.Send(message);
+Assert.IsTrue(handler.Received);
+```
+
+### Shared State Between Tests
+
+**Symptom**: Test passes alone, fails with others.
+
+**Fix**:
+
+```csharp
+public class MessageBusTests
+{
+    private MessageBus _bus;
+
+    [SetUp]
+    public void SetUp()
+    {
+        _bus = new MessageBus();
+    }
+
+    [TearDown]
+    public void TearDown()
+    {
+        _bus.Dispose();
+    }
+}
+```
+
+### Order Dependencies
+
+**Symptom**: Tests fail when executed in a different order.
+
+**Fix**: Ensure each test is fully self-contained with no shared static state.
+
+### Unity-Specific Issues
+
+**Symptom**: Test fails only in PlayMode or only in EditMode.
+
+**Fix**:
+
+```csharp
+[UnityTest]
+public IEnumerator ComponentInitializesCorrectly()
+{
+    GameObject go = new GameObject("Test");
+    TestComponent component = go.AddComponent<TestComponent>();
+
+    yield return null;
+
+    Assert.IsTrue(component.IsInitialized,
+        "Component should be initialized after Start()");
+
+    Object.Destroy(go);
+}
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                                 | Why It's Bad                       | What To Do Instead              |
+| -------------------------------------------- | ---------------------------------- | ------------------------------- |
+| `Thread.Sleep()` / `WaitForSeconds()` as fix | Masks timing bugs, slows tests     | Fix the race condition properly |
+| `[Ignore]` attribute                         | Hides real bugs                    | Fix or remove the test          |
+| Retry loops                                  | Masks intermittent failures        | Find and fix root cause         |
+| `try/catch` swallowing                       | Hides exceptions                   | Let exceptions propagate        |
+| "Works on my machine"                        | Different environments expose bugs | Fix for all environments        |
+| Increasing timeouts                          | Slows test suite, masks issues     | Fix the underlying timing       |
+| Deleting failing tests                       | Loses coverage                     | Fix the test                    |
+
+## Investigation Checklist
+
+- [ ] Can I reproduce the failure reliably?
+- [ ] Do I understand the behavior the test verifies?
+- [ ] Have I inspected actual vs expected values?
+- [ ] Have I read the production code path being tested?
+- [ ] Is this a production bug or a test bug?
+- [ ] Are there shared state or order dependencies?
+- [ ] Are there timing/race issues?
+- [ ] Does the fix address the root cause?
+- [ ] Have I run the test multiple times after fixing?
+
+## See Also
+
+- [Test Failure Investigation](test-failure-investigation.md)
+- [Investigation Procedure](test-failure-investigation-procedure.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |