Creates UI tests for a GitHub issue and verifies they reproduce the bug. Iterates until tests actually fail (proving they catch the issue). Use when PR lacks tests or tests need to be created for an issue.
npxskills add dotnet/maui--skill write-ui-testsLoading…
Creates UI tests that reproduce a GitHub issue, following .NET MAUI conventions. Verifies the tests actually fail before completing.
YOU CANNOT COMPLETE THIS SKILL UNTIL TESTS FAIL.
A test that passes does NOT prove it catches the bug. You MUST:
If tests keep passing after 3 iterations:
Common mistakes that lead to passing tests:
Before invoking, ensure you have:
Platform selection guidance:
platform/iOS label → test on iOS firstplatform/Android label → test on Android firstcat .github/instructions/uitests.instructions.md
This contains the authoritative conventions for:
IssueXXXXX.cs for C#-only, or IssueXXXXX.xaml/.xaml.cs for XAML)TestCases.HostApp/Issues/, TestCases.Shared.Tests/Tests/Issues/)[Issue()], [Category()])Location: src/Controls/tests/TestCases.HostApp/Issues/IssueXXXXX.cs
namespace Maui.Controls.Sample.Issues;
[Issue(IssueTracker.Github, XXXXX, "Brief description of issue", PlatformAffected.All)]
public partial class IssueXXXXX : ContentPage
{
public IssueXXXXX()
{
// Create UI that reproduces the issue
var button = new Button
{
Text = "Test Button",
AutomationId = "TestButton" // Required for Appium
};
var resultLabel = new Label
{
Text = "Waiting...",
AutomationId = "ResultLabel"
};
button.Clicked += (s, e) =>
{
resultLabel.Text = "Success";
};
Content = new VerticalStackLayout
{
Children = { button, resultLabel }
};
}
}
Key requirements:
AutomationId to all interactive elements[Issue()] attribute with tracker, number, description, platformNote: XAML is optional. C#-only pages (as shown above) are simpler and preferred for most test scenarios. Use XAML only when the bug specifically relates to XAML parsing or markup behavior.
Location: src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs
namespace Microsoft.Maui.TestCases.Tests.Issues;
public class IssueXXXXX : _IssuesUITest
{
public override string Issue => "Brief description matching HostApp";
public IssueXXXXX(TestDevice device) : base(device) { }
[Test]
[Category(UITestCategories.Button)] // Pick ONE appropriate category
public void ButtonClickUpdatesLabel()
{
// Wait for element to be ready
App.WaitForElement("TestButton");
// Interact with the UI
App.Tap("TestButton");
// Verify expected behavior
var labelText = App.FindElement("ResultLabel").GetText();
Assert.That(labelText, Is.EqualTo("Success"));
}
}
Key requirements:
_IssuesUITestAutomationId values as HostApp[Category()] attribute (check UITestCategories.cs for options)App.WaitForElement() before interactions# For Android
dotnet build src/Controls/tests/TestCases.HostApp/Controls.TestCases.HostApp.csproj -c Debug -f net10.0-android --no-restore -v q
# For iOS
dotnet build src/Controls/tests/TestCases.HostApp/Controls.TestCases.HostApp.csproj -c Debug -f net10.0-ios --no-restore -v q
# Test project (platform-independent)
dotnet build src/Controls/tests/TestCases.Shared.Tests/Controls.TestCases.Shared.Tests.csproj -c Debug --no-restore -v q
Tests must FAIL to prove they catch the bug. Run verification:
pwsh .github/skills/verify-tests-fail-without-fix/scripts/verify-tests-fail.ps1 -Platform <platform> -TestFilter "IssueXXXXX"
Replace <platform> with android, ios, or maccatalyst based on the issue's affected platforms.
The script auto-detects that only test files exist (no fix files) and runs in "verify failure only" mode.
Why FAIL = success? The test must fail NOW (before the fix) to prove it catches the bug. After the fix is applied, it should pass. A test that passes now proves nothing.
If tests FAIL → ✅ Success! Tests correctly reproduce the bug. Proceed to Output.
If tests PASS → ❌ STOP. Test doesn't catch the bug. Iterate:
Console.WriteLine in HostApp to trace execution"Tests are passing after 3 iterations. This means either: (a) my test scenario doesn't correctly reproduce the bug, (b) the bug may already be fixed on this branch, or (c) I'm missing something from the issue description. How would you like me to proceed?"
Common reasons tests pass when they shouldn't:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Test passes on all attempts | Test scenario doesn't match bug | Re-read issue reproduction steps carefully |
| Test asserts pass but bug exists | Asserting wrong property/element | Check what exactly the bug affects |
| Works on Android, fails on iOS | Bug is platform-specific | Try both platforms |
| Bug involves timing | Race condition not captured | Add delays or event handlers |
| Bug involves navigation | Page lifecycle not exercised | Ensure pages are actually pushed/popped |
Do NOT mark this skill complete until tests FAIL.
⚠️ ONLY use this output format if tests FAIL. If tests pass, you have not completed this skill.
After completion (tests verified to fail), report:
✅ Tests created and verified for Issue #XXXXX
**Files:**
- `src/Controls/tests/TestCases.HostApp/Issues/IssueXXXXX.cs`
- `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs`
**Test method:** `ButtonClickUpdatesLabel`
**Category:** `UITestCategories.Button`
**Verification:** Tests FAIL as expected (bug reproduced)
**Failure message:** `Expected "X" but got "Y"` (include actual assertion failure)
If tests PASS after multiple iterations, report instead:
⚠️ Tests created but NOT verified for Issue #XXXXX
**Files:** [list files]
**Status:** Tests PASS when they should FAIL
**Iterations tried:** 3
**Problem:** [describe why test may not be catching the bug]
**Next steps:** Need guidance on reproduction steps
// HostApp: Add a way to trigger and observe the property
var picker = new Picker { AutomationId = "TestPicker" };
var statusLabel = new Label { AutomationId = "StatusLabel" };
picker.PropertyChanged += (s, e) => {
if (e.PropertyName == nameof(Picker.IsOpen))
statusLabel.Text = $"IsOpen={picker.IsOpen}";
};
// Test: Verify the property changes correctly
App.Tap("TestPicker");
App.WaitForElement("StatusLabel");
var status = App.FindElement("StatusLabel").GetText();
Assert.That(status, Does.Contain("IsOpen=True"));
// Test: Use GetRect() for position/size assertions
var rect = App.WaitForElement("TestElement").GetRect();
Assert.That(rect.Height, Is.GreaterThan(0));
Assert.That(rect.Y, Is.GreaterThanOrEqualTo(safeAreaTop));
// Use retryTimeout for animations - keeps retrying until success
App.Tap("AnimatedButton");
VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2));
// retryTimeout handles timing variance, small tolerance for cross-machine rendering
VerifyScreenshot(tolerance: 0.5, retryTimeout: TimeSpan.FromSeconds(2));
// Only limit platforms when NECESSARY
[Test]
[Category(UITestCategories.Picker)]
public void PickerDismissResetsIsOpen()
{
// This test should run on all platforms unless there's
// a specific technical reason it can't
App.WaitForElement("TestPicker");
// ...
}
When running tests on iOS, you may need to target a specific device or iOS version:
# Default: iPhone Xs with iOS 18.5
pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform ios -TestFilter "Issue12345"
# Find iPhone Xs with iOS 18.5 and get its UDID
UDID=$(xcrun simctl list devices available --json | jq -r '
.devices | to_entries
| map(select(.key | contains("iOS-18-5")))
| map(.value) | flatten
| map(select(.name == "iPhone Xs")) | first | .udid')
# Run with specific device
pwsh .github/scripts/BuildAndRunHostApp.ps1 -Platform ios -TestFilter "Issue12345" -DeviceUdid "$UDID"
Finding different device/version combinations:
# iPhone 16 Pro with any iOS version
UDID=$(xcrun simctl list devices available --json | jq -r '
.devices[][] | select(.name == "iPhone 16 Pro") | .udid' | head -1)
# Any device with iOS 18.0
UDID=$(xcrun simctl list devices available --json | jq -r '
.devices | to_entries
| map(select(.key | contains("iOS-18-0")))
| map(.value) | flatten | .[0].udid')
Before running verify-tests-fail.ps1, confirm:
TestCases.HostApp/Issues/IssueXXXXX.csTestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs[Issue()] attribute present with all parametersAutomationId values match between HostApp and test_IssuesUITest[Category()] attribute from UITestCategories.cs.github/instructions/uitests.instructions.mdsrc/Controls/tests/TestCases.Shared.Tests/UITestCategories.cssrc/Controls/tests/TestCases.Shared.Tests/Tests/Issues/
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).