Sandbox Agent

The Sandbox Agent is a specialized AI assistant for working with the .NET MAUI Sandbox app to test, validate, and experiment with MAUI features through automated deployment and testing.

How to Use This Agent

• VS Code: Custom Agents in VS Code
• Copilot CLI: GitHub Copilot CLI

See Export Your Chat Sessions after completing your work.

---

What It Does

The Sandbox Agent:

• ✅ Sets up test scenarios in the Sandbox app
• ✅ Deploys to Android, iOS, MacCatalyst, and Windows
• ✅ Runs automated Appium tests to reproduce issues
• ✅ Validates PR fixes work correctly
• ✅ Reproduces reported issues
• ✅ Iteratively fixes issues - once reproduction is automated, keeps working until fix is validated
• ✅ Converts Sandbox scenarios to UI tests when ready
• ✅ Captures device logs and screenshots

When to Use

Use the Sandbox Agent when:

• You want to manually verify a PR fix works on device/simulator
• You need to reproduce an issue hands-on
• You want to experiment with a MAUI feature
• You need functional validation beyond code review
• You want to iteratively fix an issue - reproduce → fix → test → repeat until solved
• You're ready to convert a working Sandbox scenario into proper UI tests

Note: The Sandbox Agent focuses on functional testing, not code review. For reviewing code quality, use the PR Agent instead.

Example Prompts

Basic Testing

test PR #12345 on Android

test this PR on iOS

validate PR #12345 on both Android and iOS

Issue Reproduction

reproduce issue #12345 in Sandbox

try to reproduce issue #12345 on Android

Specific Device/Version

test this PR on iPhone 15

test PR #12345 on iOS 18.5

Iterative Fix Workflow

reproduce issue #12345 with Appium automation, then work on fixing it until the test passes

The fix works! Now move this Sandbox scenario to proper UI tests.

Test Workflow

The Sandbox Agent follows this workflow:

1. Modify Sandbox app → 2. Create Appium test → 3. Deploy to device → 4. Run test → 5. Report results

Files Modified

• src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml - UI for test scenario
• src/Controls/samples/Controls.Sample.Sandbox/MainPage.xaml.cs - Test logic
• CustomAgentLogsTmp/Sandbox/RunWithAppiumTest.cs - Appium test script (auto-generated)

Logs Captured

• CustomAgentLogsTmp/Sandbox/android-device.log or ios-device.log - Device logs
• CustomAgentLogsTmp/Sandbox/build-run-output.log - Build and deployment logs
• CustomAgentLogsTmp/Sandbox/appium.log - Appium test execution logs
• CustomAgentLogsTmp/Sandbox/*.png - Screenshots (if test captures them)

Iterative Issue Fixing (Recommended Workflow)

This is the most powerful way to use the Sandbox Agent - set up automated reproduction, then work with Copilot to fix the issue iteratively.

Step 1: Set up automated reproduction

reproduce issue #12345 in Sandbox with Appium automation

What happens:

• Agent creates MainPage with reproduction scenario
• Agent creates Appium test that demonstrates the bug
• Agent runs test and confirms: "Bug reproduced - test fails as expected"

Step 2: Iteratively fix the issue

Now work on fixing issue #12345. Keep testing after each change until the Appium test passes.

What happens:

• Copilot analyzes the bug and proposes a fix
• Modifies MAUI framework code (not Sandbox)
• Reruns BuildAndRunSandbox.ps1 to test
• If test still fails → analyzes why → tries different approach
• Repeats until Appium test passes

Step 3: Convert to UI tests

The fix works! Now move this Sandbox scenario to proper UI tests.

What happens:

• Agent creates TestCases.HostApp/Issues/Issue12345.xaml[.cs]
• Agent creates TestCases.Shared.Tests/Tests/Issues/Issue12345.cs
• Copies working test logic from Sandbox
• Cleans up Sandbox

Understanding Test Results

✅ Success

✅ FIX VALIDATED - Test scenario completes successfully, expected behavior observed

Meaning: PR fix works as expected, no issues found.

⚠️ Partial Success

⚠️ PARTIAL - Fix appears to work but noticed a minor animation glitch

Meaning: Fix mostly works but there are concerns worth noting.

❌ Issues Found

❌ ISSUES FOUND - App crashes when tapping button after navigation

Meaning: Test revealed problems with the fix.

🚫 Cannot Test

🚫 CANNOT TEST - Build failed due to missing dependency

Meaning: Unable to complete testing due to technical issues.

Platform Selection

The agent automatically selects platforms based on:

1. PR title tags - [Android], [iOS], etc.
2. Modified file paths - Platform-specific code paths
3. Issue description - Mentioned platforms
4. Code changes - Cross-platform vs. platform-specific

Default: Tests on Android only (faster) unless PR affects iOS-specific code or cross-platform controls.

You can override by specifying:

test PR #12345 on iOS

Supported Platforms

Platform	Command	Notes
Android	-Platform android	Requires Android emulator
iOS	-Platform ios	Requires iOS simulator (macOS only)
MacCatalyst	-Platform catalyst	Runs on macOS host directly
Windows	-Platform windows	Runs on Windows host directly

Scripts Used

The Sandbox Agent uses BuildAndRunSandbox.ps1:

# Android
pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform android

# iOS (auto-detects device)
pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios

# iOS with specific device
pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios -DeviceUdid "YOUR-DEVICE-UDID"

# MacCatalyst
pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform catalyst

# Windows
pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform windows

File Locations

File	Purpose
.github/agents/sandbox-agent.md	Agent definition
.github/instructions/sandbox.instructions.md	Detailed testing workflow
.github/scripts/BuildAndRunSandbox.ps1	Build, deploy, and test script
.github/scripts/templates/RunWithAppiumTest.template.cs	Appium test template

Related Documentation

• Sandbox Testing Instructions - Full workflow details
• UI Testing Guide - For creating permanent UI tests