Copilot instructions

1---
2description: "Comprehensive guide for working with the .NET MAUI Sandbox app for testing, validation, and experimentation"
3applyTo: "src/Controls/samples/Controls.Sample.Sandbox/**"
4---
5 
6# Sandbox Testing Guide
7 
8Comprehensive guide for working with the .NET MAUI Sandbox app for manual testing, PR validation, issue reproduction, and experimentation with MAUI features.
9 
10## When This Applies
11 
12This guide applies when you:
13- Work with files in `src/Controls/samples/Controls.Sample.Sandbox/`
14- User asks to "test this PR" or "validate PR #XXXXX" in Sandbox
15- User asks to "reproduce issue #XXXXX" in Sandbox
16- User wants to deploy to iOS/Android for manual testing
17- User mentions Sandbox app by name in testing context
18 
19## 🚨 CRITICAL VALIDATION RULES - READ FIRST
20 
21**YOU MUST FOLLOW THESE RULES WHEN RUNNING SANDBOX TESTS:**
22 
23### What You NEVER Do (Absolute Rules)
24 
25- ❌ **NEVER** assume test completion without validation
26- ❌ **NEVER** claim success based on HTTP 200 responses alone (element found ≠ test completed)
27- ❌ **NEVER** skip the mandatory validation checklist
28- ❌ **NEVER** proceed without verifying device logs show expected behavior
29- ❌ **NEVER** assume Appium connection means test finished
30- ❌ **NEVER** claim button was tapped without checking device logs
31- ❌ **NEVER** switch branches (e.g., `git checkout main`) during reproduction - stay on current branch
32 
33### What You ALWAYS Do (Mandatory Steps)
34 
35- ✅ **ALWAYS** save full output to file for analysis
36- ✅ **ALWAYS** check for errors/exceptions FIRST before claiming success
37- ✅ **ALWAYS** verify "Test completed" marker appears in output
38- ✅ **ALWAYS** verify expected test actions in logs (Tapping, Screenshot, etc.)
39- ✅ **ALWAYS** check device logs for Console.WriteLine markers (e.g., "SANDBOX: ...")
40- ✅ **ALWAYS** verify artifacts exist (screenshots, if test captures them)
41 
42### Rule 1: NEVER ASSUME TEST COMPLETION
43- ❌ **DO NOT** assume the test completed successfully just because Appium connected
44- ❌ **DO NOT** assume success based on HTTP 200 responses (element found ≠ test completed)
45- ✅ **DO** verify test completion by checking for completion markers in output
46- ✅ **DO** search for "Test completed", "═══════", or final summary messages
47 
48### Rule 2: ALWAYS VALIDATE TEST OUTPUT
49After running BuildAndRunSandbox.ps1, you MUST:
501. **Save full output to file**: `pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios > CustomAgentLogsTmp/Sandbox/build-run-output.log 2>&1`
512. **Check for errors FIRST**: `grep -E "ERROR|Exception|failed" CustomAgentLogsTmp/Sandbox/build-run-output.log`
523. **Verify completion markers**: `grep "Test completed\|══════" CustomAgentLogsTmp/Sandbox/build-run-output.log`
534. **Check for expected actions**: `grep "Tapping\|Screenshot saved\|switched to" CustomAgentLogsTmp/Sandbox/build-run-output.log`
54 
55### Rule 3: VALIDATE DEVICE LOGS FOR EXPECTED BEHAVIOR
56- ✅ **DO** check device logs confirm your expected test actions happened
57- ✅ **DO** grep for your Console.WriteLine markers (e.g., "SANDBOX.*CLICKED")
58- ❌ **DO NOT** claim the test worked without verifying device logs show the action
59 
60### Rule 4: SYSTEMATIC VALIDATION CHECKLIST
61After EVERY test run, verify ALL of these **IN THIS ORDER**:
62 
63```bash
64# Step 1: Check for errors/exceptions FIRST
65grep -iE "error|exception|failed" CustomAgentLogsTmp/Sandbox/build-run-output.log | grep -v "no such element" | head -20
66 
67# Step 2: Verify expected test actions (MOST IMPORTANT - proves test actually ran)
68grep -E "Tapping|Screenshot saved|Found.*element|Clicking|Entering text" CustomAgentLogsTmp/Sandbox/build-run-output.log
69 
70# Step 3: Verify test completion marker
71grep "Test completed" CustomAgentLogsTmp/Sandbox/build-run-output.log
72 
73# Step 4: Verify device logs show expected behavior
74grep "SANDBOX" CustomAgentLogsTmp/Sandbox/android-device.log  # or ios-device.log
75 
76# Step 5: Check screenshots were saved (if test captures them)
77ls -lh CustomAgentLogsTmp/Sandbox/*.png
78 
79# Step 6: Check exit code
80echo $?  # Should be 0 for success
81```
82 
83**CRITICAL**: If Step 2 shows NO test actions, the test didn't actually run even if it "completed successfully". Update your Appium test and rerun.
84 
85**If ANY of these checks fail, the test DID NOT complete successfully. Investigate and fix before proceeding.**
86 
87---
88 
89## 🚨 WARNING: "Test Completed Successfully" ≠ Test Actually Worked
90 
91**CRITICAL UNDERSTANDING**: The message "✅ Test completed successfully" only means:
92- ✅ Appium test script finished running without crashing
93- ✅ Script exit code was 0
94 
95**It does NOT mean**:
96- ❌ Appium found your UI elements
97- ❌ Buttons were clicked
98- ❌ Navigation happened
99- ❌ Your test scenario actually ran
100 
101### Example of False Success
102 
103**What you see in output**:
104```
105✅ Test completed successfully
106 
107╔═══════════════════════════════════════════════════════════╗
108║                    Test Summary                           ║
109╠═══════════════════════════════════════════════════════════╣
110║  Platform:     ANDROID                                    ║
111║  Device:       emulator-5554                              ║
112║  Result:       SUCCESS ✅                                 ║
113╚═══════════════════════════════════════════════════════════╝
114```
115 
116**What actually happened**:
117```bash
118# Check the logs:
119grep "no such element" CustomAgentLogsTmp/Sandbox/build-run-output.log
120# Result: 20+ lines of "no such element" errors
121 
122# The test looked for "InstructionLabel" which doesn't exist in MainPage
123# Appium never found ANY elements
124# Test script just gave up and exited with code 0
125# NO ACTUAL TESTING WAS PERFORMED
126```
127 
128### How to Detect False Success
129 
130**MANDATORY check after EVERY "successful" test**:
131```bash
132# Look for actual test actions in output
133grep -E "Tapping|Clicking|Found element|Screenshot saved" CustomAgentLogsTmp/Sandbox/build-run-output.log
134```
135 
136**If grep returns NOTHING → FALSE SUCCESS**:
137- Test didn't actually do anything
138- Template test is looking for elements that don't exist
139- You MUST update `CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs` to match your MainPage
140- Rerun BuildAndRunSandbox.ps1 after updating test
141 
142**If grep returns multiple lines → REAL SUCCESS**:
143- Test found elements and interacted with them
144- Proceed with full validation checklist
145 
146---
147 
148## Purpose
149 
150Work with the Sandbox app for manual testing, PR validation, issue reproduction, and experimentation with MAUI features.
151 
152## When to Use Sandbox Testing
153 
154- ✅ User asks to "test this PR" (functional testing, not code review)
155- ✅ User asks to "validate PR #XXXXX" or "validate PR #XXXXX in Sandbox"
156- ✅ User asks to "reproduce issue #XXXXX" or "try out issue #XXXXX"
157- ✅ User asks to "try out" or "experiment with" a feature in Sandbox
158- ✅ PR modifies core MAUI functionality (controls, layouts, platform code)
159- ✅ Need to manually verify a fix works on device/simulator
160- ✅ Need to create a quick test scenario for hands-on validation
161 
162## When NOT to Use Sandbox
163 
164- ❌ User asks to "review PR #XXXXX" → Use **pr** agent for code review
165- ❌ User asks to "write tests" or "create automated tests" → Use **write-tests-agent**
166- ❌ User asks to "validate the UI tests" or "verify test quality" → Review test code instead
167- ❌ User asks to "fix issue #XXXXX" (no PR exists) → Suggest `/delegate` command
168- ❌ PR only adds documentation (no code changes to test)
169- ❌ PR only modifies build scripts (no functional changes)
170 
171## Distinction: Code Review vs. Functional Testing
172 
173**Code Review** (pr-review skill):
174- Analyzes code quality, patterns, best practices
175- Reviews test coverage and correctness
176- Checks for potential bugs or issues in the code itself
177- Trigger: "review PR", "work on PR"
178 
179**Functional Testing** (sandbox-agent):
180- Builds and deploys PR to device/simulator
181- Manually validates the fix works as expected
182- Reproduces issues and verifies they're resolved
183- Trigger: "test this PR", "validate PR in Sandbox", "reproduce issue"
184 
185## 🚨 Critical Requirements for Android Testing
186 
187**ANDROID-ONLY REQUIREMENT - appium:noReset**
188 
189⚠️ **This ONLY applies to Android, NOT iOS**
190 
191When testing on Android, the Appium test script **MUST** have this capability:
192 
193```csharp
194// ANDROID ONLY - Do NOT add this for iOS
195if (PLATFORM == "android")
196{
197    options.AddAdditionalAppiumOption("appium:noReset", true);
198}
199```
200 
201**Why this is critical for Android:**
202- Without `noReset`, Appium clears app data between runs
203- This breaks .NET MAUI's Fast Deployment mechanism on Android
204- App crashes with: `"No assemblies found in '.../__override__/...' ... Assuming this is part of Fast Deployment. Exiting..."`
205- The app will crash immediately on launch before any test can run
206 
207**iOS does NOT need this** - iOS deployment works differently and doesn't use Fast Deployment
208 
209**Where to set it:**
210- Template: `.github/scripts/templates/RunWithAppiumTest.template.cs` (line ~68, Android section only)
211- Active test: `CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs` (Android section only)
212 
213**Platform detection is automatic** - The template automatically detects Android vs iOS from the UDID format, so you don't need to manually set the platform. The `if (PLATFORM == "android")` block will execute automatically when testing on Android.
214 
215**⚠️ NEVER REMOVE THIS CAPABILITY FROM ANDROID** - All Android tests depend on it
216 
217---
218 
219## Core Workflow
220 
221**🚨 CRITICAL RULES FOR ENTIRE WORKFLOW:**
222- **ALWAYS use BuildAndRunSandbox.ps1 script** for building, deploying, and testing
223- **NEVER use manual `dotnet build`, `adb`, or `xcrun` commands**
224- **NEVER switch branches during reproduction** - stay on the current branch
225- **ALWAYS stop and ask user if you cannot reproduce** - do not try alternative branches
226- The script handles device detection, build, deployment, and test execution automatically
227- See "BuildAndRunSandbox.ps1 Script" section below for full details
228 
229---
230 
231### Step 1: Understand Issue (DO NOT Checkout PR Unless Instructed)
232 
233**⚠️ IMPORTANT**: Only checkout a PR if the user explicitly asks you to test a specific PR. For general issue reproduction, work on the current branch.
234 
235```bash
236# ONLY if user explicitly asks to test a PR:
237gh pr checkout <PR_NUMBER>
238```
239 
240**Understand the issue thoroughly:**
241- Read issue report or PR description
242- Identify what bug needs to be reproduced
243- Note affected platforms
244- Look for reproduction steps in the issue
245- If testing a PR: Review PR changes to understand the fix
246 
247---
248 
249### Step 2: Create Test Scenario in Sandbox
250 
251**Choose test scenario source (in priority order):**
252 
2531. **From Issue Reproduction** (Preferred)
254   - Look for "Reproduction" or "Steps to Reproduce" in the linked issue
255   - Use the exact scenario the user reported
256   - This proves you're testing what the user experienced
257 
2582. **From PR's UI Tests** (Alternative)
259   - Check if PR includes files in `TestCases.HostApp/Issues/IssueXXXXX.*`
260   - Adapt the test page code to Sandbox
261   - Simplify if needed for manual testing
262 
2633. **Create Your Own** (Last Resort)
264   - If no repro available, design scenario based on PR changes
265   - Focus on the specific code paths modified by the fix
266   - Keep it simple and focused
267 
268**Files to modify**:
269- `src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml[.cs]` - UI and code for reproduction
270- `CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs` - Appium test script (MANDATORY - see setup below)
271 
272**Setting up the Appium test file (MANDATORY):**
273 
274🚨 **CRITICAL**: Update Appium test BEFORE running script. Template will give FALSE SUCCESS otherwise.
275 
2761. **Create test file**:
277```bash
278   mkdir -p CustomAgentLogsTmp/Sandbox
279   cp .github/scripts/templates/RunWithAppiumTest.template.cs CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs
280```
281 
2822. **Update test to match MainPage**:
283   - Check AutomationIds: `grep AutomationId MainPage.xaml`
284   - Update test to use those IDs (not template defaults)
285   - Add test logic: tap buttons, verify labels
286   - Add Console.WriteLine markers for debugging
287 
2883. **Example**:
289```bash
290   # Check MainPage
291   grep 'AutomationId=' MainPage.xaml
292   # Update test: App.WaitForElement("NavigateButton");
293```
294 
295**Checklist**:
296- ✅ Add AutomationIds to MainPage.xaml elements
297- ✅ Update RunWithAppiumTest.cs to match
298- ✅ Add SANDBOX markers for debugging
299 
300**🚨 CRITICAL - Document Your Test Scenario:**
301 
302You MUST include in your final report:
303- ✅ **Source**: Where did the test scenario come from? (issue reproduction / PR UITest / custom)
304- ✅ **Why**: Why did you choose that source? (e.g., "Issue #XXXXX provides detailed repro steps")
305- ✅ **What**: What specific actions does your test perform? (e.g., "Tap button → verify label changes to 'Success'")
306- ✅ **Expected**: What behavior should occur? (from issue description or PR changes)
307 
308Without this documentation, user cannot verify you tested the right thing.
309 
310---
311 
312### Step 3: Test WITH PR Fix
313 
314**Platform Selection Decision Tree:**
315 
316Follow this flowchart in order - stop at the first match:
317 
318```
319┌─────────────────────────────────────────────────────────────────┐
320│ 1. Does PR title have platform tag? [Android], [iOS], etc.     │
321│    YES → Test that platform ONLY                                │
322│    NO  → Continue to step 2                                     │
323├─────────────────────────────────────────────────────────────────┤
324│ 2. Are ALL modified files in platform-specific paths?          │
325│    (Platform/Android/, Platform/iOS/, *.Android.cs, etc.)      │
326│    YES → Test that platform ONLY                                │
327│    NO  → Continue to step 3                                     │
328├─────────────────────────────────────────────────────────────────┤
329│ 3. Does issue report mention a specific platform?              │
330│    YES (one platform)  → Test that platform ONLY               │
331│    YES (multiple)      → Test Android + iOS                    │
332│    NO  → Continue to step 4                                     │
333├─────────────────────────────────────────────────────────────────┤
334│ 4. Is this high-risk cross-platform code?                      │
335│    (Controls/, Core/, layout, navigation, critical controls)   │
336│    YES → Test Android + iOS                                     │
337│    NO  → Test Android ONLY (default - faster)                  │
338└─────────────────────────────────────────────────────────────────┘
339```
340 
341**Platform-specific path indicators:**
342- `Platform/Android/` or `Platform/iOS/` → Platform-specific
343- Files with `.Android.`, `.iOS.`, `.MacCatalyst.` in name → Platform-specific
344- `Controls/`, `Core/` without platform subfolders → Cross-platform
345 
346**Hard rule:** Never test more than 2 platforms unless user explicitly requests it.
347 
348**Run Test on Specific iOS Device/Version:**
349 
350When user requests a specific iOS version or device:
351 
3521. **Find the UDID for that device/version combination**:
353```bash
354   # Example: Find iPhone Xs with iOS 18.5
355   UDID=$(xcrun simctl list devices available --json | jq -r '
356     .devices 
357     | to_entries 
358     | map(select(.key | contains("iOS-18-5"))) 
359     | map(.value) 
360     | flatten 
361     | map(select(.name == "iPhone Xs")) 
362     | first 
363     | .udid
364   ')
365   
366   echo "Found UDID: $UDID"
367```
368 
3692. **Pass the UDID to the script**:
370```bash
371   pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios -DeviceUdid "$UDID"
372```
373 
374**Examples:**
375- **"Run on iOS 18.5"** → Find iPhone Xs with iOS 18.5, get UDID, pass to script
376- **"Run on iPhone 15"** → Find iPhone 15 (any iOS), get UDID, pass to script
377- **"Run on iPhone 16 Pro with iOS 18.0"** → Find iPhone 16 Pro with iOS 18.0, get UDID, pass to script
378 
379---
380 
381## How the Template Works
382 
383**The template ALWAYS does the same thing:**
384 
3851. ✅ Verifies app launched successfully (WaitForElement)
3862. ✅ Optionally runs automated UI tests (if you add them)
3873. ✅ Exits WITHOUT closing the app (stays running for manual validation)
388 
389**Usage:**
390```bash
391# Copy the template
392cp .github/scripts/templates/RunWithAppiumTest.template.cs CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs
393 
394# OPTIONAL: Add automated test logic in the TEST LOGIC section
395# If you don't add test logic, it just verifies launch and exits
396 
397# Run the script
398pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios
399```
400 
401**Result:**
402- App launches and stays running
403- You can manually validate in the simulator
404- Test script exits without closing the app
405 
406---
407 
408## 🚨 CRITICAL: BuildAndRunSandbox.ps1 Script - ONLY Way to Deploy Sandbox
409 
410**YOU MUST ALWAYS USE THIS SCRIPT. NEVER USE MANUAL `dotnet build`, `adb`, or `xcrun` COMMANDS.**
411 
412### Script Location
413`.github/scripts/BuildAndRunSandbox.ps1`
414 
415### Basic Usage
416```powershell
417# Android
418pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform Android
419 
420# iOS (auto-detects device)
421pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform iOS
422 
423# iOS with specific device
424pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform iOS -DeviceUdid "YOUR-DEVICE-UDID"
425```
426 
427### What the Script Does Automatically
428- ✅ **Device detection and boot** - Finds and boots simulator/emulator
429- ✅ **UDID extraction** - Sets DEVICE_UDID environment variable
430- ✅ **Fresh app build** - Builds Sandbox project for target platform
431- ✅ **App deployment** - Installs and launches app
432- ✅ **Appium server management** - Starts/stops Appium automatically
433- ✅ **Log capture** - Saves device and Appium logs to `CustomAgentLogsTmp/Sandbox/`
434- ✅ **Test execution** - Runs your Appium test script
435 
436### Requirements Before Running
437Copy and update test file (see Step 2 above). Template looks for "InstructionLabel" which doesn't exist - update first!
438 
439**🚨 POST-TEST VALIDATION (MANDATORY):**
440 
441After script completes, run Rule 4 validation checklist (see above). If ANY check fails: investigate, fix, rerun.
442 
443**Key reminders**:
444- HTTP 200 = element found, NOT test completed
445- If no test actions in logs = FALSE SUCCESS
446- If Appium can't find initial element = app crashed or AutomationIds wrong
447 
448---
449 
450### 📝 Note for User
451 
452**Test scenario is ready in Sandbox for manual verification.**
453 
454**To verify bug reproduction (optional):**
455```bash
456# 1. Revert the PR fix files
457git checkout main -- [list specific fix files from PR]
458 
459# 2. Rerun test - bug should appear
460pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios]
461 
462# 3. Restore fix
463git checkout HEAD -- [fix files]
464 
465# 4. Rerun test - bug should be gone
466pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios]
467```
468 
469This proves the test scenario correctly reproduces the bug.
470 
471---
472 
473## 🔄 Iterative Testing Workflow (MANDATORY PROCESS)
474 
475**🚨 CRITICAL**: This is THE workflow for Sandbox testing. Do NOT use manual `adb`/`xcrun` commands to bypass it.
476 
477### The Required Loop
478 
479```
480┌─────────────────────────────────────────────────────────────┐
481│ 1. Update MainPage.xaml[.cs] with your test scenario       │
482│    - Add UI elements for reproduction                       │
483│    - Add AutomationIds to all interactive elements          │
484│    - Add Console.WriteLine markers for debugging            │
485├─────────────────────────────────────────────────────────────┤
486│ 2. Update Appium test to match your MainPage               │
487│    CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs         │
488│    - Update element locators to match AutomationIds        │
489│    - Add test logic (tap buttons, verify labels)           │
490├─────────────────────────────────────────────────────────────┤
491│ 3. Run BuildAndRunSandbox.ps1                               │
492│    pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform X  │
493├─────────────────────────────────────────────────────────────┤
494│ 4. Validate results using SYSTEMATIC CHECKLIST             │
495│    - Step 1: Check for errors/exceptions                   │
496│    - Step 2: Verify test actions (Tapping, etc.)           │
497│    - Step 3: Verify "Test completed"                       │
498│    - Step 4: Check device logs for SANDBOX markers         │
499│    - Step 5-6: Screenshots and exit code                   │
500├─────────────────────────────────────────────────────────────┤
501│ 5. Did ALL validation checks pass?                         │
502│    YES → Report success with summary (go to step 8)        │
503│    NO  → Continue to step 6                                │
504├─────────────────────────────────────────────────────────────┤
505│ 6. Investigate failure from captured logs                  │
506│    - Read CustomAgentLogsTmp/Sandbox/android-device.log    │
507│    - Read CustomAgentLogsTmp/Sandbox/build-run-output.log  │
508│    - Identify root cause (element not found? crash?)       │
509├─────────────────────────────────────────────────────────────┤
510│ 7. Fix the issue and LOOP BACK TO STEP 3                   │
511│    - Update MainPage if UI/code issue                      │
512│    - Update RunWithAppiumTest.cs if test issue             │
513│    - Update both if AutomationId mismatch                  │
514│    - Max 3 iterations before reporting as blocked          │
515├─────────────────────────────────────────────────────────────┤
516│ 8. Report comprehensive summary to user                    │
517│    - Test scenario source and justification                │
518│    - Validation results                                    │
519│    - Verdict (success/partial/issues/blocked)              │
520└─────────────────────────────────────────────────────────────┘
521```
522 
523### ❌ What NOT To Do
524 
525**Never use manual commands during testing**:
526- ❌ `adb logcat`, `adb shell`, `adb install`
527- ❌ `xcrun simctl spawn`, `xcrun simctl install`
528- ❌ `dotnet build`, `dotnet run`
529 
530**Why**: Script already captured everything. Manual commands show CURRENT state, not test execution state.
531 
532**✅ Correct**: Edit files → Rerun `BuildAndRunSandbox.ps1`
533 
534### ✅ Correct Iteration Example
535 
536**Most common case - Test fails to find element**:
537```bash
538# 1. Check what went wrong
539grep "no such element" CustomAgentLogsTmp/Sandbox/build-run-output.log
540 
541# 2. Check what DOES exist in MainPage
542grep AutomationId src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml
543 
544# 3. Fix MainPage: Add AutomationIds
545# Edit MainPage.xaml: <Button AutomationId="NavigateButton" ...
546 
547# 4. Fix test: Update to match
548# Edit RunWithAppiumTest.cs: App.WaitForElement("NavigateButton");
549 
550# 5. Rerun
551pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform android
552```
553 
554**When validation passes**: Report success with comprehensive summary
555 
556### When to Stop Iterating
557 
558- ✅ **All validation checks pass** → Report success with detailed summary
559- ❌ **Max 3 iterations reached** → **STOP and report**: "I wasn't able to reproduce the issue. What should I try next?"
560- ❌ **Build fails repeatedly** → **STOP and report**: "I wasn't able to reproduce the issue due to build failures. What should I try next?"
561- ❌ **Root cause unclear after log analysis** → **STOP and report**: "I wasn't able to reproduce the issue. What should I try next?"
562- ❌ **Issue appears to be PR bug, not test** → **STOP and report findings to user**: "I wasn't able to reproduce the issue - it appears there may be an issue with [details]. What should I try next?"
563- ❌ **Cannot reproduce the issue** → **STOP immediately**: "I wasn't able to reproduce the issue. What should I try next?"
564 
565**CRITICAL**: When you cannot reproduce or hit blockers, **PAUSE and ask the user**. Do NOT:
566- ❌ Switch to a different branch (e.g., `git checkout main`)
567- ❌ Try alternative approaches without asking first
568- ❌ Change the workflow significantly without user guidance
569 
570### Mental Model: The Script is Your Robot
571 
572BuildAndRunSandbox.ps1 handles: build → deploy → capture logs → run test → report
573 
574**Your workflow**: Edit files → Run script → Read logs → Fix issues → Repeat
575 
576---
577 
578## Output Format
579 
580Provide a concise test summary:
581 
582```markdown
583## PR Testing Summary
584 
585**PR**: #XXXXX - [Title]
586**Platform Tested**: Android/iOS
587**Issue**: [Brief description]
588 
589---
590 
591### Test Scenario Setup
592 
593**🚨 REQUIRED - Source of Test Scenario**:
594- **Source**: [From issue reproduction / From PR UITest / Custom scenario]
595- **Why this source**: [e.g., "Issue #XXXXX provides detailed repro steps" / "PR includes UITest that demonstrates the fix" / "No repro available, created scenario based on PR code changes"]
596- **Link to source**: [URL to issue comment with repro, or path to UITest file]
597 
598**What was tested**:
599- [Specific actions taken - e.g., "Tap 'Toggle RTL' button, then tap 'Show Dialog' button"]
600- [UI elements involved - e.g., "Button with AutomationId='ToggleButton', Dialog with Label"]
601- [Expected behavior - e.g., "Dialog should appear with correct RTL padding on label"]
602 
603---
604 
605### Test Results WITH PR Fix
606 
607**Observed Behavior**:
608- [What happened when running the test]
609- [Appium test results]
610- [Relevant log excerpts]
611 
612**Screenshots**: [Reference if taken, but not for validation]
613 
614---
615 
616### Verdict
617 
618✅ **FIX VALIDATED** - Test scenario completes successfully, expected behavior observed
619OR
620⚠️ **PARTIAL** - Fix appears to work but [note any concerns]
621OR
622❌ **ISSUES FOUND** - [Specific problems encountered]
623OR
624🚫 **CANNOT TEST** - [Build failures, setup issues, etc.]
625 
626---
627 
628### Notes for User
629- Test scenario is set up in Sandbox and ready for manual verification if needed
630- To verify bug reproduction without fix, revert PR changes: `git checkout main -- [fix files]`
631- Then rerun: `pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios]`
632```
633 
634---
635 
636## Best Practices
637 
6381. **Use issue reproduction when available** - Most reliable test scenario
6392. **Adapt PR's UITests if no repro** - They're already designed to test the fix
6403. **Validate programmatically, reference visually** - Use Appium element queries for validation, screenshots only for additional context
6414. **Use colored backgrounds** - Makes layout issues visible
6425. **Add console markers** - Easy to grep logs  
6436. **Test multiple iterations** - Race conditions need multiple runs (3-5 times)
6447. **Leave Sandbox as-is** - User will iterate on it after your testing
6458. **Document your test scenario thoroughly** - Include source (issue/UITest/custom), why you chose it, specific actions, and expected behavior so user can verify
646 
647**Screenshot Usage**:
648- ✅ Take screenshots for **context and reference** (e.g., showing layout before/after)
649- ✅ Include in report if they provide **additional insight** beyond what logs show
650- ❌ Do NOT rely on screenshots as **primary validation** - use Appium element queries and log analysis
651- ❌ Do NOT take screenshots just to show "it works" - validation should come from test assertions
652 
653---
654 
655## Log Capture and Review
656 
657### Where Logs Are Saved
658 
659After running BuildAndRunSandbox.ps1, all logs are in `CustomAgentLogsTmp/Sandbox/`:
660 
6611. **Android**: `CustomAgentLogsTmp/Sandbox/android-device.log`
6622. **iOS**: `CustomAgentLogsTmp/Sandbox/ios-device.log`
6633. **Appium**: `CustomAgentLogsTmp/Sandbox/appium.log`
664 
665### Viewing Logs
666 
667```bash
668# View device logs
669cat CustomAgentLogsTmp/Sandbox/android-device.log
670# or
671cat CustomAgentLogsTmp/Sandbox/ios-device.log
672 
673# Search for specific output
674grep &quot;TEST OUTPUT&quot; CustomAgentLogsTmp/Sandbox/android-device.log
675 
676# View Appium logs
677cat CustomAgentLogsTmp/Sandbox/appium.log
678```
679 
680### 📝 Adding Debug Logging to Your Test Scenario
681 
682**Use `Console.WriteLine` for logging** - it works on all platforms.
683 
684```csharp
685// Use a unique prefix for easy grep
686Console.WriteLine("SANDBOX: Button clicked");
687Console.WriteLine($"SANDBOX: Value is {myValue}");
688```
689 
690**Searching logs:**
691```bash
692grep &quot;SANDBOX&quot; CustomAgentLogsTmp/Sandbox/android-device.log
693grep &quot;SANDBOX&quot; CustomAgentLogsTmp/Sandbox/ios-device.log
694grep &quot;SANDBOX&quot; CustomAgentLogsTmp/Sandbox/catalyst-device.log
695```
696 
697---
698 
699## 🚨 ABSOLUTE RULE: BuildAndRunSandbox.ps1 is THE ONLY Deployment Method
700 
701**THIS IS MANDATORY. NOT A SUGGESTION.**
702 
703❌ If typing `adb`/`xcrun` commands during testing → STOP. You're violating the workflow.
704 
705**Why**: Manual commands show CURRENT state, not test execution state. Script already captured correct logs during test.
706 
707**❌ NEVER during testing**: `adb logcat`, `adb install`, `adb shell`, `xcrun simctl install/spawn`, `dotnet build/run`
708 
709**✅ ONLY exception**: Finding/booting specific iOS device BEFORE running script (`xcrun simctl list/boot`)
710 
711**Correct workflow**:
7121. Edit files (MainPage, RunWithAppiumTest.cs)
7132. Run: `pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform X`
7143. Analyze logs in `CustomAgentLogsTmp/Sandbox/` (android-device.log, appium.log)
7154. Fix issues, rerun script
716 
717**Expected logs**: `android-device.log` or `ios-device.log`, `appium.log`, `RunWithAppiumTest.cs`, optional screenshots
718 
719---
720 
721## Troubleshooting & Recovery
722 
723**Retry up to 3 times before reporting as blocked.** After each failure: analyze logs → fix → rerun script.
724 
725### Common Issues
726 
727| Issue | Recovery | Max Retries |
728|-------|----------|-------------|
729| Build error | Check SDK version, `dotnet tool restore` | 2 |
730| App crash | Check stack trace in device log, fix code/XAML | 3 |
731| Element not found | Verify AutomationIds match, check app loaded | 2 |
732| Fast Deployment (Android) | Add `appium:noReset` capability | 1 |
733| XAML parse error | Verify event handler exists in code-behind | 2 |
734 
735### Element Not Found Debugging
736 
737🚨 If Appium can't find initial element, app is NOT running correctly.
738 
739**Check**:
740```bash
741# Look for crashes
742grep -i &quot;FATAL\|crash\|exception&quot; CustomAgentLogsTmp/Sandbox/android-device.log | tail -20
743 
744# Verify app launched
745grep &quot;SANDBOX.*MainPage&quot; CustomAgentLogsTmp/Sandbox/android-device.log
746```
747 
748**Root causes**: App crashed, XAML parse error, AutomationId mismatch, Android Fast Deployment
749 
750### When to Stop & Report
751- ✅ **Continue**: Minor warnings, non-critical timeouts, platform differences
752- ❌ **Stop and ask user**: Can't checkout PR, build fails after max retries, SDK mismatch, root cause unclear, cannot reproduce issue
753 
754**When blocked, ALWAYS report to user with this format**:
755```markdown
756I wasn't able to reproduce the issue. Here's what I tried:
757 
7581. [What I attempted]
7592. [Issues encountered]
7603. [Current state of reproduction attempt]
761 
762What should I try next?
763```
764 
765**DO NOT** try alternative approaches without asking first. **DO NOT** switch branches.
766 
767### Test Shows Unexpected Behavior
768**Action**: Document and report
769 
770```markdown
771⚠️ Unexpected behavior during testing
772 
773**What I expected**: [Based on issue description]
774 
775**What I observed**: [Actual behavior]
776 
777**Test scenario**: [What was tested]
778 
779**Logs**: [Relevant excerpts]
780 
781**Question for user**: Is this expected behavior, or does this indicate an issue?
782```
783 
784---
785 
786## Common Mistakes to Avoid
787 
788- ❌ Using TestCases.HostApp for manual PR validation (use Sandbox)
789- ❌ Manual build/deploy commands instead of BuildAndRunSandbox.ps1
790- ❌ Testing only one platform when PR affects multiple
791- ❌ Using screenshots for validation (use Appium element queries)
792- ❌ Creating test scenario without checking issue for reproduction steps
793- ❌ Ignoring PR's existing UITests when available
794- ❌ Cleaning up or reverting Sandbox changes (user will iterate on it)
795 
796**Testing Tips**:
797- For layout bugs: Use `element.GetRect()` to measure positions
798- For SafeArea PRs: Measure child content position, not parent size
799- Add `Console.WriteLine("SANDBOX: ...")` markers for debugging
800 
801---
802 
803## Appendix: Cleanup (Only When User Requests)
804 
805⚠️ **DO NOT clean up after testing** - Leave Sandbox as-is so user can iterate on it.
806 
807Only use these commands if the **user explicitly requests cleanup**:
808 
809### Sandbox App Cleanup (User Request Only)
810```bash
811# Revert all changes to Sandbox app
812git checkout -- src/Controls/samples/Controls.Sample.Sandbox/
813```
814 
815### Sandbox Test Files Cleanup (User Request Only)
816```bash
817# Remove Appium test directory (gitignored)
818rm -rf CustomAgentLogsTmp/Sandbox/
819```
820