Copilot instructions

1---
2description: "Guidelines for writing XAML unit tests in the Controls.Xaml.UnitTests project"
3applyTo: "src/Controls/tests/Xaml.UnitTests/**"
4---
5 
6# XAML Unit Testing Guidelines
7 
8This guide provides conventions for writing XAML unit tests in `src/Controls/tests/Xaml.UnitTests/`.
9 
10## 1. File Naming and Location for Issue Tests
11 
12When writing a test for a GitHub issue:
13 
14- **Location**: Place the test file in the `Issues/` folder
15- **Naming convention**: `MauiXXXXX.xaml` and `MauiXXXXX.xaml.cs` (where XXXXX is the GitHub issue number)
16 
17**Example:**
18```
19src/Controls/tests/Xaml.UnitTests/Issues/
20├── Maui12345.xaml
21└── Maui12345.xaml.cs
22```
23 
24## 2. Basic Test Pattern
25 
26Most unit tests will:
271. Check that the XAML page can be created/inflated
282. Perform some assertions on the created page
293. Apply to all `[XamlInflator]` test variations (runtime, XamlC, SourceGen)
30 
31**XAML file (Maui12345.xaml):**
32```xaml
33<?xml version="1.0" encoding="utf-8" ?>
34<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
35             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
36             x:Class="Microsoft.Maui.Controls.Xaml.UnitTests.Maui12345">
37    <!-- Your test content -->
38</ContentPage>
39```
40 
41**Code-behind (Maui12345.xaml.cs):**
42```csharp
43namespace Microsoft.Maui.Controls.Xaml.UnitTests;
44 
45public partial class Maui12345 : ContentPage
46{
47    public Maui12345()
48    {
49        InitializeComponent();
50    }
51 
52    [TestFixture]
53    class Tests
54    {
55        [Test]
56        public void MyTest([Values] XamlInflator inflator)
57        {
58            var page = new Maui12345(inflator);
59            Assert.That(page, Is.Not.Null);
60            // Additional assertions
61        }
62    }
63}
64```
65 
66**Note**: Only add `[SetUp]` and `[TearDown]` methods if your test requires special initialization (e.g., setting up `DispatcherProvider` or `Application.Current`). Most tests don't need them.
67 
68## 3. Testing IL Correctness (XamlC) or Source Generation
69 
70When the test specifically validates compile-time behavior for a specific inflator:
71 
72**XamlC (IL generation):**
73```csharp
74[Test]
75public void MyTest([Values] XamlInflator inflator)
76{
77    if (inflator == XamlInflator.XamlC)
78        Assert.Throws<BuildException>(() => MockCompiler.Compile(typeof(Maui12345)));
79    else
80    {
81        var page = new Maui12345(inflator);
82        Assert.That(page, Is.Not.Null);
83    }
84}
85```
86 
87**Source Generation:**
88```csharp
89using static Microsoft.Maui.Controls.Xaml.UnitTests.MockSourceGenerator;
90 
91[Test]
92public void MyTest([Values] XamlInflator inflator)
93{
94    if (inflator == XamlInflator.SourceGen)
95    {
96        var result = CreateMauiCompilation()
97            .WithAdditionalSource(
98"""
99namespace Microsoft.Maui.Controls.Xaml.UnitTests;
100 
101[XamlProcessing(XamlInflator.Runtime, true)]
102public partial class Maui12345 : ContentPage
103{
104    public Maui12345() => InitializeComponent();
105}
106""")
107            .RunMauiSourceGenerator(typeof(Maui12345));
108        Assert.That(result.Diagnostics, Is.Empty); // or Is.Not.Empty for error cases
109    }
110    else
111    {
112        var page = new Maui12345(inflator);
113        Assert.That(page, Is.Not.Null);
114    }
115}
116```
117 
118## 4. Handling Invalid Code Generation
119 
120When testing scenarios where code generation is **expected to fail** or produce invalid code, use special file extensions to prevent build failures:
121 
122| Extension | Behavior | Use Case |
123|-----------|----------|----------|
124| `.rt.xaml` | Runtime inflation only | XamlC/SourceGen should fail, but runtime should work |
125| `.rtsg.xaml` | Runtime + SourceGen only | XamlC should fail |
126| `.rtxc.xaml` | Runtime + XamlC only | SourceGen should fail |
127 
128**Why?** These extensions prevent the compiler and build tasks from processing the XAML file, allowing your test to execute and verify the expected behavior.
129 
130**Example:**
131```
132Issues/
133├── Maui12345.rt.xaml      # Only inflated at runtime (compiler/sourcegen skip)
134└── Maui12345.xaml.cs
135```
136 
137## Quick Reference
138 
139| Scenario | Location | Naming | Special Extension |
140|----------|----------|--------|-------------------|
141| Issue test | `Issues/` | `MauiXXXXX.*` | None (unless invalid codegen) |
142| Invalid XamlC | `Issues/` | `MauiXXXXX.rt.xaml` | `.rt.xaml` |
143| Invalid SourceGen | `Issues/` | `MauiXXXXX.rt.xaml` or `.rtxc.xaml` | Depends on what should fail |
144| Test XamlC IL | Anywhere | Any | Use `MockCompiler` |
145| Test SourceGen | Anywhere | Any | Use `MockSourceGenerator` |
146 
147## Related Documentation
148 
149- `.github/copilot-instructions.md` - General MAUI development guidelines
150- `.github/instructions/uitests.instructions.md` - UI testing guidelines (different from XAML unit tests)
151