com.valectric.mooserunner 2.1.4

package/README.md

@@ -0,0 +1,347 @@
+# MooseRunner (Unity Git Submodule)
+
+This project integrates **[MooseRunner](https://github.com/Valectric/MooseRunner)** as a Unity package using **Git submodules**.  
+Unity detects it as an **embedded package** via its `package.json`.
+
+---
+
+## Why use a submodule?
+
+Instead of copying MooseRunner’s source code directly, we use a **Git submodule** because:
+
+- Keeps MooseRunner’s history and version tracking intact  
+- Easy to update to the latest changes (or pin to a specific commit)  
+- Keeps your repository clean while still embedding MooseRunner as a Unity package  
+- Works seamlessly with Unity’s Package Manager as an **embedded package**
+
+---
+
+## Adding MooseRunner
+
+To add MooseRunner as a submodule in your Unity project:
+
+```bash
+git submodule add https://github.com/Valectric/MooseRunner.git Packages/MooseRunnerGit
+git commit -m "Add MooseRunner as submodule in Packages/MooseRunnerGit"
+```
+
+Then manual add MooseRunner as a pakcage in packagemanager from disk by selecting 
+the package.json in the subfolder MooseRunner
+
+### Important: Enable Test Assemblies
+
+When using MooseRunner as a package, you must add it to the `testables` array in your project's `Packages/manifest.json`:
+
+```json
+{
+  "dependencies": {
+    ...
+  },
+  "testables": [
+    "com.valectric.mooserunner"
+  ]
+}
+```
+
+This ensures Unity includes MooseRunner's test assemblies, allowing the SelectMethod list to properly display all available tests.
+
+---
+
+## Cloning With Submodules
+
+When cloning this repository fresh, make sure to fetch submodules:
+
+```bash
+git clone <your-repo-url>
+cd <your-repo>
+git submodule update --init --recursive
+```
+
+---
+
+## Updating MooseRunner
+
+Update MooseRunner to the latest version:
+
+```bash
+cd Packages/MooseRunnerGit
+git pull origin main
+```
+
+Update all submodules in one go:
+
+```bash
+git submodule update --remote --merge
+```
+
+---
+
+## Listing Submodules
+
+Check the status of submodules (commit SHA and path):
+
+```bash
+git submodule status
+```
+
+List configured submodule URLs:
+
+```bash
+git config --file .gitmodules --get-regexp url
+```
+
+---
+
+## Removing MooseRunner
+
+To completely remove the MooseRunner submodule:
+
+```bash
+git submodule deinit -f Packages/MooseRunnerGit
+git rm -f Packages/MooseRunnerGit
+rm -rf .git/modules/Packages/MooseRunnerGit
+git commit -m "Remove MooseRunner submodule"
+```
+
+---
+
+With this setup, Unity treats MooseRunner as an **embedded package** while Git keeps it synced as a **submodule**.
+
+---
+
+## Claude Code Integration
+
+MooseRunner includes skills for Claude Code that provide comprehensive documentation on writing and running tests.
+
+### Available Skills
+
+Skills are located in `MooseRunner/skills/`:
+
+| Skill | Use Case |
+|-------|----------|
+| **play-mode-tester** | Isolated component tests with SetUp/TearDown |
+| **e2e-tester** | E2E gameplay flow tests (chained, no setup between) |
+
+### Installing Skills
+
+Skills sync automatically via git hooks on checkout/merge.
+
+#### Step 1: Create Hooks Folder
+
+Create a `.githooks/` folder in your project root (tracked by git, unlike `.git/hooks/`):
+
+```bash
+mkdir .githooks
+```
+
+#### Step 2: Copy the Sync Script
+
+```bash
+cp Assets/MooseRunnerGit/MooseRunner/hooks/sync-mooserunner-skills.ps1 .githooks/
+```
+
+**Note:** If MooseRunner is in `Packages/` instead of `Assets/`, edit the script's `$SubmodulePath` parameter.
+
+#### Step 3: Set Up Git Hooks
+
+Copy or create `post-checkout` and `post-merge` in `.githooks/`:
+
+```bash
+cp Assets/MooseRunnerGit/MooseRunner/hooks/post-checkout .githooks/
+cp Assets/MooseRunnerGit/MooseRunner/hooks/post-merge .githooks/
+```
+
+Or add this line to existing hooks:
+
+```bash
+powershell -NoProfile -ExecutionPolicy Bypass -File .githooks/sync-mooserunner-skills.ps1
+```
+
+#### Step 4: Configure Git to Use Tracked Hooks
+
+```bash
+git config core.hooksPath .githooks
+```
+
+> **Tip**: Add this to a setup script so new developers run it once after cloning.
+
+#### Step 5: Run the Sync Script
+
+```powershell
+.\.githooks\sync-mooserunner-skills.ps1
+```
+
+#### Step 6: Update .gitignore
+
+Add the junctioned folders to your `.gitignore`:
+
+```gitignore
+# Skills synced from MooseRunner submodule
+.claude/skills/play-mode-tester/
+.claude/skills/e2e-tester/
+```
+
+#### Step 7: Update settings.json (Optional)
+
+To allow skills to run without permission prompts, add to `.claude/settings.json`:
+
+```json
+"Skill(play-mode-tester)",
+"Skill(e2e-tester)"
+```
+
+### Windows Developer Mode
+
+Junction creation requires Developer Mode on Windows:
+
+**Settings > Update & Security > For developers > Developer Mode**
+
+Without it, skills are copied instead of junctioned (won't auto-update with submodule).
+
+### What the Skills Provide
+
+- **Test Structure Guidelines**: Arrange – Act – Assert – Cleanup pattern
+- **Scene Cleanup Methods**: `DoNotDestroyOnTeardown.CleanSceneImmediate()` and `CleanSceneSafeUsingUpdateAsync()`
+- **MCP Integration**: How to run tests via MCP tools
+- **E2E Test Patterns**: Dynamic loading rules, first-test-method setup, chained execution
+- **Debugging Workflows**: Console analysis and debug logging patterns
+
+### Recommended CLAUDE.md Settings
+
+Add to your project's `CLAUDE.md`:
+
+```markdown
+## Critical Constraints
+- For tests use the `play-mode-tester` skill (isolated tests) or `e2e-tester` skill (E2E gameplay flows). Never run the MCP run_play_mode_test yourself.
+
+## MooseRunner Testing
+
+Deny these MCP tools in `.claude/settings.json` to prevent direct test execution:
+- `mcp__unityMCP__run_tests`
+- `mcp__unityMCP__refresh_unity`
+- `mcp__unityMCP__get_test_job`
+
+Use the skills instead, which handle test execution properly via MooseRunner.
+```
+
+---
+
+## Troubleshooting
+
+### Skills Not Appearing in Claude Code
+- Verify junctions exist: `ls .claude/skills/`
+- Re-run sync script: `.\.git\hooks\sync-mooserunner-skills.ps1`
+- Restart Claude Code after installation
+
+### Junction Creation Failed
+- Enable Developer Mode: Settings > Update & Security > For developers
+- Without Developer Mode, skills are copied (won't auto-update)
+
+### Hook Not Executing on Checkout
+- Verify hook is executable (Git Bash): `chmod +x .git/hooks/post-checkout`
+- Check hooks path: `git config core.hooksPath`
+
+### PowerShell Execution Policy Error
+- Run: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`
+
+---
+
+## AI Installation Guide
+
+If you are an AI assistant installing this for a user:
+
+### Pre-Installation Checks (Silent)
+1. Check if `.claude/skills/` directory exists
+2. Check if hooks folder exists (`.git/hooks` or custom path via `git config core.hooksPath`)
+3. Check if `sync-mooserunner-skills.ps1` already exists in hooks folder
+
+### Installation Notes
+- **Merging**: When updating settings.json, merge new permissions into existing `permissions.allow` array
+- **Existing hooks**: Add sync line to existing post-checkout/post-merge, don't replace entire file
+- **Verification**: After running sync script, verify junctions created with `ls .claude/skills/`
+
+### Questions to Ask User
+- "Do you have a custom hooks path configured?" (if unsure, run `git config core.hooksPath`)
+- "Should I add these skills to your settings.json permissions?"
+
+---
+
+## Optional Components
+
+MooseRunner includes optional utilities. Each component can be installed independently.
+
+### A. MooseRunner Core (Skills + Test CLI)
+
+**What it does:** Test skills for Claude Code + CLI script for long-running tests.
+
+**Why useful:** Skills provide test documentation and patterns. CLI bypasses MCP timeout for long tests.
+
+**Setup:** Follow "Installing Skills" section above.
+
+**CLAUDE.md snippet:**
+```markdown
+## Critical Constraints
+- For tests use the `play-mode-tester` skill (isolated tests) or `e2e-tester` skill (E2E gameplay flows).
+
+## MooseRunner Testing
+Script location: `Assets/MooseRunnerGit/MooseRunner/Editor/MCPForUnityTools/run-moose-test.py`
+
+```bash
+python run-moose-test.py --method Assembly Class Method
+python run-moose-test.py --class Assembly Class
+python run-moose-test.py --assembly Assembly
+```
+```
+
+---
+
+### B. Unity MCP CLI
+
+**What it does:** Command-line interface for Unity MCP tools.
+
+**Why useful:** Avoids MCP reconnection issues. When Unity restarts, MCP connection breaks and requires human `/mcp reconnect`. CLI works via HTTP - no persistent connection needed.
+
+**Installation:**
+```bash
+cd Server  # In unity-mcp repo (https://github.com/CoplayDev/unity-mcp)
+pip install -e .
+```
+
+**Prerequisite:** MCP HTTP server must be running. Use `restart-unity.ps1` from `General-Claude-Code-Skill-And-Agents/Unity_Control/` which handles this automatically.
+
+**Setup:** Unity needs `AutoStartMcpSession` component to connect to MCP server.
+
+**CLAUDE.md snippet:**
+```markdown
+## Unity MCP (CLI Mode)
+
+We use Unity MCP via **CLI** instead of MCP server connection. This avoids reconnection issues when Unity restarts.
+
+### Core Commands
+```bash
+unity-mcp instance list                    # List Unity instances
+unity-mcp editor play|pause|stop           # Control play mode
+unity-mcp editor console                   # Get console logs
+unity-mcp scene hierarchy                  # Get scene hierarchy
+unity-mcp gameobject find "Name"           # Find GameObject
+unity-mcp raw tool_name 'JSON_params'      # Any tool via raw access
+```
+
+Full reference: https://github.com/CoplayDev/unity-mcp/blob/main/docs/guides/CLI_USAGE.md
+```
+
+---
+
+### Why These Components Are Separate
+
+| Component | Purpose | When to Install |
+|-----------|---------|-----------------|
+| **MooseRunner Core** | Test documentation + CLI | Always (for testing) |
+| **Unity MCP CLI** | CLI instead of MCP connection | If Unity restarts break your workflow |
+
+Each component solves a specific problem:
+- **MooseRunner Core**: "How do I write and run tests?"
+- **Unity MCP CLI**: "How do I avoid MCP reconnection issues?"
+
+**Note:** Unity Control Scripts (start/stop/restart Unity) have moved to `General-Claude-Code-Skill-And-Agents/Unity_Control/`.
+

package/Runtime/Helpers/DoNotDestroyOnTeardown/DoNotDestroyOnTeardown.cs

@@ -0,0 +1,262 @@
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEngine;
+using MooseRunner.Internal.Helper;
+using Object = UnityEngine.Object;
+
+namespace MooseRunner.helper
+{
+    /// <summary>
+    /// Tag component that marks a GameObject as protected from test teardown cleanup.
+    /// Provides static cleanup methods for test scenes while preserving protected objects.
+    /// By default, protected objects are: GameObjects with TestRunnerHelper or DoNotDestroyOnTeardown components.
+    /// When includeMarkedObjects is true, only TestRunnerHelper objects are preserved.
+    /// </summary>
+    public class DoNotDestroyOnTeardown : MonoBehaviour
+    {
+        /// <summary>
+        /// When true, logs all GameObjects instead of destroying them.
+        /// Useful for debugging what objects exist in the scene.
+        /// </summary>
+        public static bool DebugLogObjectsOnly = false;
+
+        /// <summary>
+        /// Cleans the scene immediately using DestroyImmediate. Synchronous, no coroutine needed.
+        /// Use in SetUp methods or when immediate cleanup is required.
+        /// TestRunnerHelper objects are always preserved.
+        /// DoNotDestroyOnTeardown-marked objects are preserved by default unless includeMarkedObjects is true.
+        /// Warnings are suppressed during cleanup to avoid RequireComponent circular dependency spam.
+        /// </summary>
+        /// <param name="hiddenObjectsIncluded">If true, includes hidden objects with HideFlags.
+        /// Set to false to prevent SceneView cache issues with lights.</param>
+        /// <param name="includeMarkedObjects">If true, DoNotDestroyOnTeardown-marked objects are also
+        /// destroyed. TestRunnerHelper objects are always preserved regardless of this flag.</param>
+        public static void CleanSceneImmediate(bool hiddenObjectsIncluded = true, bool includeMarkedObjects = false)
+        {
+            GameObject[] visibleObjects = Object.FindObjectsByType<GameObject>(FindObjectsSortMode.None);
+
+            if (DebugLogObjectsOnly)
+            {
+                LogGameObjects(visibleObjects, "Visible Objects", includeMarkedObjects);
+                if (hiddenObjectsIncluded)
+                {
+                    GameObject[] allObjects = Resources.FindObjectsOfTypeAll<GameObject>();
+                    LogGameObjects(allObjects, "All Objects (including hidden)", includeMarkedObjects);
+                }
+                return;
+            }
+
+            // Suppress RequireComponent circular dependency warnings during destruction
+            var previousLogType = Debug.unityLogger.filterLogType;
+            Debug.unityLogger.filterLogType = LogType.Error;
+
+            try
+            {
+                DestroyGameObjectsImmediate(visibleObjects, includeMarkedObjects);
+
+                if (hiddenObjectsIncluded)
+                {
+                    GameObject[] allObjects = Resources.FindObjectsOfTypeAll<GameObject>();
+                    DestroyGameObjectsImmediate(allObjects, includeMarkedObjects);
+                }
+            }
+            finally
+            {
+                Debug.unityLogger.filterLogType = previousLogType;
+            }
+        }
+
+        /// <summary>
+        /// Cleans the scene safely using Destroy (frame-delayed). Use in TearDown contexts.
+        /// TestRunnerHelper objects are always preserved.
+        /// DoNotDestroyOnTeardown-marked objects are preserved by default unless includeMarkedObjects is true.
+        /// Uses two-pass approach: fast pass for visible objects, thorough pass for hidden objects.
+        /// Spans multiple frames: destroy, wait, verify.
+        /// Warnings are suppressed during cleanup to avoid RequireComponent circular dependency spam.
+        /// </summary>
+        /// <param name="hiddenObjectsIncluded">If true, includes hidden objects with HideFlags.
+        /// Set to false to prevent SceneView cache issues with lights.</param>
+        /// <param name="ct">Cancellation token for async operation.</param>
+        /// <param name="includeMarkedObjects">If true, DoNotDestroyOnTeardown-marked objects are also
+        /// destroyed. TestRunnerHelper objects are always preserved regardless of this flag.</param>
+        public static async Task CleanSceneSafeUsingUpdateAsync(
+            bool hiddenObjectsIncluded,
+            CancellationToken ct,
+            bool includeMarkedObjects = false)
+        {
+            // Frame 1: Destroy objects
+            GameObject[] visibleObjects = Object.FindObjectsByType<GameObject>(FindObjectsSortMode.None);
+
+            if (DebugLogObjectsOnly)
+            {
+                LogGameObjects(visibleObjects, "Visible Objects (Async)", includeMarkedObjects);
+                if (hiddenObjectsIncluded)
+                {
+                    GameObject[] allObjects = Resources.FindObjectsOfTypeAll<GameObject>();
+                    LogGameObjects(allObjects, "All Objects including hidden (Async)", includeMarkedObjects);
+                }
+                return;
+            }
+
+            // Suppress RequireComponent circular dependency warnings during destruction
+            var previousLogType = Debug.unityLogger.filterLogType;
+            Debug.unityLogger.filterLogType = LogType.Error;
+
+            try
+            {
+                DestroyGameObjects(visibleObjects, includeMarkedObjects);
+
+                if (hiddenObjectsIncluded)
+                {
+                    GameObject[] allObjects = Resources.FindObjectsOfTypeAll<GameObject>();
+                    DestroyGameObjects(allObjects, includeMarkedObjects);
+                }
+            }
+            finally
+            {
+                Debug.unityLogger.filterLogType = previousLogType;
+            }
+
+            // Frame 2: Wait for destruction
+            await Awaitable.NextFrameAsync(ct);
+
+            // Frame 3: Verify cleanup
+            await Awaitable.NextFrameAsync(ct);
+        }
+
+        /// <summary>
+        /// Checks if a GameObject is excluded from destruction.
+        /// TestRunnerHelper objects are always excluded.
+        /// DoNotDestroyOnTeardown-marked objects are excluded unless includeMarkedObjects is true.
+        /// </summary>
+        /// <param name="go">The GameObject to check.</param>
+        /// <param name="includeMarkedObjects">If true, DoNotDestroyOnTeardown-marked objects
+        /// are NOT excluded (they will be destroyed).</param>
+        /// <returns>True if excluded from destruction, false otherwise.</returns>
+        private static bool IsExcludedGameObject(GameObject go, bool includeMarkedObjects)
+        {
+            // TestRunnerHelper is ALWAYS excluded — never destroyed regardless of flags
+            if (go.GetComponent<TestRunnerHelper>() != null)
+            {
+                return true;
+            }
+
+            // DoNotDestroyOnTeardown excluded only when includeMarkedObjects is false
+            if (!includeMarkedObjects && go.GetComponent<DoNotDestroyOnTeardown>() != null)
+            {
+                return true;
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Checks if a GameObject is an editor-internal object that should never be destroyed.
+        /// This includes Unity's SceneView lights, preview objects, and other editor infrastructure.
+        /// </summary>
+        /// <param name="go">The GameObject to check.</param>
+        /// <returns>True if this is an editor-internal object, false otherwise.</returns>
+        private static bool IsEditorInternalObject(GameObject go)
+        {
+            // Skip objects with DontSave flag (editor-only objects like SceneView lights)
+            if ((go.hideFlags & HideFlags.DontSave) != 0)
+            {
+                return true;
+            }
+
+            // Skip objects in editor-internal scenes (SceneView lighting scenes)
+            if (go.scene.IsValid() && go.scene.name.StartsWith("CustomLightsScene"))
+            {
+                return true;
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Logs all GameObjects with detailed information for debugging.
+        /// </summary>
+        /// <param name="objects">Array of GameObjects to log.</param>
+        /// <param name="category">Category label for the log output.</param>
+        /// <param name="includeMarkedObjects">If true, DoNotDestroyOnTeardown-marked objects
+        /// are shown as WOULD_DESTROY instead of PROTECTED.</param>
+        private static void LogGameObjects(GameObject[] objects, string category, bool includeMarkedObjects)
+        {
+            Debug.Log($"=== {category} ({objects.Length} total) ===");
+
+            foreach (GameObject go in objects)
+            {
+                if (go == null)
+                {
+                    Debug.Log("  [null GameObject]");
+                    continue;
+                }
+
+                string sceneName = go.scene.IsValid() ? go.scene.name : "[no scene]";
+                bool sceneLoaded = go.scene.isLoaded;
+                string parentInfo = go.transform.parent != null ? $"Parent: {go.transform.parent.name}" : "Root";
+                string hideFlags = go.hideFlags.ToString();
+
+                // Get components for additional context
+                var components = go.GetComponents<Component>();
+                string componentNames = string.Join(", ", System.Array.ConvertAll(components, c => c != null ? c.GetType().Name : "null"));
+
+                bool wouldBeExcluded = IsExcludedGameObject(go, includeMarkedObjects);
+                bool wouldBeSkippedParent = go.transform.parent != null;
+                bool wouldBeSkippedScene = !sceneLoaded;
+                bool wouldBeSkippedEditorInternal = IsEditorInternalObject(go);
+
+                string status = "";
+                if (wouldBeExcluded) status += "[PROTECTED] ";
+                if (wouldBeSkippedParent) status += "[HAS_PARENT] ";
+                if (wouldBeSkippedScene) status += "[UNLOADED_SCENE] ";
+                if (wouldBeSkippedEditorInternal) status += "[EDITOR_INTERNAL] ";
+                if (string.IsNullOrEmpty(status)) status = "[WOULD_DESTROY] ";
+
+                Debug.Log($"  {status}{go.name} | Scene: {sceneName} (loaded: {sceneLoaded}) | {parentInfo} | HideFlags: {hideFlags} | Components: [{componentNames}]");
+            }
+
+            Debug.Log($"=== End {category} ===");
+        }
+
+        /// <summary>
+        /// Destroys GameObjects with filtering of excluded GameObjects (frame-delayed).
+        /// </summary>
+        /// <param name="objects">Array of GameObjects to process.</param>
+        /// <param name="includeMarkedObjects">If true, DoNotDestroyOnTeardown-marked objects
+        /// are also destroyed.</param>
+        private static void DestroyGameObjects(GameObject[] objects, bool includeMarkedObjects)
+        {
+            foreach (GameObject go in objects)
+            {
+                if (go == null) continue;
+                if (go.transform.parent != null) continue;
+                if (!go.scene.isLoaded) continue;
+                if (IsExcludedGameObject(go, includeMarkedObjects)) continue;
+                if (IsEditorInternalObject(go)) continue;
+
+                Object.Destroy(go);
+            }
+        }
+
+        /// <summary>
+        /// Destroys GameObjects immediately with filtering of excluded GameObjects.
+        /// </summary>
+        /// <param name="objects">Array of GameObjects to process.</param>
+        /// <param name="includeMarkedObjects">If true, DoNotDestroyOnTeardown-marked objects
+        /// are also destroyed.</param>
+        private static void DestroyGameObjectsImmediate(GameObject[] objects, bool includeMarkedObjects)
+        {
+            foreach (GameObject go in objects)
+            {
+                if (go == null) continue;
+                if (go.transform.parent != null) continue;
+                if (!go.scene.isLoaded) continue;
+                if (IsExcludedGameObject(go, includeMarkedObjects)) continue;
+                if (IsEditorInternalObject(go)) continue;
+
+                Object.DestroyImmediate(go);
+            }
+        }
+    }
+}

package/Runtime/Helpers/DoNotDestroyOnTeardown/DoNotDestroyOnTeardown.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 4594a5f81e5beaa45b83fc17373526cc

package/Runtime/Helpers/DoNotDestroyOnTeardown/MooseRunner.helper.asmdef

@@ -0,0 +1,18 @@
+{
+  "name": "MooseRunner.helper",
+  "rootNamespace": "MooseRunner.helper",
+  "references": [
+    "UniTask",
+    "MooseRunner.Runtime"
+  ],
+  "includePlatforms": [],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "precompiledReferences": [
+    "nunit.framework.dll"
+  ],
+  "autoReferenced": false,
+  "defineConstraints": [],
+  "versionDefines": [],
+  "noEngineReferences": false
+}

package/Runtime/Helpers/DoNotDestroyOnTeardown/MooseRunner.helper.asmdef.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 4e4df4892916ee748934a507e8875051
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Runtime/MooseRunner.Helpers.Runtime.dll.meta

@@ -0,0 +1,27 @@
+fileFormatVersion: 2
+guid: 4b0d06f854cbfcb0fa36cc3d79c7e1b0
+PluginImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  iconMap: {}
+  executionOrder: {}
+  defineConstraints: []
+  isPreloaded: 0
+  isOverridable: 1
+  isExplicitlyReferenced: 0
+  validateReferences: 0
+  platformData:
+  - first:
+      Any:
+    second:
+      enabled: 1
+      settings: {}
+  - first:
+      Editor: Editor
+    second:
+      enabled: 1
+      settings:
+        DefaultValueInitialized: true
+  userData:
+  assetBundleName:
+  assetBundleVariant: