maestra testcases

docs/research/marionette-spike-usage.md

@@ -0,0 +1,58 @@
+# Marionette MCP Spike — Usage Guide
+
+**Issue:** #533  
+**Purpose:** Document how to run the Marionette MCP spike for auth flows.
+
+## Prerequisites
+
+1. **Marionette MCP server** — Install globally:
+   ```bash
+   dart pub global activate marionette_mcp
+   ```
+
+2. **Add Marionette to Cursor** — In `.cursor/mcp.json` or global config:
+   ```json
+   {
+     "mcpServers": {
+       "marionette": {
+         "command": "marionette_mcp",
+         "args": []
+       }
+     }
+   }
+   ```
+
+3. **Run app in debug mode** — The app must be running with VM Service:
+   ```bash
+   cd apps/mobile && flutter run -d <device_id>
+   ```
+
+4. **Get VM Service URI** — From the `flutter run` output, copy the `ws://127.0.0.1:XXXX/ws` URI (often shown in the DevTools link).
+
+## Spike flows (AI agent prompts)
+
+Use these prompts with the Marionette MCP connected to the running app.
+
+### Client — Login
+
+> Connect to the app using the VM Service URI. Navigate to the Get Started screen, tap "Sign In", enter legendary@krowd.com and Demo2026!, then tap "Sign In". Verify we land on the home screen.
+
+### Client — Sign up
+
+> Connect to the app. Tap "Create Account", fill in Company, Email, Password (and confirm) with new credentials, then tap "Create Account". Verify we land on the home screen.
+
+### Staff — Login
+
+> Connect to the app. Tap "Log In", enter phone number 5557654321, tap "Send Code", enter OTP 123456, tap "Continue". Verify we reach the staff home screen.
+> (Firebase test phone: +1 555-765-4321 / OTP 123456)
+
+### Staff — Sign up
+
+> Connect to the app. Tap "Sign Up", enter a NEW phone number (Firebase test phone), tap "Send Code", enter OTP, tap "Continue". Verify we reach Profile Setup or staff home.
+
+## Limitations observed (from spike)
+
+- **Debug only** — Marionette needs the Dart VM Service; does not work with release builds.
+- **Non-deterministic** — LLM-driven actions can vary in behavior and timing.
+- **Latency** — Each step involves API roundtrips (~45s+ for full flow vs ~5s for Maestro).
+- **Best use** — Exploratory testing, live debugging, smoke checks during development.