maui: Instructions file for GitHub Copilot

XAML Unit Testing Guidelines

This guide provides conventions for writing XAML unit tests in src/Controls/tests/Xaml.UnitTests/.

1. File Naming and Location for Issue Tests

When writing a test for a GitHub issue:

• Location: Place the test file in the Issues/ folder
• Naming convention: MauiXXXXX.xaml and MauiXXXXX.xaml.cs (where XXXXX is the GitHub issue number)

Example:

src/Controls/tests/Xaml.UnitTests/Issues/
├── Maui12345.xaml
└── Maui12345.xaml.cs

2. Basic Test Pattern

Most unit tests will:

1. Check that the XAML page can be created/inflated
2. Perform some assertions on the created page
3. Apply to all [XamlInflator] test variations (runtime, XamlC, SourceGen)

XAML file (Maui12345.xaml):

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="Microsoft.Maui.Controls.Xaml.UnitTests.Maui12345">
    <!-- Your test content -->
</ContentPage>

Code-behind (Maui12345.xaml.cs):

namespace Microsoft.Maui.Controls.Xaml.UnitTests;

public partial class Maui12345 : ContentPage
{
    public Maui12345()
    {
        InitializeComponent();
    }

    [TestFixture]
    class Tests
    {
        [Test]
        public void MyTest([Values] XamlInflator inflator)
        {
            var page = new Maui12345(inflator);
            Assert.That(page, Is.Not.Null);
            // Additional assertions
        }
    }
}

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.

3. Testing IL Correctness (XamlC) or Source Generation

When the test specifically validates compile-time behavior for a specific inflator:

XamlC (IL generation):

[Test]
public void MyTest([Values] XamlInflator inflator)
{
    if (inflator == XamlInflator.XamlC)
        Assert.Throws<BuildException>(() => MockCompiler.Compile(typeof(Maui12345)));
    else
    {
        var page = new Maui12345(inflator);
        Assert.That(page, Is.Not.Null);
    }
}