Copilot instructions

1---
2applyTo: "src/Controls/tests/TestCases.Shared.Tests/**,src/Controls/tests/TestCases.HostApp/**"
3---
4 
5# UI Testing Guidelines for .NET MAUI
6 
7## Overview
8 
9This document provides specific guidance for GitHub Copilot when writing UI tests for the .NET MAUI repository.
10 
11 
12 
13**Critical Principle**: UI tests should run on all applicable platforms (iOS, Android, Windows, MacCatalyst) by default unless there is a specific technical limitation.
14 
15## UI Test Structure
16 
17### Two-Project Requirement
18 
19**CRITICAL: Every UI test requires code in TWO separate projects:**
20 
211. **HostApp UI Test Page** (`src/Controls/tests/TestCases.HostApp/Issues/`)
22   - Create the actual UI page that demonstrates the feature or reproduces the issue
23   - **Prefer C# only** (`.cs` file) unless testing XAML-specific features (bindings, templates, styles)
24   - Add `AutomationId` attributes on interactive controls for test automation
25   - Follow naming convention: `IssueXXXXX.cs` (C# only) or `IssueXXXXX.xaml` + `IssueXXXXX.xaml.cs` (when XAML required)
26   - XXXXX should correspond to a GitHub issue number when applicable
27   - Ensure the UI provides clear visual feedback for the behavior being tested
28   - Class must include `[Issue()]` attribute with tracker, number, description, and platform
29 
302. **NUnit Test Implementation** (`src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/`)
31   - Create corresponding Appium-based NUnit tests that inherit from `_IssuesUITest`
32   - Use the `AutomationId` values to locate and interact with UI elements
33   - Follow naming convention: `IssueXXXXX.cs` (matches the HostApp page file)
34   - Include appropriate `[Category(UITestCategories.XYZ)]` attributes (only ONE per test)
35   - Test should validate expected behavior through UI interactions and assertions
36 
37### Base Class and Infrastructure
38 
39- Each test class must inherit from `_IssuesUITest`
40- The `_IssuesUITest` base class provides:
41  - The `App` property for interacting with UI elements
42  - Test initialization and setup
43  - Helper methods for common UI test operations
44- The test infrastructure automatically handles platform detection and page navigation
45 
46### Naming Conventions
47 
48**Test Files:**
49- Pattern: `IssueXXXXX.cs` where XXXXX corresponds to a GitHub issue number
50- Must match the corresponding HostApp page file name in TestCases.HostApp (either `.cs` only or `.xaml`)
51 
52**Test Methods:**
53- Use descriptive names that clearly explain what behavior is being verified
54- ✅ Good: `VerifySafeAreaBottomPaddingWithKeyboard()`, `ButtonClickUpdatesLabel()`
55- ❌ Bad: `Test1()`, `TestMethod()`, `RunTest()`
56 
57**AutomationId Values:**
58- Always use unique, descriptive `AutomationId` values
59- Reference the same `AutomationId` in both C# code (or XAML if used) and test code
60- Use PascalCase for AutomationId values
61 
62## Complete Test Example
63 
64### Example 1: C# Only (Preferred for Most Tests)
65 
66**HostApp Page** (`TestCases.HostApp/Issues/Issue12345.cs`):
67```csharp
68namespace Maui.Controls.Sample.Issues;
69 
70[Issue(IssueTracker.Github, 12345, "Button click updates label text", PlatformAffected.All)]
71public class Issue12345 : ContentPage
72{
73    public Issue12345()
74    {
75        var resultLabel = new Label
76        {
77            Text = "Initial Text",
78            AutomationId = "ResultLabel"
79        };
80 
81        Content = new VerticalStackLayout
82        {
83            Children =
84            {
85                new Button
86                {
87                    Text = "Click Me",
88                    AutomationId = "TestButton",
89                    Command = new Command(() => resultLabel.Text = "Expected Text")
90                },
91                resultLabel
92            }
93        };
94    }
95}
96```
97 
98### Example 2: XAML (When Testing XAML-Specific Features)
99 
100**HostApp XAML** (`TestCases.HostApp/Issues/Issue12346.xaml`):
101```xaml
102<?xml version="1.0" encoding="utf-8" ?>
103<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
104             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
105             x:Class="Maui.Controls.Sample.Issues.Issue12346">
106    <VerticalStackLayout>
107        <Button Text="Click Me" 
108                AutomationId="TestButton"
109                Clicked="OnButtonClicked" />
110        <Label Text="Initial Text" 
111               x:Name="ResultLabel"
112               AutomationId="ResultLabel" />
113    </VerticalStackLayout>
114</ContentPage>
115```
116 
117**HostApp Code-Behind** (`TestCases.HostApp/Issues/Issue12346.xaml.cs`):
118```csharp
119namespace Maui.Controls.Sample.Issues;
120 
121[Issue(IssueTracker.Github, 12346, "Testing XAML binding behavior", PlatformAffected.All)]
122public partial class Issue12346 : ContentPage
123{
124    public Issue12346()
125    {
126        InitializeComponent();
127    }
128 
129    void OnButtonClicked(object sender, EventArgs e)
130    {
131        ResultLabel.Text = "Expected Text";
132    }
133}
134```
135 
136### NUnit Test (Same for Both Examples)
137 
138**NUnit Test** (`TestCases.Shared.Tests/Tests/Issues/Issue12345.cs` or `Issue12346.cs`):
139```csharp
140public class Issue12345 : _IssuesUITest
141{
142    public override string Issue => "Description of the issue being tested";
143 
144    public Issue12345(TestDevice device) : base(device) { }
145 
146    [Test]
147    [Category(UITestCategories.Layout)] // Pick the most appropriate category
148    public void ButtonClickUpdatesLabel()
149    {
150        // Wait for element to be ready
151        App.WaitForElement("TestButton");
152 
153        // Interact with the UI
154        App.Tap("TestButton");
155 
156        // Verify expected behavior
157        var labelText = App.FindElement("ResultLabel").GetText();
158        Assert.That(labelText, Is.EqualTo("Expected Text"));
159 
160        // Optional: Visual verification
161        VerifyScreenshot();
162    }
163}
164```
165 
166## Common Patterns
167 
168### Waiting for Elements
169```csharp
170App.WaitForElement("AutomationId");
171```
172 
173### Interacting with Elements
174```csharp
175App.Tap("AutomationId");
176App.FindElement("AutomationId").GetText();
177var rect = App.WaitForElement("AutomationId").GetRect();
178```
179 
180### Assertions
181```csharp
182Assert.That(actualValue, Is.EqualTo(expectedValue).Within(tolerance));
183Assert.That(rect.Height, Is.LessThanOrEqualTo(maxHeight));
184```
185 
186### Screenshot Verification
187```csharp
188// Verify visual appearance (automated comparison)
189VerifyScreenshot();
190 
191// With custom name
192VerifyScreenshot("CustomTestName");
193 
194// With tolerance (0.0-100.0 percentage) - use sparingly
195VerifyScreenshot(tolerance: 0.5); // Allow 0.5% difference for cross-machine rendering variance
196 
197// PREFERRED: Keep retrying for up to 2 seconds (for animations)
198VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2));
199 
200// Combined: tolerance for rendering variance + retryTimeout for timing
201VerifyScreenshot(tolerance: 0.5, retryTimeout: TimeSpan.FromSeconds(2));
202 
203// Manual screenshot for debugging
204App.Screenshot("TestStep1");
205```
206 
207**CRITICAL - VerifyScreenshot() Built-in Features:**
208 
209`VerifyScreenshot()` **already includes** stability mechanisms. Do NOT add redundant delays:
210 
211| Feature | Behavior | Parameter |
212|---------|----------|-----------|
213| **Android delay** | Automatic 350ms wait for animations | Built-in, cannot override |
214| **Retry logic** | Default: retries once; with retryTimeout: keeps retrying | Built-in |
215| **Retry delay** | 500ms delay between retry attempts | `retryDelay: TimeSpan` (customizable) |
216| **Retry timeout** | Total time to keep retrying | `retryTimeout: TimeSpan` (PREFERRED for flaky tests) |
217| **Tolerance** | Allow percentage difference (0-100) | `tolerance: double` (default: 0.0) |
218 
219**When to customize:**
220- ✅ Use `retryTimeout` parameter for animations with variable timing (PREFERRED approach)
221- ✅ Use small `tolerance` (0.5%) for cross-machine rendering variance, NOT to hide timing issues
222- ✅ Use `retryDelay` if you need to change the delay between retry attempts
223- ❌ **DO NOT** add `Task.Delay()` or `Thread.Sleep()` before `VerifyScreenshot()` - use `retryTimeout` instead
224 
225## Writing Robust UI Tests
226 
227### Best Practices for Screenshot Tests
228 
229When writing tests that use `VerifyScreenshot()`, follow these patterns to avoid flakiness:
230 
231```
232┌─────────────────────────────────────────────────────────────────┐
233│ 1. UNDERSTAND TEST INFRASTRUCTURE                               │
234│    - Read UITest.cs base class implementation                   │
235│    - Understand built-in retry/delay/tolerance mechanisms       │
236│    - Check what helpers/extensions already exist                │
237├─────────────────────────────────────────────────────────────────┤
238│ 2. USE PROPER WAITING PATTERNS                                  │
239│    - Use WaitForElement before interacting with elements        │
240│    - Use retryTimeout for screenshots after animations          │
241│    - Never use arbitrary Task.Delay() before VerifyScreenshot   │
242├─────────────────────────────────────────────────────────────────┤
243│ 3. APPLY MINIMAL TOLERANCES                                     │
244│    - Use retryTimeout for timing issues (preferred)             │
245│    - Use small tolerance (0.5%) only for rendering variance     │
246│    - Never use tolerance > 5% without justification             │
247└─────────────────────────────────────────────────────────────────┘
248```
249 
250### Common Flaky Test Patterns
251 
252| Symptom | Root Cause | Fix Pattern | Anti-Pattern |
253|---------|------------|-------------|--------------|
254| **Visual diff in screenshot** | Animation not finished | `VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2))` | ❌ Adding `Task.Delay()` before |
255| **Element not found** | Element not rendered yet | `App.WaitForElement("Id", timeout: TimeSpan.FromSeconds(10))` | ❌ `Thread.Sleep()` then `FindElement()` |
256| **Timeout on interaction** | Page not fully loaded | Wait for specific element that indicates ready state | ❌ Arbitrary 3-second delay |
257| **Inconsistent rect/position** | Layout not settled | Multiple `GetRect()` calls with comparison | ❌ Single `GetRect()` after delay |
258| **WebView failures** | External URL/network | Use mock URLs instead of external URLs | ❌ Adding longer timeouts |
259 
260### Anti-Patterns (DO NOT DO)
261 
262| Anti-Pattern | Why It's Wrong | Better Alternative |
263|--------------|----------------|-------------------|
264| ❌ `Task.Delay(500).Wait()` before `VerifyScreenshot()` | VerifyScreenshot already has built-in retry; use retryTimeout instead | Use `VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2))` |
265| ❌ `Thread.Sleep(2000)` before element interaction | Arbitrary wait; doesn't guarantee element is ready | `App.WaitForElement("Id", timeout: ...)` |
266| ❌ Adding tolerance > 5% without justification | Hides real bugs; too permissive | Use `retryTimeout` for timing issues; small tolerance (0.5%) for rendering variance |
267| ❌ Using external URLs in WebView tests | External dependency; unreliable | Use mock URLs or local content |
268| ❌ Fixing symptoms without understanding infrastructure | Redundant fixes; doesn't address root cause | Read `UITest.cs` first (step 1 above) |
269 
270### When to Use What
271 
272**VerifyScreenshot() parameters (preferred):**
273```csharp
274// Animation timing issues - keep retrying for up to 2 seconds
275// This is the PREFERRED approach for flaky screenshot tests
276VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2));
277 
278// Small tolerance for cross-machine rendering variance + retryTimeout for timing
279// Use 0.5% tolerance as safety margin, NOT to hide timing issues
280VerifyScreenshot(tolerance: 0.5, retryTimeout: TimeSpan.FromSeconds(2));
281 
282// Legacy: retryDelay only changes delay BETWEEN retries (default 500ms)
283// retryTimeout is preferred because it keeps trying until success
284VerifyScreenshot(retryDelay: TimeSpan.FromSeconds(1));
285```
286 
287**Key difference: retryDelay vs retryTimeout:**
288- `retryDelay`: Delay between retry attempts (default 500ms). Only retries ONCE.
289- `retryTimeout`: Total time to keep retrying. Retries every `retryDelay` until timeout.
290- **Prefer `retryTimeout`** for animations with variable completion times.
291 
292**WaitForElement (for element readiness):**
293```csharp
294// Wait up to 10 seconds for element to appear
295App.WaitForElement("ButtonId", timeout: TimeSpan.FromSeconds(10));
296 
297// Then interact
298App.Tap("ButtonId");
299```
300 
301**Task.Delay/Thread.Sleep (avoid if possible):**
302```csharp
303// AVOID: With retryTimeout, you rarely need explicit delays anymore
304// 
305// Old pattern (before retryTimeout):
306// Task.Delay(300).Wait();
307// VerifyScreenshot(tolerance: 2.0);
308//
309// New pattern (preferred):
310VerifyScreenshot(tolerance: 0.5, retryTimeout: TimeSpan.FromSeconds(2));
311 
312// ONLY use explicit delays when:
313// 1. Waiting for non-element state with no screenshot (rare)
314// 2. External system delay that can't be detected otherwise
315// 3. After exhausting other options AND documenting why
316```
317 
318### Understanding Test Infrastructure
319 
320**Key files to understand when writing UI tests:**
321 
3221. **UITest.cs** - Base class with `VerifyScreenshot()` implementation
323   - Path: `src/Controls/tests/TestCases.Shared.Tests/UITest.cs`
324   - Contains: retry logic, tolerance parsing, platform-specific delays
325 
3262. **_IssuesUITest.cs** - Issues test base class
327   - Path: `src/Controls/tests/TestCases.Shared.Tests/_IssuesUITest.cs`
328   - Contains: Navigation helpers, common patterns
329 
3303. **Extension methods** - Platform-specific helpers
331   - Path: `src/Controls/tests/TestCases.Shared.Tests/` (various extension files)
332   - Contains: Existing helpers for common operations
333 
334**Find existing patterns:**
335```bash
336# See VerifyScreenshot implementation (including retryTimeout)
337grep -A 30 &quot;public void VerifyScreenshot&quot; src/Controls/tests/TestCases.Shared.Tests/UITest.cs
338 
339# Find existing tests using retryTimeout (preferred pattern)
340grep -r &quot;retryTimeout&quot; src/Controls/tests/TestCases.Shared.Tests/Tests/
341 
342# Find existing tolerance patterns
343grep -r &quot;tolerance:&quot; src/Controls/tests/TestCases.Shared.Tests/Tests/
344```
345 
346### Infrastructure Notes
347 
348**Tolerance regex handles multiple locales:** The tolerance parsing uses regex pattern `\d+[.,]\d+` to match both `.` and `,` as decimal separators (e.g., "2.5%" or "2,5%"). If tolerance appears to not be applied, verify the regex patterns in `UITest.cs` `VerifyWithTolerance()` method.
349 
350## Test Categories
351 
352### Category Guidelines
353- Use appropriate categories from `UITestCategories`
354- **Only ONE** `[Category]` attribute per test
355- Pick the most specific category that applies
356 
357### Test Categories
358 
359**CRITICAL**: Always check [UITestCategories.cs](../../src/Controls/tests/TestCases.Shared.Tests/UITestCategories.cs) for the authoritative, complete list of categories.
360 
361**Selection rule**: Choose the MOST SPECIFIC category that applies to your test. If multiple categories seem applicable, choose the one that best describes the primary focus of the test.
362 
363**Common categories** (examples only - not exhaustive):
364- **SafeArea**: `SafeAreaEdges` - Safe area and padding tests
365- **Basic controls**: `Button`, `Label`, `Entry`, `Editor` - Specific control tests
366- **Collection controls**: `CollectionView`, `ListView`, `CarouselView` - Collection control tests
367- **Layout**: `Layout` - Layout-related tests
368- **Navigation**: `Shell`, `Navigation`, `TabbedPage` - Navigation tests
369- **Interaction**: `Gestures`, `Focus`, `Accessibility` - Interaction tests
370- **Lifecycle**: `Window`, `Page`, `LifeCycle` - Page lifecycle tests
371 
372**List all categories programmatically**:
373```bash
374grep -E &quot;public const string [A-Za-z]+ = &quot; src/Controls/tests/TestCases.Shared.Tests/UITestCategories.cs
375```
376 
377**Important**: When a new UI test category is added to `UITestCategories.cs`, also update `eng/pipelines/common/ui-tests.yml` to include the new category.
378 
379## Platform Coverage
380 
381### Default Behavior
382 
383Tests should run on all applicable platforms by default. The test infrastructure handles platform detection automatically.
384 
385### No Inline #if Directives in Test Methods
386 
387**Do NOT use `#if ANDROID`, `#if IOS`, etc. directly in test methods.** Platform-specific behavior must be hidden behind extension methods for readability.
388 
389**Note:** This rule is about **code cleanliness**, not platform scope. Using `#if ANDROID ... #else ...` still compiles for all platforms - the issue is that inline directives make test logic hard to read and maintain.
390 
391```csharp
392// ❌ BAD - inline #if in test method (hard to read)
393[Test]
394public void MyTest()
395{
396#if ANDROID
397    App.TapCoordinates(100, 200);
398#else
399    App.Tap("MyElement");
400#endif
401}
402 
403// ✅ GOOD - platform logic in extension method (clean test)
404[Test]
405public void MyTest()
406{
407    App.TapElementCrossPlatform("MyElement");
408}
409```
410 
411Move platform-specific logic to extension methods to keep test code clean and readable.
412 
413## Running UI Tests Locally
414 
415**CRITICAL: ALWAYS use the BuildAndRunHostApp.ps1 script to run UI tests. NEVER run `dotnet test` or `dotnet build` commands manually.**
416 
417### BuildAndRunHostApp.ps1 Script (ONLY Way to Run Tests)
418 
419**Script location**: `.github/scripts/BuildAndRunHostApp.ps1`
420 
421**Usage:**
422```powershell
423# Run specific test on Android
424pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform android -TestFilter "FullyQualifiedName~Issue12345"
425 
426# Run specific test on iOS
427pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform ios -TestFilter "FullyQualifiedName~Issue12345"
428 
429# Run specific test on MacCatalyst
430pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform maccatalyst -TestFilter "FullyQualifiedName~Issue12345"
431 
432# Run tests by category
433pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform android -Category "SafeAreaEdges"
434 
435# Run specific test with custom device (iOS only)
436pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform ios -TestFilter "Issue12345" -DeviceUdid "12345678-1234567890ABCDEF"
437```
438 
439**What the script handles automatically:**
440- ✅ Automatic device detection and boot (iPhone Xs for iOS, first available for Android)
441- ✅ Building TestCases.HostApp (always fresh build)
442- ✅ App installation and deployment
443- ✅ Running your NUnit test via `dotnet test`
444- ✅ Complete log capture to `CustomAgentLogsTmp/UITests/` directory:
445  - `android-device.log` or `ios-device.log` - Device logs filtered to HostApp
446  - `test-output.log` - Test execution output
447 
448**Why you must use the script:**
449- The script ensures correct device targeting and environment variables
450- It handles platform-specific quirks and setup requirements
451- It provides consistent test execution across all platforms
452- It captures logs automatically for debugging
453- Manual `dotnet` commands often fail due to missing environment setup
454 
455### Prerequisites: Kill Existing Appium Processes
456 
457**CRITICAL**: Before running UITests with BuildAndRunHostApp.ps1, always kill any existing Appium processes. The UITest framework needs to start its own Appium server, and having a stale process running will cause the tests to fail with an error like:
458 
459```
460AppiumServerHasNotBeenStartedLocallyException: The local appium server has not been started.
461Time 120000 ms for the service starting has been expired!
462```
463 
464**Solution: Always kill existing Appium processes before running tests:**
465 
466```bash
467# Kill any Appium processes on port 4723
468lsof -i :4723 | grep LISTEN | awk '{print $2}' | xargs kill -9 2&gt;/dev/null && echo &quot;✅ Killed existing Appium processes&quot; || echo &quot;ℹ️ No Appium processes running on port 4723&quot;
469```
470 
471**Why this is needed:** The UITest framework automatically starts and manages its own Appium server. If there's already an Appium process running (from a previous test run or manual testing), the framework will timeout trying to start a new one.
472 
473### Troubleshooting
474 
475**Android App Crashes on Launch:**
476 
477If you encounter navigation fragment errors or resource ID issues:
478```
479java.lang.IllegalArgumentException: No view found for id 0x7f0800f8 (com.microsoft.maui.uitests:id/inward) for fragment NavigationRootManager_ElementBasedFragment
480```
481 
482**Solution:** Read the crash logs to find the actual exception:
483```bash
484# Monitor logcat for the crash
485adb logcat | grep -E &quot;(FATAL|AndroidRuntime|Exception|Error|Crash)&quot;
486```
487 
488**Debugging steps:**
4891. **Find the exception** in logcat - look for the stack trace
4902. **Investigate the root cause** - What line of code is throwing? Why?
4913. **Check for null references** - Are required resources missing?
4924. **Verify resource IDs exist** - Check if the ID referenced actually exists in the app
4935. If you can't determine the fix, **ask for guidance** with the full exception details
494 
495**iOS App Crashes on Launch or Won't Start with Appium:**
496 
497If the iOS app crashes when launched by Appium or manually with `xcrun simctl launch`:
498 
499**Solution:** Read the crash logs to find the actual exception:
500```bash
501# Capture crash logs
502xcrun simctl spawn booted log stream --predicate 'processImagePath contains "TestCases.HostApp"' --level=debug &gt; /tmp/ios_crash.log 2&gt;&amp;1 &amp;
503LOG_PID=$!
504 
505# Try to launch the app
506xcrun simctl launch $UDID com.microsoft.maui.uitests
507 
508# Wait a moment for crash
509sleep 3
510 
511# Stop log capture
512kill $LOG_PID
513 
514# Review the crash log
515cat /tmp/ios_crash.log | grep -A 20 -B 5 &quot;Exception&quot;
516```
517 
518**Debugging steps:**
5191. **Find the exception** in the crash log - look for stack traces
5202. **Investigate the root cause** - What's causing the crash?
5213. **Check for missing resources** - Are all required files included in the bundle?
5224. **Verify Info.plist** - Are required keys present?
5235. **Check for platform-specific issues** - iOS version compatibility, permissions, etc.
5246. If you can't determine the fix, **ask for guidance** with the full exception details
525 
526### Dangerous System Commands (Never Run)
527 
528**🚨 NEVER run these commands — they cause destructive system-wide side effects:**
529 
530- **`tccutil reset`** — Wipes ALL macOS permissions (Accessibility, Camera, etc.) system-wide. This breaks Appium/WebDriverAgent, Xcode, and other tools. Once reset, permissions must be manually re-granted through System Settings.
531- **`csrutil disable`** — Disables System Integrity Protection
532- **`networksetup`** — Modifies network configuration
533- **`defaults delete`** on system domains — Resets system preferences
534 
535**General rule:** Do not run commands that modify macOS system-level privacy, security, or permission settings. If you need to check permissions, read them — never reset or modify them.
536 
537## Before Committing
538 
539Verify the following checklist before committing UI tests:
540 
541- [ ] Compile both the HostApp project and TestCases.Shared.Tests project successfully
542- [ ] Verify AutomationId references match between HostApp UI (C# or XAML) and test code
543- [ ] Ensure file names follow the `IssueXXXXX` pattern and match between projects
544- [ ] Ensure test methods have descriptive names
545- [ ] Verify test inherits from `_IssuesUITest`
546- [ ] Confirm only ONE `[Category]` attribute per test
547- [ ] No inline `#if` directives in test code (use extension methods)
548- [ ] Test passes locally on at least one platform
549 
550### Test State Management
551 
552- Tests should be independent and not rely on state from other tests
553- The test infrastructure handles navigation to the test page and basic cleanup
554- If your test modifies global app state, consider whether cleanup is needed
555- Most tests don't require explicit cleanup as each test gets a fresh page instance
556 
557## Best Practices
558 
559### Default: C# Over XAML
560 
561**Use C# files (`.cs`) for UI tests. Only use XAML files (`.xaml`) when the test scenario requires XAML-specific features.**
562 
563**When to use C# only (`.cs` file):**
564- ✅ Simple control tests (Button, Label, Entry, etc.)
565- ✅ Layout tests (Grid, StackLayout, FlexLayout, etc.)
566- ✅ Navigation tests
567- ✅ Event handling tests
568- ✅ Property tests
569- ✅ Most UI behavior tests
570 
571**When XAML is required (`.xaml` + `.xaml.cs` files):**
572- ✅ Testing XAML binding syntax
573- ✅ Testing XAML templates (DataTemplate, ControlTemplate)
574- ✅ Testing XAML styles and resources
575- ✅ Testing XAML markup extensions
576- ✅ Testing XamlC compilation behavior
577- ✅ Testing XAML-specific parsing or compilation issues
578 
579**Examples:**
580 
581```csharp
582// ✅ GOOD: C# only test (most common pattern)
583public class Issue12345 : ContentPage
584{
585    public Issue12345()
586    {
587        Content = new StackLayout
588        {
589            Children =
590            {
591                new Label { Text = "Hello", AutomationId = "MyLabel" },
592                new Button { Text = "Click Me", AutomationId = "MyButton" }
593            }
594        };
595    }
596}
597```
598 
599```xaml
600<!-- ❌ AVOID unless testing XAML bindings/templates/styles -->
601<ContentPage ...>
602    <StackLayout>
603        <Label Text="Hello" AutomationId="MyLabel" />
604        <Button Text="Click Me" AutomationId="MyButton" />
605    </StackLayout>
606</ContentPage>
607```
608 
609### Use Test Helper Base Classes
610 
611**ALWAYS check for and use existing test helper base classes instead of creating from scratch:**
612 
613| Base Class | Use For | Example |
614|------------|---------|---------|
615| `TestShell` | Shell-related tests | `public class Issue12345 : TestShell` |
616| `TestContentPage` | ContentPage tests needing `Init()` pattern | `public class Issue12345 : TestContentPage` |
617| `TestNavigationPage` | NavigationPage tests | `public class Issue12345 : TestNavigationPage` |
618| `ContentPage` | Simple page tests (direct inheritance) | `public class Issue12345 : ContentPage` |
619 
620**TestShell provides:**
621- Platform-specific automation IDs for flyout and back buttons
622- Helper methods: `AddContentPage()`, `AddBottomTab()`, `AddTopTab()`, `AddFlyoutItem()`
623- Abstract `Init()` method for setup
624- `DisplayedPage` property for accessing current page
625 
626**TestContentPage/TestNavigationPage provide:**
627- Abstract `Init()` method for deferred initialization
628- Cleaner separation of setup logic
629 
630**Example:**
631 
632```csharp
633// ✅ GOOD: Using TestShell for Shell tests
634[Issue(IssueTracker.Github, 12345, "Shell navigation bug", PlatformAffected.All)]
635public class Issue12345 : TestShell
636{
637    protected override void Init()
638    {
639        AddContentPage(new ContentPage 
640        { 
641            Content = new Label { Text = "Test" } 
642        });
643    }
644}
645 
646// ❌ BAD: Creating Shell from scratch
647public class Issue12345 : Shell
648{
649    public Issue12345()
650    {
651        Items.Add(new ShellItem { ... }); // Verbose, error-prone
652    }
653}
654```
655 
656### Avoid Obsolete APIs
657 
658**NEVER use obsolete APIs in new tests. Use modern equivalents:**
659 
660| ❌ Obsolete API | ✅ Modern API | Notes |
661|----------------|--------------|-------|
662| `Application.MainPage` | `Window.Page` | Access via `this.Window.Page` in ContentPage |
663| `Application.MainPage` | `Application.Current.Windows[0].Page` | When not in Page context |
664| `Frame` | `Border` | Frame is deprecated, use Border instead |
665| `Device.BeginInvokeOnMainThread` | `Dispatcher.Dispatch` or `MainThread.BeginInvokeOnMainThread` | Modern threading APIs |
666 
667**Examples:**
668 
669```csharp
670// ✅ GOOD: Modern Window API
671this.Window.Page = new NavigationPage(new MyPage());
672 
673// ❌ BAD: Obsolete Application.MainPage
674Application.MainPage = new NavigationPage(new MyPage());
675 
676// ✅ GOOD: Border
677new Border { Content = new Label { Text = "Hello" } }
678 
679// ❌ BAD: Frame (deprecated)
680new Frame { Content = new Label { Text = "Hello" } }
681```
682 
683### Use UITest Optimized Controls for Screenshot Tests
684 
685**For tests that use `VerifyScreenshot()`, use UITest optimized controls instead of standard text input controls.** These controls provide `IsCursorVisible` to prevent cursor blinking from causing flaky screenshot comparisons.
686 
687| Standard Control | UITest Control | Purpose |
688|------------------|----------------|---------|
689| `Entry` | `UITestEntry` | Text input without cursor blink |
690| `Editor` | `UITestEditor` | Multi-line input without cursor blink |
691| `SearchBar` | `UITestSearchBar` | Search input without cursor blink |
692 
693**Example:**
694 
695```csharp
696// For screenshot tests, use UITest controls (UITestEntry, UITestEditor, UITestSearchBar)
697var entry = new UITestEntry
698{
699    Placeholder = "Enter text",
700    IsCursorVisible = false,  // Prevents flaky screenshots
701    AutomationId = "TestEntry"
702};
703 
704// For non-screenshot tests, standard Entry is fine
705var entry = new Entry { Placeholder = "Enter text", AutomationId = "TestEntry" };
706```
707 
708**Location:** `src/Controls/tests/TestCases.HostApp/Controls/UITest*.cs`
709 
710### Check Similar Tests for Patterns
711 
712**Before creating a new test, search for similar tests to reuse patterns:**
713 
714```bash
715# Find similar control tests
716grep -r &quot;class.*Issue.*Button&quot; src/Controls/tests/TestCases.HostApp/Issues/*.cs
717 
718# Find Shell tests
719grep -r &quot;TestShell&quot; src/Controls/tests/TestCases.HostApp/Issues/*.cs
720 
721# Find tests for specific control
722grep -r &quot;CollectionView&quot; src/Controls/tests/TestCases.HostApp/Issues/*.cs
723 
724# Find tests using UITest optimized controls
725grep -r &quot;UITestEntry\|UITestEditor\|UITestSearchBar&quot; src/Controls/tests/TestCases.HostApp/Issues/*.cs
726```
727 
728**Reuse established patterns:**
729- AutomationId naming conventions
730- Test structure and layout
731- Common helper methods
732- Platform-specific workarounds
733- UITest optimized control usage
734 
735### Safe Area Testing (iOS/MacCatalyst)
736 
737**⚠️ CRITICAL for macCatalyst safe area tests:**
738 
739Safe area behavior differs significantly between macOS versions. Tests must account for this variability.
740 
741| macOS Version | Title Bar Safe Area | CI Environment |
742|---------------|---------------------|----------------|
743| **macOS 14/15** | ~28px top inset | ✅ Used by CI |
744| **macOS 26 (Liquid Glass)** | ~0px top inset | ❌ Local dev only |
745 
746**Rules for safe area tests:**
747 
7481. **Use tolerances for safe area measurements** - Exact pixel values vary by macOS version
7492. **Test behavior, not exact values** - Verify content is NOT obscured, rather than checking exact padding pixels
7503. **Use `GetRect()` for child content position** - Measure where content actually appears, not parent size
7514. **Never hardcode safe area expectations** - Tests should pass on macOS 14/15 AND macOS 26
752 
753**Example patterns:**
754 
755```csharp
756// ❌ BAD: Hardcoded safe area value (breaks across macOS versions)
757var safeArea = element.GetRect();
758Assert.That(safeArea.Y, Is.EqualTo(28)); // Fails on macOS 26
759 
760// ✅ GOOD: Test that content is not obscured by title bar
761var contentRect = App.WaitForElement("MyContent").GetRect();
762var titleBarRect = App.WaitForElement("TitleBar").GetRect();
763Assert.That(contentRect.Y, Is.GreaterThanOrEqualTo(titleBarRect.Height), 
764    "Content should not be obscured by title bar");
765 
766// ✅ GOOD: Use tolerance for safe area (accounts for OS differences)
767Assert.That(contentRect.Y, Is.GreaterThan(0).And.LessThan(50), 
768    "Content should have some top padding but not excessive");
769```
770 
771**Test category**: Use `UITestCategories.SafeAreaEdges` for safe area tests.
772 
773**Platform scope**: Safe area tests should typically run on iOS and MacCatalyst (not just one).
774 
775**See also**: `.github/instructions/safe-area-debugging.instructions.md` for investigation guidelines
776