diff --git a/.github/instructions/appium-control.instructions.md b/.github/instructions/appium-control.instructions.md index 038a1b10df8c..3eebb642943b 100644 --- a/.github/instructions/appium-control.instructions.md +++ b/.github/instructions/appium-control.instructions.md @@ -31,101 +31,30 @@ This repository uses **.NET 10's built-in scripting features** with the `#:packa ## Quick Start with Sandbox App -The fastest way to experiment with Appium is using the Sandbox app (`src/Controls/samples/Controls.Sample.Sandbox`): +**Use BuildAndRunSandbox.ps1 Script** -1. **Modify `MainPage.xaml`** to add controls with `AutomationId` attributes +The script handles all building, deployment, Appium management, and log capture: -2. **Build and deploy**: +```powershell +# 1. Copy Appium template +cp .github/scripts/templates/RunWithAppiumTest.template.cs SandboxAppium/RunWithAppiumTest.cs - **iOS:** - ```bash - # Build - dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios +# 2. Edit the template for your test scenario - # Get device UDID - UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid') - - # Verify UDID was found - if [ -z "$UDID" ]; then - echo "❌ ERROR: No iPhone Xs simulator found" - exit 1 - fi - echo "Using iPhone Xs with UDID: $UDID" - - # Boot and install - xcrun simctl boot $UDID 2>/dev/null || true - xcrun simctl install $UDID artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app - - # Set environment variable - export DEVICE_UDID=$UDID - ``` - - **Android:** - ```bash - # Get device UDID - UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1) - - # Verify UDID was found - if [ -z "$UDID" ]; then - echo "❌ ERROR: No Android device/emulator found" - exit 1 - fi - echo "Using Android device: $UDID" - - # Set environment variable - export DEVICE_UDID=$UDID - - # Build and deploy (this handles install + launch) - dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-android -t:Run - - # Verify app is running - sleep 3 - if adb -s $UDID shell pidof com.microsoft.maui.sandbox > /dev/null; then - echo "✅ App is running" - else - echo "❌ App failed to start" - exit 1 - fi - ``` - -3. **Start Appium and run your control script**: - ```bash - # Start Appium in background - appium --log-level error & - - # Wait for Appium to be ready - sleep 3 - - # Or verify it's ready (optional): - # curl http://localhost:4723/status - - # Run your script (from SandboxAppium/ directory) - cd SandboxAppium - - # Run with .NET 10's native scripting (NOT dotnet-script) - dotnet run yourscript.cs - ``` - -**Note**: The Sandbox app and SandboxAppium folder are set up for iterative development. You can modify your script and re-run it multiple times without cleaning up. Only clean up when you're completely done with your debugging session. - -## Cleanup (Optional) - -When you're finished with your debugging session and ready to clean up: - -```bash -# Revert Sandbox changes -git checkout -- src/Controls/samples/Controls.Sample.Sandbox/ +# 3. Run everything with one command +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios] +``` -# Remove SandboxAppium folder (it's gitignored) -rm -rf SandboxAppium +The script automatically: +- Detects and boots devices +- Builds and deploys the Sandbox app +- Starts/stops Appium server +- Runs your Appium test script +- Captures all logs to `SandboxAppium/` directory -# Kill Appium server -lsof -i :4723 | grep LISTEN | awk '{print $2}' | xargs kill -9 -``` +See [Common Testing Patterns](common-testing-patterns.md) for details. -## Prerequisites -Ensure Appium server is running on `http://localhost:4723` before running your script. ## Basic Template @@ -248,6 +177,10 @@ catch (Exception ex) ## Running the Script +**The BuildAndRunSandbox.ps1 script handles all setup and execution.** See [Quick Start with Sandbox App](#quick-start-with-sandbox-app) for the complete workflow. + +**For manual/standalone script execution** (advanced scenarios): + **🚨 CRITICAL: .NET 10 Native Scripting (NOT dotnet-script)** - ✅ **DO**: Use `dotnet run yourscript.cs` (.NET 10 native scripting) @@ -258,28 +191,7 @@ catch (Exception ex) **⚠️ Important: Create scripts inside project directory (e.g., `SandboxAppium/`), not in `/tmp` or repository root.** -```bash -# 1. Create script folder -mkdir -p SandboxAppium && cd SandboxAppium - -# 2. Copy the Basic Template above into a .cs file (or use the Quick Start example) - -# 3. Set DEVICE_UDID environment variable -export DEVICE_UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid') - -# 4. Start Appium (separate terminal or background) -appium --log-level error & - -# Wait for Appium to be ready -sleep 3 - -# 5. Run your script -dotnet run yourscript.cs -``` - -**For Android:** Replace iOS UDID command with: `adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1` - -**Complete workflow:** See [Quick Start with Sandbox App](#quick-start-with-sandbox-app) above for full end-to-end example. +For manual execution details, see [Common Testing Patterns](common-testing-patterns.md). ## ❌ Wrong vs ✅ Right Approach diff --git a/.github/instructions/instrumentation.instructions.md b/.github/instructions/instrumentation.instructions.md index c5d6ae95aa30..bda17d8185e5 100644 --- a/.github/instructions/instrumentation.instructions.md +++ b/.github/instructions/instrumentation.instructions.md @@ -137,12 +137,26 @@ namespace Maui.Controls.Sample ### Step 3: Build, Deploy, and Capture -See [Common Testing Patterns](common-testing-patterns.md) for detailed build and deploy commands: +**⚡ Option A: Use BuildAndRunSandbox.ps1 Script (Recommended)** -**iOS**: [Sandbox App Build (iOS)](common-testing-patterns.md#sandbox-app-build-ios) -**Android**: [Sandbox App Build (Android)](common-testing-patterns.md#sandbox-app-build-android) +When using with Appium for UI interaction: -**Quick iOS workflow:** +```powershell +# 1. Create Appium test script with your instrumentation logic +cp .github/scripts/templates/RunWithAppiumTest.template.cs SandboxAppium/RunWithAppiumTest.cs +# Edit RunWithAppiumTest.cs to add your test logic + +# 2. Run everything with one command +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios] +``` + +The script handles device detection, building, deployment, Appium management, and log capture. See [Common Testing Patterns](common-testing-patterns.md) for details. + +--- + +**Option B: Manual Build and Capture** (for console-only instrumentation without Appium): + +**iOS**: ```bash # Get UDID, boot, build, install, launch UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid') @@ -153,7 +167,7 @@ xcrun simctl launch --console-pty $UDID com.microsoft.maui.sandbox > /tmp/output sleep 8 && cat /tmp/output.log ``` -**Quick Android workflow:** +**Android**: ```bash export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1) dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-android -t:Run diff --git a/.github/instructions/pr-reviewer-agent/error-handling.md b/.github/instructions/pr-reviewer-agent/error-handling.md index 7cbedece22d5..8146d4d47b84 100644 --- a/.github/instructions/pr-reviewer-agent/error-handling.md +++ b/.github/instructions/pr-reviewer-agent/error-handling.md @@ -150,36 +150,23 @@ fi **Step 1: ATTEMPT available solutions first** -For Android: -```bash -# 1. Check for device -export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1) - -# 2. If no device, START EMULATOR (don't give up!) -if [ -z "$DEVICE_UDID" ]; then - echo "No device found. Starting emulator..." - cd $ANDROID_HOME/emulator && (./emulator -avd Pixel_9 -no-snapshot-load -no-audio -no-boot-anim > /tmp/emulator.log 2>&1 &) - adb wait-for-device - until [ "$(adb shell getprop sys.boot_completed 2>/dev/null)" = "1" ]; do - sleep 2 - done - export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1) -fi - -# 3. If emulator failed, check logs -if [ -z "$DEVICE_UDID" ]; then - echo "Emulator failed to start. Checking logs..." - cat /tmp/emulator.log - # Now proceed to Step 2 (checkpoint) -fi +**For both Android and iOS**: Use the BuildAndRunSandbox.ps1 script, which handles device detection and emulator startup automatically: + +```powershell +# The script will: +# 1. Auto-detect devices +# 2. Start emulator/simulator if no device found (Android only - prompts for confirmation) +# 3. Build and deploy Sandbox app +# 4. Run your Appium test + +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform android +# OR +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios ``` -For iOS: -```bash -# Check for available simulators -xcrun simctl list devices | grep iPhone -# Attempt to boot simulator (see quick-ref.md) -``` +**If the script fails**, check the log files in `SandboxAppium/`: +- `appium.log` - Appium server issues +- `android-device.log` or `ios-device.log` - Device/app issues **Step 2: If solutions fail, CREATE CHECKPOINT (don't skip testing!)** @@ -226,28 +213,22 @@ After attempting solutions and hitting genuine blocker: **How to avoid**: 1. **Read appium-control.instructions.md FIRST** before attempting UI interaction 2. Remember: Appium is REQUIRED for reliability (element-based vs coordinate-based) -3. **Use .cs files with `dotnet run`** (NOT .csx files with dotnet-script) +3. **Use the Appium template** from `.github/scripts/templates/RunWithAppiumTest.template.cs` 4. When Appium fails, debug the Appium approach (don't fall back to adb) 5. **Internalize instructions, don't just skim them** **Complete sequence**: ```bash -# 1. Create Appium script (.cs file, NOT .csx) -cat > test_pr_XXXXX.cs << 'EOF' -#r "nuget: Appium.WebDriver, 8.0.1" -using OpenQA.Selenium.Appium; -using OpenQA.Selenium.Appium.Android; - -var options = new AppiumOptions(); -options.AddAdditionalAppiumOption("platformName", "Android"); -options.AddAdditionalAppiumOption("automationName", "UIAutomator2"); -options.AddAdditionalAppiumOption("appPackage", "com.microsoft.maui.sandbox"); -options.AddAdditionalAppiumOption("appActivity", "crc64..MainActivity"); -options.AddAdditionalAppiumOption("noReset", true); - -var driver = new AndroidDriver(new Uri("http://127.0.0.1:4723"), options); - -// Find and tap button by AutomationId +# 1. Copy Appium template to SandboxAppium directory +cp .github/scripts/templates/RunWithAppiumTest.template.cs SandboxAppium/RunWithAppiumTest.cs + +# 2. Edit the file to customize: +# - Set ISSUE_NUMBER constant +# - Set PLATFORM constant ("android" or "ios") +# - Implement test logic in the "Test Logic" section + +# 3. Run with BuildAndRunSandbox.ps1 script +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform android var button = driver.FindElement(MobileBy.AccessibilityId("TestButton")); button.Click(); diff --git a/.github/instructions/pr-reviewer-agent/quick-ref.md b/.github/instructions/pr-reviewer-agent/quick-ref.md index f0befdd27498..5819abcd6a77 100644 --- a/.github/instructions/pr-reviewer-agent/quick-ref.md +++ b/.github/instructions/pr-reviewer-agent/quick-ref.md @@ -24,52 +24,41 @@ When in doubt → Sandbox app --- -## 📦 Platform Testing - Quick Commands +## 📦 Platform Testing - Use BuildAndRunSandbox.ps1 -**Full workflows with error checking**: See [Shared Platform Workflows](../shared/platform-workflows.md) +**CRITICAL**: Use the `BuildAndRunSandbox.ps1` script for all Sandbox app testing. It handles all device detection, building, deployment, Appium management, and log capture automatically. -### iOS Quick Start +### Quick Start -```bash -# Get UDID, boot, build, install, launch - see shared doc for full sequence -UDID=$(xcrun simctl list devices available --json | jq -r '.devices | to_entries | map(select(.key | startswith("com.apple.CoreSimulator.SimRuntime.iOS"))) | map({key: .key, version: (.key | sub("com.apple.CoreSimulator.SimRuntime.iOS-"; "") | split("-") | map(tonumber)), devices: .value}) | sort_by(.version) | reverse | map(select(.devices | any(.name == "iPhone Xs"))) | first | .devices[] | select(.name == "iPhone Xs") | .udid') -xcrun simctl boot $UDID 2>/dev/null || true -dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-ios -xcrun simctl install $UDID artifacts/bin/Maui.Controls.Sample.Sandbox/Debug/net10.0-ios/iossimulator-arm64/Maui.Controls.Sample.Sandbox.app -xcrun simctl launch --console-pty $UDID com.microsoft.maui.sandbox > /tmp/ios_test.log 2>&1 & -``` - -📖 **Complete workflow**: [Shared Platform Workflows - iOS](../shared/platform-workflows.md#complete-ios-reproduction-workflow) - -### Android Quick Start - -**⚠️ CRITICAL**: If no device found, START AN EMULATOR - don't skip testing! - -```bash -# 1. Check for device -export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1) +**Script location**: `.github/scripts/BuildAndRunSandbox.ps1` -# 2. If no device found, start emulator (see below) -if [ -z "$DEVICE_UDID" ]; then - echo "❌ No device found. Starting emulator..." - # See "Android Emulator Startup" section below -fi +```powershell +# iOS +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios -# 3. Build and deploy -dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-android -t:Run - -# 4. Monitor logs -adb logcat > /tmp/android_test.log 2>&1 & -LOGCAT_PID=$! - -# ... do testing ... - -# 5. Stop logcat and view output -kill $LOGCAT_PID -cat /tmp/android_test.log | grep "TEST OUTPUT" +# Android +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform android ``` -📖 **Complete workflow**: [Shared Platform Workflows - Android](../shared/platform-workflows.md#complete-android-reproduction-workflow) +**What the script handles**: +- ✅ Automatic device detection and boot (iPhone Xs for iOS, first available for Android) +- ✅ Building Sandbox app (always fresh build) +- ✅ App installation and deployment +- ✅ Appium server management (auto-start/stop) +- ✅ Running your Appium test script (`SandboxAppium/RunWithAppiumTest.cs`) +- ✅ Complete log capture to `SandboxAppium/` directory: + - `appium.log` - Appium server logs + - `android-device.log` or `ios-device.log` - Device logs filtered to Sandbox app + - Console output from your test script + +**Prerequisites**: +1. Create `SandboxAppium/RunWithAppiumTest.cs` using template: + ```bash + cp .github/scripts/templates/RunWithAppiumTest.template.cs SandboxAppium/RunWithAppiumTest.cs + ``` +2. Modify the template for your test scenario + +📖 **Full documentation**: See [Common Testing Patterns](../common-testing-patterns.md) --- @@ -94,56 +83,30 @@ cat /tmp/android_test.log | grep "TEST OUTPUT" ### Quick Appium Script Template: -```csharp -// File: test_pr_XXXXX.cs (use .cs NOT .csx) -#r "nuget: Appium.WebDriver, 8.0.1" -using OpenQA.Selenium.Appium; -using OpenQA.Selenium.Appium.Android; - -var options = new AppiumOptions(); -options.AddAdditionalAppiumOption("platformName", "Android"); -options.AddAdditionalAppiumOption("automationName", "UIAutomator2"); -options.AddAdditionalAppiumOption("appPackage", "com.microsoft.maui.sandbox"); -options.AddAdditionalAppiumOption("appActivity", "crc64..MainActivity"); -options.AddAdditionalAppiumOption("noReset", true); - -var driver = new AndroidDriver(new Uri("http://127.0.0.1:4723"), options); - -// Find and tap button -var button = driver.FindElement(MobileBy.AccessibilityId("TestButton")); -button.Click(); - -driver.Quit(); -``` - -**Run with**: `dotnet run test_pr_XXXXX.cs` (NOT `dotnet-script`) - -📖 **Full Appium guide**: [../appium-control.instructions.md](../appium-control.instructions.md) - ---- - -### Android Emulator Startup (REQUIRED when no device) - -**When to use**: `adb devices` shows no devices connected +**CRITICAL**: Use the template file provided in the repository: ```bash -# CRITICAL: Use subshell with & to persist emulator -cd $ANDROID_HOME/emulator && (./emulator -avd Pixel_9 -no-snapshot-load -no-audio -no-boot-anim > /tmp/emulator.log 2>&1 &) +# Copy template to SandboxAppium directory +cp .github/scripts/templates/RunWithAppiumTest.template.cs SandboxAppium/RunWithAppiumTest.cs -# Wait for boot -adb wait-for-device -until [ "$(adb shell getprop sys.boot_completed 2>/dev/null)" = "1" ]; do - sleep 2 - echo -n "." -done +# Edit the file to customize for your test scenario: +# 1. Set ISSUE_NUMBER constant +# 2. Set PLATFORM constant ("android" or "ios") +# 3. Implement test logic in the "Test Logic" section +``` -echo "✅ Emulator ready" +**The template includes**: +- ✅ Proper .NET 10 scripting syntax (`#:package` directive) +- ✅ Platform-specific Appium configuration +- ✅ Automatic device UDID handling +- ✅ PID capture for Android logcat filtering +- ✅ Error handling and troubleshooting guidance +- ✅ Screenshot capture before/after test +- ✅ Complete example test logic to customize -# Now get device UDID -export DEVICE_UDID=$(adb devices | grep -v "List" | grep "device" | awk '{print $1}' | head -1) -``` +**Run with**: `pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ` -📖 **Full startup sequence with error handling**: [Shared Platform Workflows - Android Emulator](../shared/platform-workflows.md#android-emulator-startup) +📖 **Full Appium guide**: [../appium-control.instructions.md](../appium-control.instructions.md) --- diff --git a/.github/instructions/pr-reviewer-agent/quick-start.md b/.github/instructions/pr-reviewer-agent/quick-start.md index 9d30a3b52aca..e7642920728f 100644 --- a/.github/instructions/pr-reviewer-agent/quick-start.md +++ b/.github/instructions/pr-reviewer-agent/quick-start.md @@ -183,8 +183,8 @@ git checkout main -- src/path/to/changed/file.cs # Verify no differences remain git diff main -- src/path/to/changed/file.cs # Should be empty -# Build and test -dotnet build ... -t:Run +# Build and test using automated script +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios] # Document results: "Bug reproduces" ``` @@ -197,8 +197,8 @@ git checkout HEAD -- src/path/to/changed/file.cs # Verify PR changes are back git diff main -- src/path/to/changed/file.cs # Should show PR changes -# Build and test -dotnet build ... -t:Run +# Build and test using automated script +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios] # Document results: "Bug is fixed" ``` @@ -217,16 +217,27 @@ After reverting: ## 📋 Common Commands (Copy-Paste) -See [quick-ref.md](quick-ref.md) for complete command sequences. +**Sandbox App Testing** (use these scripts for all PR validation): +```powershell +# iOS +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform ios -**iOS Testing**: -```bash -# Complete workflow - see quick-ref.md for full version -UDID=$(xcrun simctl list devices available --json | jq -r '...') -# ... build, install, launch +# Android +pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform android ``` -**Android Testing**: +**HostApp UI Testing** (only when writing/validating UI tests): +```powershell +# iOS +pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform ios -TestFilter "IssueXXXXX" + +# Android +pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform android -TestFilter "IssueXXXXX" +``` + +See [quick-ref.md](quick-ref.md) and [Common Testing Patterns](../common-testing-patterns.md) for more details. + +**Manual commands** (for troubleshooting): ```bash # 1. Check for device export DEVICE_UDID=$(adb devices | grep device | awk '{print $1}' | head -1) diff --git a/.github/instructions/pr-reviewer-agent/testing-guidelines.md b/.github/instructions/pr-reviewer-agent/testing-guidelines.md index 37b99e58ccb5..f2e28e7ccf1e 100644 --- a/.github/instructions/pr-reviewer-agent/testing-guidelines.md +++ b/.github/instructions/pr-reviewer-agent/testing-guidelines.md @@ -595,10 +595,11 @@ Create a checkpoint when: **To verify this PR works, you'll need to**: -1. **Build sandbox app with PR changes**: - ```bash - dotnet build src/Controls/samples/Controls.Sample.Sandbox/Maui.Controls.Sample.Sandbox.csproj -f net10.0-[platform] -t:Run +1. **Build and run sandbox app with PR changes**: + ```powershell + pwsh .github/scripts/BuildAndRunSandbox.ps1 -Platform [android|ios] ``` + (This handles device detection, building, deployment, and Appium test execution) 2. **Reproduce the original issue** (verify bug exists): - Action: [specific steps] diff --git a/.github/instructions/shared/platform-workflows.md b/.github/instructions/shared/platform-workflows.md index 9579e5f3d7ab..dd76e5fc4890 100644 --- a/.github/instructions/shared/platform-workflows.md +++ b/.github/instructions/shared/platform-workflows.md @@ -4,7 +4,17 @@ description: "Shared platform-specific workflows for iOS, Android, and MacCataly # Platform-Specific Workflows -This document contains platform-specific workflows shared by both PR reviewer and issue resolver agents. Use these workflows for reproducing issues, building apps, and capturing diagnostics. +**⚠️ IMPORTANT: Use Automated Scripts First** + +For most testing scenarios, use the automated PowerShell scripts instead of manual commands: +- **Sandbox app testing**: Use `.github/scripts/BuildAndRunSandbox.ps1` - See [Common Testing Patterns](../common-testing-patterns.md) +- **HostApp UI tests**: Use `.github/scripts/BuildAndRunHostApp.ps1` - See [Common Testing Patterns](../common-testing-patterns.md) + +**This document provides manual workflows for**: +- Low-level troubleshooting when scripts fail +- Understanding what the scripts do internally +- Advanced scenarios not covered by scripts +- Reference documentation for platform-specific commands ---