Improve write-tests-agent with best practices

[sheiksyedm]

Add comprehensive reinforcement guidelines to prevent common mistakes:

1. Prefer C# Over XAML

   • Default to .cs files for most UI tests
   • Only use XAML for binding/template/style/resource tests
   • Includes clear examples and decision criteria

2. Use Test Helper Base Classes

   • Document TestShell, TestContentPage, TestNavigationPage
   • Show helper methods and when to use each
   • Prevent creating Shell tests from scratch

3. Avoid Obsolete APIs

   • Map obsolete → modern APIs (Application.MainPage → Window.Page)
   • Cover Frame → Border deprecation
   • Include modern threading API guidance

4. Use UITest Optimized Controls

   • Always use UITestEntry, UITestEditor, UITestSearchBar
   • Controls provide IsCursorVisible to prevent flaky screenshots
   • Cursor blinking causes visual test failures
   • Includes examples and location of controls

5. Check Similar Tests for Patterns

   • Add bash commands to search for similar tests
   • Encourage reusing established patterns
   • Help agent learn from existing examples

These additions address real scenarios encountered during test creation and will help the agent make better decisions automatically.

[PureWeen]

Review: Content is Valuable, but Wrong Location

Thanks for contributing these best practices! The guidance is practical and addresses real issues we've seen. However, the content should be moved to a different file.

The Content is Good ✅

Section	Value
1. Prefer C# Over XAML	✅ Reduces unnecessary XAML complexity
2. Use Test Helper Base Classes	✅ Documents TestShell, TestContentPage - not well documented elsewhere
3. Avoid Obsolete APIs	✅ Prevents compiler warnings
4. Use UITest Optimized Controls	✅ Prevents flaky tests from cursor blinking
5. Check Similar Tests	✅ Encourages pattern reuse

The Location is Wrong ❌

Current location: .github/agents/write-tests-agent.md

Problem: This is an agent file, not a guidance file. Agents should be lightweight dispatchers that invoke skills.

File Type	Purpose	Size Guideline
Agent (.github/agents/*.md)	Dispatch to skills, minimal logic	<100 lines ideal
Skill (.github/skills/*/SKILL.md)	Detailed workflow, procedures	<500 lines
Instructions (.github/instructions/*.md)	Reference guidance, auto-loaded by glob	Unlimited

The agent file is now 322 lines - way over the ideal size for an agent (~50-100 lines).

Recommended Fix

Move all 5 sections to .github/instructions/uitests.instructions.md

This is the correct location because:

1. Auto-loaded for relevant files - Has applyTo: "src/Controls/tests/TestCases.Shared.Tests/**,src/Controls/tests/TestCases.HostApp/**"
2. Reference material - Best practices are reference guidance, not workflow
3. Already exists - This file is the canonical place for UI test guidance
4. Agent should stay thin - write-tests-agent should just dispatch to skills

Suggested Structure in uitests.instructions.md

Add a new section near the end:

## Best Practices

### Prefer C# Over XAML
[Your content here]

### Use Test Helper Base Classes  
[Your content here]

### Avoid Obsolete APIs
[Your content here]

### Use UITest Optimized Controls
[Your content here]

### Check Similar Tests for Patterns
[Your content here]

Summary

• ✅ Content: Valuable, keep it
• ❌ Location: Move to uitests.instructions.md
• ❌ Agent size: Revert agent to its original thin state

Please move the content and I'll be happy to approve. Thanks for the contribution!

[Copilot]

Pull request overview

This PR adds comprehensive best practices guidance to the write-tests-agent to help it avoid common mistakes when creating UI tests. The changes provide clear decision criteria, examples, and search commands to help the agent make better architectural decisions automatically.

Changes:

• Added "Prefer C# Over XAML" guideline with clear decision criteria and examples
• Documented test helper base classes (TestShell, TestContentPage, TestNavigationPage) with usage examples
• Mapped obsolete APIs to modern equivalents (Application.MainPage → Window.Page, Frame → Border, Device.BeginInvokeOnMainThread → modern threading APIs)
• Added UITest optimized controls guidance (UITestEntry, UITestEditor, UITestSearchBar) to prevent flaky screenshot tests
• Included bash commands to search for similar tests and reuse established patterns

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
.github/instructions/uitests.instructions.md	Added comprehensive Best Practices section with 5 subsections covering C# vs XAML preference, test helper base classes, obsolete API avoidance, UITest optimized controls, and pattern reuse guidance
.github/agents/write-tests-agent.md	Added reference to the new best practices section in the uitests.instructions.md file with summary of key topics

[sheiksyedm]

Review: Content is Valuable, but Wrong Location

Thanks for contributing these best practices! The guidance is practical and addresses real issues we've seen. However, the content should be moved to a different file.

The Content is Good ✅

Section Value

1. Prefer C# Over XAML ✅ Reduces unnecessary XAML complexity
2. Use Test Helper Base Classes ✅ Documents TestShell, TestContentPage - not well documented elsewhere
3. Avoid Obsolete APIs ✅ Prevents compiler warnings
4. Use UITest Optimized Controls ✅ Prevents flaky tests from cursor blinking
5. Check Similar Tests ✅ Encourages pattern reuse

The Location is Wrong ❌

Current location: .github/agents/write-tests-agent.md

Problem: This is an agent file, not a guidance file. Agents should be lightweight dispatchers that invoke skills.

File Type Purpose Size Guideline
Agent (.github/agents/*.md) Dispatch to skills, minimal logic <100 lines ideal
Skill (.github/skills/*/SKILL.md) Detailed workflow, procedures <500 lines
Instructions (.github/instructions/*.md) Reference guidance, auto-loaded by glob Unlimited
The agent file is now 322 lines - way over the ideal size for an agent (~50-100 lines).

Recommended Fix

Move all 5 sections to .github/instructions/uitests.instructions.md

This is the correct location because:

1. Auto-loaded for relevant files - Has applyTo: "src/Controls/tests/TestCases.Shared.Tests/**,src/Controls/tests/TestCases.HostApp/**"
2. Reference material - Best practices are reference guidance, not workflow
3. Already exists - This file is the canonical place for UI test guidance
4. Agent should stay thin - write-tests-agent should just dispatch to skills

Suggested Structure in uitests.instructions.md

Add a new section near the end:

## Best Practices

### Prefer C# Over XAML
[Your content here]

### Use Test Helper Base Classes  
[Your content here]

### Avoid Obsolete APIs
[Your content here]

### Use UITest Optimized Controls
[Your content here]

### Check Similar Tests for Patterns
[Your content here]

Summary

• ✅ Content: Valuable, keep it
• ❌ Location: Move to uitests.instructions.md
• ❌ Agent size: Revert agent to its original thin state

Please move the content and I'll be happy to approve. Thanks for the contribution!

The review concern is completely valid and well‑reasoned, and I have made the changes based on it. I also consulted with different agents, and one of them provided a minor concern, which has also been addressed in this PR. Now the PR changes is perfect.