Skip to content

Add comprehensive Appium Test API guide and reference documentation #30849

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 7 commits into
base: main
Choose a base branch
from
Draft

Add comprehensive Appium Test API guide and reference documentation #30849

wants to merge 7 commits into from
+1,484 −41

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Jul 25, 2025 •
edited
Loading

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

This PR adds a comprehensive documentation file AppiumTestGuide.md to the src/Controls/tests/TestCases.Shared.Tests/ directory that serves as both an instruction guide for developers and a reference for Copilot agents writing UI tests.

What's Included

The guide provides complete documentation of the .NET MAUI Appium testing framework including:

Core API Reference

  • IApp Interface: Complete documentation of all interaction methods including element discovery (WaitForElement, FindElement), user interactions (Tap, EnterText, DragAndDrop), navigation (Back, NavigateToGallery), and app state management
  • IUIElement Interface: Element-specific operations for getting properties, text, and attributes
  • Advanced Query Operations: XPath queries and complex element selection patterns

Test Base Classes

  • UITest: Main base class with visual regression testing capabilities
  • _IssuesUITest: Base class for testing specific GitHub issues with automatic navigation
  • CoreGalleryBasePageTest: Base class for control gallery testing
  • _ViewUITests: Base class for view control testing with common state and event patterns

Testing Patterns with Examples

  • Issue testing pattern with real code examples from existing tests
  • Control gallery testing pattern showing navigation and interaction
  • Property testing using ViewContainerRemote classes
  • Cross-platform testing strategies with conditional compilation

Step-by-Step Guide

Complete workflow for creating new tests including:

  • Choosing the appropriate base class
  • Setting up platform fixtures
  • Writing test methods with proper structure
  • Adding categories and handling platform differences

Visual Regression Testing

  • Screenshot verification with tolerance and cropping options
  • Batch screenshot verification for multiple captures
  • Platform-specific visual testing requirements and device configurations

Best Practices and Common Pitfalls

  • Reliable element waiting strategies to avoid race conditions
  • Platform-specific handling for Android, iOS, Mac, and Windows
  • Memory and performance testing patterns
  • Error handling and retry logic
  • Visual testing best practices with tolerance handling

Purpose

This documentation addresses the need for:

  1. Developer onboarding: Clear instructions for writing new UI tests
  2. AI agent reference: Comprehensive API documentation for Copilot agents
  3. Consistency: Standardized patterns and best practices across the codebase
  4. Maintenance: Reduced learning curve for maintaining existing tests

The guide is based on analysis of all existing Appium tests in the repository and captures real-world patterns and APIs currently in use, making it both practical and immediately applicable.

This pull request was created as a result of the following prompt from Copilot chat.

Review all Appium tests located in src/Controls/tests/TestCases.Shared.Tests/. Create a comprehensive document that lists all the APIs used within these tests. The document should serve as both an instruction guide for users and a reference for Copilot agents to understand how to write tests for this repository. The guide should include:

  • A categorized list of all API calls and usage patterns found in the tests
  • Example code snippets for typical test scenarios
  • Step-by-step instructions for writing new Appium tests tailored for dotnet/maui
  • Any setup or configuration steps required for running tests
  • Best practices and common pitfalls

Place the resulting documentation file in the same folder, named 'AppiumTestGuide.md'.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

@Copilot @PureWeen
Add comprehensive Appium test API guide and reference documentation
e2187a2 
Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
@Copilot Copilot AI changed the title [WIP] Document All APIs Used in Appium Tests and Create Instruction Guide Add comprehensive Appium Test API guide and reference documentation Jul 25, 2025
@Copilot Copilot AI requested a review from PureWeen July 25, 2025 19:10
Copilot finished work on behalf of PureWeen July 25, 2025 19:10
@PureWeen
Copy link
Member

Can you add a specific instruction file for writing UITests?
I'd like you to take all the copilot instructions related to writing UI tests and put them in a specific instructions folder based on the instructions here

https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#using-one-or-more-instructionsmd-files-1

image

@Copilot @PureWeen
Extract UI testing instructions to separate instructions file
0f940b2 
- Created .github/instructions/ui-testing.instructions.md following GitHub Copilot custom instructions format
- Extracted UI testing guidelines from main copilot-instructions.md
- Added applyTo: "src/Controls/tests/**/*.cs" to target relevant files
- Updated main instructions to reference the dedicated UI testing file
- Includes comprehensive UI testing patterns, examples, and API reference

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
@Copilot Copilot SWE Agent
Copy link
Contributor Author

Copilot AI commented Jul 25, 2025

Can you add a specific instruction file for writing UITests?
I'd like you to take all the copilot instructions related to writing UI tests and put them in a specific instructions folder based on the...

Created the UI testing instructions file following the GitHub Copilot custom instructions format. Extracted all UI testing guidelines from the main copilot-instructions.md and placed them in .github/instructions/ui-testing.instructions.md with applyTo: "src/Controls/tests/**/*.cs" to target relevant test files. The main instructions file now references the dedicated UI testing file. Commit: 0f940b2

Copilot finished work on behalf of PureWeen July 25, 2025 20:10
PureWeen
PureWeen requested changes Jul 25, 2025
View reviewed changes
@Copilot @PureWeen
Update UI testing instructions to apply only to specific test directo…
6083f36 
…ries

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
@Copilot Copilot AI requested a review from PureWeen July 25, 2025 20:25
Copilot finished work on behalf of PureWeen July 25, 2025 20:25
PureWeen
PureWeen requested changes Jul 25, 2025
View reviewed changes
@Copilot @PureWeen
Remove TestFixture examples, replace ClassicAssert with modern NUnit …
cd14122 
…assertions, remove platform fixtures section, and simplify test setup failure handling

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
@PureWeen
Copy link
Member

Let's see how accurate you are

Generate UItests for the following PR
#30290

@Copilot Copilot AI requested a review from PureWeen July 25, 2025 20:40
@Copilot @PureWeen
Generate UI tests for PR #30290 - prevent tabs from being removed dur…
8f3fd36 
…ing modal navigation

Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
@Copilot Copilot SWE Agent
Copy link
Contributor Author

Copilot AI commented Jul 25, 2025

Let's see how accurate you are

Generate UItests for the following PR
...

Generated comprehensive UI tests for PR #30290 that validate the TabbedPage modal navigation fix. The tests cover:

  • TabbedPage with modal navigation scenario - 3 tabs with modal trigger button
  • Platform-specific Android validation - ensures tabs remain accessible during modal presentation
  • Complete navigation flow testing - tab switching before, during, and after modal
  • Proper test structure - follows repository patterns with AutomationId attributes and _IssuesUITest inheritance

Both HostApp and test projects build successfully. The tests specifically verify that tabs are not removed during modal navigation on Android, which is the core behavior this PR addresses.

Commit: 8f3fd36

Copilot finished work on behalf of PureWeen July 25, 2025 20:59
@PureWeen
Copy link
Member

Let's see how accurate you are

Use your code instructions to generate UITests for
#30337

@Copilot @PureWeen
Generate UI tests for PR #30337 SafeArea per-edge control feature
cf66269 
Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
@Copilot Copilot SWE Agent
Copy link
Contributor Author

Copilot AI commented Jul 26, 2025

Let's see how accurate you are

Use your code instructions to generate UITests for
...

Generated comprehensive UI tests for PR #30337 that implement the SafeArea attached property for per-edge safe area control.

Created test components:

  1. HostApp test page (Issue30337.xaml/.cs) - Interactive page demonstrating SafeAreaEdges functionality with different controls and dynamic property changes
  2. NUnit tests (Issue30337.cs) - Appium tests validating all SafeAreaRegions types (None, All, Container, SoftInput) and interactive behavior

Test coverage includes:

  • Per-edge safe area control testing
  • Dynamic property changes at runtime
  • UI feedback validation for each SafeAreaRegions value
  • Property persistence verification
  • Cross-platform behavior expectations

Both projects compile successfully and follow established UI testing patterns. The tests validate the complete SafeArea feature functionality as described in PR #30337.

Commit: cf66269

Copilot finished work on behalf of PureWeen July 26, 2025 12:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@PureWeen PureWeen Awaiting requested review from PureWeen

Requested changes must be addressed to merge this pull request.

Assignees

@PureWeen PureWeen

Copilot code review Copilot

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@Copilot @PureWeen