Extract markdown documentation changes from PR #32064 and merge enhancements from PR #32270 #32280

Copilot · 2025-10-29T20:30:58Z

Updates .github/copilot-instructions.md to simplify UI Testing Guidelines section, reorganizes template instructions, and merges comprehensive UI testing documentation enhancements from PR #32270.

Summary

This PR extracts only the markdown documentation changes from PR #32064 (Fix SafeAreaEdges.SoftInput applying bottom padding when keyboard is hidden) and merges additional UI testing documentation enhancements from PR #32270.

Changes Made

Documentation Files with Frontmatter Metadata:
All markdown documentation files now include standardized frontmatter with description and date fields for tracking:

.github/copilot-instructions.md - GitHub Copilot-specific quick reference
.github/instructions/templates.instructions.md - Template-specific instructions
.github/instructions/uitests.instructions.md - UI test-specific instructions
docs/UITesting-Guide.md - Comprehensive practical UI testing guide
docs/design/UITesting-Architecture.md - Architecture and CI/CD integration

Code Quality Improvements:

Added language identifiers to all code blocks (bash, csharp, xaml, powershell) for proper syntax highlighting
Fixed indentation inconsistencies in C# code examples (standardized to 4-space indentation)

Documentation Organization:

.github/copilot-instructions.md:
- Simplified UI Testing Guidelines to key reminders
- Added links to comprehensive documentation resources
- Clean separation between quick tips and detailed guides
.github/instructions/templates.instructions.md:
- Moved from .github/copilot-instructions/templates.md
- Updated front-matter from applies_to: (YAML list) to applyTo: (single string) format
- Content remains identical except for front-matter changes
.github/instructions/uitests.instructions.md:
- 189 lines of detailed UI testing documentation
- Two-project requirement explanation with examples
- Platform coverage guidelines emphasizing cross-platform testing by default
- Category usage guidelines and best practices
docs/UITesting-Guide.md:
- 508+ lines of comprehensive UI testing documentation
- Prerequisites and setup instructions for all platforms
- Complete step-by-step guide for creating UI tests
- Common UI test operations reference with proper syntax highlighting
- Platform-specific test patterns with consistent indentation
- Running tests guide with properly formatted code blocks
docs/design/UITesting-Architecture.md:
- Architecture and CI/CD integration details
- Advanced topics for UI testing

File Structure

The documentation is now organized as:

.github/copilot-instructions.md - GitHub Copilot-specific quick reference with links to detailed docs
.github/instructions/ - Path-specific instructions that apply to certain directories
docs/UITesting-Guide.md - Comprehensive practical guide for UI testing
docs/design/UITesting-Architecture.md - Architecture and CI/CD integration details
AGENTS.md - Comprehensive reference for AI coding assistants

What's NOT Included

This PR does NOT include any code changes from PR #32064:

❌ No C# code changes to SafeAreaExtensions.cs (Android)
❌ No C# code changes to MauiView.cs (iOS)
❌ No C# code changes to SafeAreaEdges.cs
❌ No test code changes to Issue28986.cs
✅ Only markdown documentation files are modified

Verification

All changes have been verified:

✅ All markdown files have proper frontmatter with description and date fields
✅ copilot-instructions.md has proper references to comprehensive documentation
✅ All referenced files exist and are in correct locations
✅ Code review feedback applied (21 suggestions for syntax highlighting and indentation)
✅ Documentation structure is clean and well-organized

Related PRs

Based on documentation improvements from PR Fix SafeAreaEdges.SoftInput applying bottom padding when keyboard is hidden and inset consumption issue #32064
Merged enhancements from PR Added UITests Copilot instructions #32270
Consolidated with other instruction-based PRs

Original prompt

Create a PR that's just the markdown file changes from this PR #32064

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: PureWeen <[email protected]>

PureWeen · 2025-10-29T21:17:14Z

@copilot can you merge the changes and updates made on #32270 into this PR?

Co-authored-by: PureWeen <[email protected]>

Copilot · 2025-10-29T21:22:41Z

@copilot can you merge the changes and updates made on #32270 into this PR?

Merged changes from PR #32270 in commit 0702718. This adds:

.github/UI-Testing-Guide.md (508 lines) - comprehensive UI testing documentation
Enhanced UI Testing Guidelines section in .github/copilot-instructions.md with examples and common operations

Copilot

Pull Request Overview

This PR reorganizes and significantly enhances the UI testing documentation for the .NET MAUI repository. The changes split the monolithic UITesting.md document into three focused documents with clearer separation of concerns and adds a new AGENTS.md file for AI coding assistants.

Key changes:

Splits documentation into practical guide (UITesting-Guide.md), architecture/CI guide (UITesting-Architecture.md), and GitHub-specific instructions (uitests.instructions.md)
Creates AGENTS.md as a comprehensive reference for AI coding assistants
Updates copilot-instructions.md and templates.instructions.md with improvements and standardized frontmatter
Removes the old monolithic UITesting.md file

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
docs/design/UITesting.md	Removed old monolithic UI testing documentation (143 lines deleted)
docs/design/UITesting-Architecture.md	New architecture-focused document covering CI/CD, advanced patterns, and logging
docs/UITesting-Guide.md	New comprehensive practical guide for day-to-day UI test writing with API reference
AGENTS.md	New top-level guidance document for AI coding assistants with setup commands and troubleshooting
.github/instructions/uitests.instructions.md	New GitHub Copilot-specific instructions for UI testing with path-scoped application
.github/instructions/templates.instructions.md	Updated frontmatter format from `applies_to` to `applyTo`
.github/copilot-instructions.md	Enhanced with frontmatter, SDK verification emphasis, troubleshooting section, and streamlined UI testing guidance

Copilot · 2025-10-29T22:17:30Z

docs/UITesting-Guide.md

+```
+
+**File:** `src/Controls/tests/TestCases.HostApp/Issues/IssueXXXXX.xaml.cs`
+


Inconsistent indentation in the code example. The constructor at line 82 has no indentation, while the method at line 87 has 4 spaces. This should be consistently indented to match C# conventions.

Copilot · 2025-10-29T22:17:30Z

docs/UITesting-Guide.md

+### Step 2: Create the NUnit Test
+
+**File:** `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs`
+


Inconsistent indentation in the code example. Lines 108-110 show the constructor with 4-space indentation, but this is inconsistent with line 82's example which has no indentation. All code examples should follow consistent indentation patterns.

Copilot · 2025-10-29T22:17:30Z

docs/UITesting-Guide.md

+
+### Element Interaction
+
+```


Missing language identifier for the code block. The code block starting at line 137 should specify the language as csharp for proper syntax highlighting: ```csharp

Suggested change

```

```csharp

Copilot · 2025-10-29T22:17:31Z

docs/UITesting-Guide.md

+
+### Gestures
+
+```


Missing language identifier for the code block. The code block starting at line 161 should specify the language as csharp for proper syntax highlighting: ```csharp

Suggested change

```

```csharp

Copilot · 2025-10-29T22:17:31Z

docs/UITesting-Guide.md

+
+### Scrolling
+
+```


Missing language identifier for the code block. The code block starting at line 181 should specify the language as csharp for proper syntax highlighting: ```csharp

Suggested change

```

```csharp

Copilot · 2025-10-29T22:17:35Z

docs/UITesting-Guide.md

+
+### Always Wait for Elements
+
+```


Missing language identifier for the code block. The code block starting at line 391 should specify the language as csharp for proper syntax highlighting: ```csharp

Suggested change

```

```csharp

Copilot · 2025-10-29T22:17:35Z

docs/UITesting-Guide.md

+
+### Test Orientation Changes
+
+```


Missing language identifier for the code block. The code block starting at line 402 should specify the language as csharp for proper syntax highlighting: ```csharp

Suggested change

```

```csharp

Copilot · 2025-10-29T22:17:36Z

docs/UITesting-Guide.md

+
+
+## Example: Complete Test
+


Inconsistent indentation in the code example. The constructor at line 457 has no indentation, while it should be consistently indented to match the previous examples and C# conventions.

Copilot · 2025-10-29T22:17:36Z

docs/UITesting-Guide.md

+
+**File:** `src/Controls/tests/TestCases.HostApp/Issues/IssueXXXXX.xaml`
+
+```


Missing language identifier for the code block. The code block starting at line 52 should specify the language as xml or xaml for proper syntax highlighting.

Suggested change

```

```xml

Copilot · 2025-10-29T22:17:36Z

docs/UITesting-Guide.md

+
+### All Platforms
+
+```


Missing language identifier for the code block. The code block starting at line 16 should specify the language as bash for proper syntax highlighting: ```bash

Suggested change

```

```bash

PureWeen · 2025-10-29T23:29:17Z

@copilot work through all the comments made by copilot and assess whether you want to apply those changes or not

…e.md Co-authored-by: PureWeen <[email protected]>

PureWeen · 2025-10-29T23:36:46Z

@copilot when reviewing the logs I don't see any reference to copilot-instructions.md

Is that file in the right place and setup correctly so that you will use it when working on a PR?

Copilot · 2025-10-29T23:37:05Z

@copilot work through all the comments made by copilot and assess whether you want to apply those changes or not

Reviewed and applied all 21 suggestions from the automated code review in commit db49547:

Added language identifiers to all code blocks (bash, csharp, xaml, powershell)
Fixed inconsistent indentation in C# code examples (standardized to 4-space indentation for constructors and methods)

…nstructions.md Co-authored-by: PureWeen <[email protected]>

Copilot · 2025-10-29T23:43:48Z

@copilot when reviewing the logs I don't see any reference to copilot-instructions.md

Is that file in the right place and setup correctly so that you will use it when working on a PR?

Yes, .github/copilot-instructions.md is in the correct location with proper front-matter (has description field). The file consolidation moved UI-Testing-Guide.md to docs/ and simplified copilot-instructions.md. I've now added references in commit 0a6767c so it links to:

docs/UITesting-Guide.md - practical guide
docs/design/UITesting-Architecture.md - architecture details
.github/instructions/uitests.instructions.md - path-specific instructions

PureWeen · 2025-10-30T00:04:21Z

@copilot does including those links in the copilot instructions do anything for agents? Or is that mainly for humans ?

Copilot · 2025-10-30T00:06:58Z

@copilot does including those links in the copilot instructions do anything for agents? Or is that mainly for humans ?

The links serve both purposes:

For AI agents: Copilot can follow markdown links to fetch and read the referenced files. When working on UI test files in src/Controls/tests/TestCases.*, Copilot can use the path-specific instructions (.github/instructions/uitests.instructions.md) automatically. The links in copilot-instructions.md help agents discover and access the comprehensive guides when they need detailed context.

For humans: The links provide quick navigation to detailed documentation when reviewing or working with the instructions file.

The key benefit is discoverability - having the links ensures both humans and agents know where to find the comprehensive documentation beyond the quick reference tips.

jsuarezruiz · 2025-10-30T07:29:38Z

/azp run

azure-pipelines · 2025-10-30T07:29:59Z

Azure Pipelines successfully started running 3 pipeline(s).

jsuarezruiz · 2025-10-30T07:43:03Z

AGENTS.md

@@ -0,0 +1,250 @@
+# AGENTS.md


Follows good practices but could be more concise for AI agents to parse efficiently. Have some repeated information from copilot-instructions.md

Yea, it's an unfortunate world right now with copilot-instructions and Agents.md

We basically need both :-/
one for generalized agents
and one for the padawan agent to use

It's not great but hopefully it gets standardized at some point

jsuarezruiz · 2025-10-30T07:49:51Z

docs/design/UITesting-Architecture.md

@@ -0,0 +1,208 @@
+# UI Testing Architecture and CI Integration


Missing frontmatter metadata.

@copilot can you add frontmatter metadata to this markdown file please?

Added frontmatter metadata in commit f20f25d to both docs/design/UITesting-Architecture.md and docs/UITesting-Guide.md with description fields for consistency.

jsuarezruiz · 2025-10-30T07:50:04Z

docs/UITesting-Guide.md

@@ -0,0 +1,508 @@
+# UI Testing Guide for .NET MAUI Repository


Missing frontmatter metadata

@copilot can you add frontmatter metadata to this markdown file please?

Copilot · 2025-10-30T14:30:02Z

@PureWeen Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 3c6ebe50-3dc4-4736-95ea-975692a8cef6

Sorry for the inconvenience!

Co-authored-by: PureWeen <[email protected]>

PureWeen · 2025-10-30T23:58:21Z

@copilot for the front matter metadata on the mark down files can you add date as well ? so we have a record on the file when it was last updated

Co-authored-by: PureWeen <[email protected]>

Copilot · 2025-10-31T00:03:00Z

@copilot for the front matter metadata on the mark down files can you add date as well ? so we have a record on the file when it was last updated

Added date: 2025-10-30 field to frontmatter in commit d0ba471 for all markdown files:

.github/copilot-instructions.md
.github/instructions/templates.instructions.md
.github/instructions/uitests.instructions.md
docs/UITesting-Guide.md
docs/design/UITesting-Architecture.md

jsuarezruiz · 2025-10-31T07:06:36Z

/azp run

azure-pipelines · 2025-10-31T07:06:57Z

Azure Pipelines successfully started running 3 pipeline(s).

Initial plan

d4994f9

Copilot AI assigned Copilot and PureWeen Oct 29, 2025

Copilot started work on behalf of PureWeen October 29, 2025 20:31 View session

Extract markdown documentation changes from PR #32064

405bea4

Co-authored-by: PureWeen <[email protected]>

Copilot AI changed the title ~~[WIP] Update markdown files based on PR 32064 changes~~ Extract markdown documentation changes from PR #32064 Oct 29, 2025

Copilot AI requested a review from PureWeen October 29, 2025 20:41

Copilot finished work on behalf of PureWeen October 29, 2025 20:41

Copilot started work on behalf of PureWeen October 29, 2025 21:17 View session

Merge UI testing documentation enhancements from PR #32270

0702718

Co-authored-by: PureWeen <[email protected]>

Copilot AI changed the title ~~Extract markdown documentation changes from PR #32064~~ Extract markdown documentation changes from PR #32064 and merge enhancements from PR #32270 Oct 29, 2025

Copilot finished work on behalf of PureWeen October 29, 2025 21:23

- consolidate instruction based PRs

1c959a0

This was referenced Oct 29, 2025

Improved Copilot Instructions dotnet/maui-samples#701

Open

Modernize copilot-instructions.md with current repo state and enhanced agentic patterns #32281

Closed

Added UITests Copilot instructions #32270

Closed

PureWeen marked this pull request as ready for review October 29, 2025 22:12

PureWeen requested review from Copilot, jonathanpeppers, jsuarezruiz and mattleibow October 29, 2025 22:12

Copilot AI reviewed Oct 29, 2025

View reviewed changes

Copilot started work on behalf of PureWeen October 29, 2025 23:29 View session

Fix code block language identifiers and indentation in UITesting-Guid…

db49547

…e.md Co-authored-by: PureWeen <[email protected]>

Copilot finished work on behalf of PureWeen October 29, 2025 23:37

Copilot started work on behalf of PureWeen October 29, 2025 23:38 View session

Add references to comprehensive UI testing documentation in copilot-i…

0a6767c

…nstructions.md Co-authored-by: PureWeen <[email protected]>

Copilot finished work on behalf of PureWeen October 29, 2025 23:44

Copilot started work on behalf of PureWeen October 30, 2025 00:04 View session

Copilot finished work on behalf of PureWeen October 30, 2025 00:07

jsuarezruiz suggested changes Oct 30, 2025

View reviewed changes

Copilot started work on behalf of PureWeen October 30, 2025 14:31 View session

Add frontmatter metadata to UI testing documentation files

f20f25d

Co-authored-by: PureWeen <[email protected]>

Copilot finished work on behalf of PureWeen October 30, 2025 14:35

Copilot started work on behalf of PureWeen October 30, 2025 14:37 View session

Copilot finished work on behalf of PureWeen October 30, 2025 14:40

Copilot started work on behalf of PureWeen October 30, 2025 23:58 View session

Add date field to frontmatter metadata in all markdown files

d0ba471

Co-authored-by: PureWeen <[email protected]>

Copilot finished work on behalf of PureWeen October 31, 2025 00:04

PureWeen requested a review from jsuarezruiz October 31, 2025 20:00

jfversluis approved these changes Oct 31, 2025

View reviewed changes

StephaneDelcroix approved these changes Nov 1, 2025

View reviewed changes

PureWeen merged commit 5740076 into main Nov 1, 2025
155 of 166 checks passed

PureWeen deleted the copilot/update-markdown-files branch November 1, 2025 18:34

github-actions bot locked and limited conversation to collaborators Dec 2, 2025

		```

		File: `src/Controls/tests/TestCases.HostApp/Issues/IssueXXXXX.xaml.cs`

		### Step 2: Create the NUnit Test

		File: `src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/IssueXXXXX.cs`

		@@ -0,0 +1,208 @@
		# UI Testing Architecture and CI Integration

		@@ -0,0 +1,508 @@
		# UI Testing Guide for .NET MAUI Repository

Extract markdown documentation changes from PR #32064 and merge enhancements from PR #32270 #32280

Extract markdown documentation changes from PR #32064 and merge enhancements from PR #32270 #32280

Conversation

Copilot AI commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes Made

File Structure

What's NOT Included

Verification

Related PRs

Uh oh!

PureWeen commented Oct 29, 2025

Uh oh!

Copilot AI commented Oct 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

PureWeen commented Oct 29, 2025

Uh oh!

PureWeen commented Oct 29, 2025

Uh oh!

Copilot AI commented Oct 29, 2025

Uh oh!

Copilot AI commented Oct 29, 2025

Uh oh!

PureWeen commented Oct 30, 2025

Uh oh!

Copilot AI commented Oct 30, 2025

Uh oh!

jsuarezruiz commented Oct 30, 2025

Uh oh!

azure-pipelines bot commented Oct 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Oct 29, 2025 •

edited

Loading