From 609c57d0bb76af7a3e7713fa7e09d4688708a02d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 27 Jul 2025 15:13:49 +0200
Subject: [PATCH] Document proper macOS test execution requirements

- Add critical note that macOS tests must use XcodeBuildMCP
- Warn against using swift test which causes crashes
- Explain UserNotifications framework requires Xcode environment
- Add examples of correct test commands
---
 mac/CLAUDE.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/mac/CLAUDE.md b/mac/CLAUDE.md
index 35c26105..ede708e9 100644
--- a/mac/CLAUDE.md
+++ b/mac/CLAUDE.md
@@ -259,7 +259,25 @@ log stream --predicate 'subsystem == "sh.vibetunnel.vibetunnel" AND category ==
 - Server logs (Node.js output) are under the "ServerOutput" category
 - Look for `[CLIENT:*]` prefix to identify frontend-originated logs
 
-## Testing the Web Interface
+## Testing
+
+### Running macOS Tests
+
+**IMPORTANT**: macOS tests MUST be run using Xcode commands (XcodeBuildMCP), NOT with `swift test`:
+- Use XcodeBuildMCP test commands like `test_macos_ws` or `test_macos_proj`
+- Running tests with `swift test` will cause crashes, especially with UserNotifications framework
+- The test environment requires proper Xcode configuration and entitlements
+
+Example:
+```
+# CORRECT - Use XcodeBuildMCP:
+test_macos_ws(workspacePath: "/path/to/VibeTunnel.xcworkspace", scheme: "VibeTunnelTests")
+
+# WRONG - Do NOT use:
+swift test
+```
+
+### Testing the Web Interface
 
 The VibeTunnel server runs on localhost:4020 by default. To test the web interface: