Skip to content

Commit 741411a

Browse files
imalcolm1imalcolm1
committed
Added copilot-generated design doc
1 parent 082caa4 commit 741411a

1 file changed

Lines changed: 226 additions & 0 deletions

File tree

‎src/Tests/UITests/DESIGN.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# UITests Design
2+
3+
## Summary
4+
5+
`src\Tests\UITests` is a cross-platform UI test foundation for the repository.
6+
7+
It includes:
8+
9+
- Appium-based UI test runners for six target platforms
10+
- Dedicated test apps for WPF, WinUI, and MAUI
11+
- Shared test logic and shared test page code
12+
- Per-platform setup for building apps and starting Appium sessions
13+
- Initial sample coverage for the Compass control
14+
15+
## Goals
16+
17+
- Run the same UI test scenarios across WPF, WinUI, and MAUI
18+
- Keep test logic shared where possible
19+
- Keep test pages aligned across app frameworks
20+
- Support platform-specific Appium setup without duplicating the tests
21+
- Make it easy to add more control tests over time
22+
23+
## UITests Structure
24+
25+
### 1. UITests workspace
26+
27+
`src\Tests\UITests` contains its own:
28+
29+
- `README.md`
30+
- `Directory.Build.props`
31+
- runner projects
32+
- app projects
33+
- shared test code
34+
- shared test page code
35+
36+
`Directory.Build.props` centralizes test settings such as:
37+
38+
- .NET target versions for runners and apps
39+
- Appium WebDriver and Magick.NET versions
40+
- Android test app behavior
41+
- iOS device and WebDriverAgent settings
42+
43+
### 2. Test runner projects
44+
45+
The UITests area includes six MSTest runner projects:
46+
47+
- `Toolkit.UITests.Wpf`
48+
- `Toolkit.UITests.WinUI`
49+
- `Toolkit.UITests.MauiWinUI`
50+
- `Toolkit.UITests.MauiAndroid`
51+
- `Toolkit.UITests.MauiiOS`
52+
- `Toolkit.UITests.MauiMac`
53+
54+
Each runner imports `Toolkit.UITests.Shared` and keeps only the setup code that is different for that platform.
55+
56+
Several runners also build their test app before test execution and write settings into `AppBuildInfo.txt`. The shared Appium setup reads that file to find the app path, package name, device ID, or other platform settings.
57+
58+
### 3. Shared test layer
59+
60+
`Toolkit.UITests.Shared` contains the common test foundation:
61+
62+
- `AppiumSetup.cs`
63+
- `AppiumTestBase.cs`
64+
- gesture helpers
65+
- image analysis helpers
66+
- crash handling helpers
67+
- the first shared test set
68+
69+
This shared layer handles the common pattern:
70+
71+
1. Read runner-provided build settings when needed
72+
2. Create the correct Appium driver
73+
3. Expose a common base class to the tests
74+
4. Share cross-platform test logic
75+
76+
The first shared scenario is `CompassTests`, which shows how one test can run across different frameworks and platforms.
77+
78+
### 4. Shared test page layer
79+
80+
`Toolkit.UITests.TestPages.Shared` contains shared code-behind and page base types for the test apps.
81+
82+
This keeps the page behavior in one place while still allowing each framework to keep its own XAML file.
83+
84+
The first shared page implementation is:
85+
86+
- `CompassMap.xaml.cs`
87+
- `TestPage.cs`
88+
89+
### 5. Test apps
90+
91+
The UITests area includes three test apps:
92+
93+
- `Toolkit.UITests.Wpf.App`
94+
- `Toolkit.UITests.WinUI.App`
95+
- `Toolkit.UITests.Maui.App`
96+
97+
These apps host mirrored test pages and expose automation IDs and metadata that the tests depend on, such as screen density and version labels.
98+
99+
The MAUI app is multi-targeted for:
100+
101+
- Android
102+
- iOS
103+
- Mac Catalyst
104+
- Windows
105+
106+
This lets one app project support four runner targets.
107+
108+
### 6. Automation-tree and accessibility fixes
109+
110+
The UITests area includes testability work so Appium can reliably find the right UI elements.
111+
112+
Examples:
113+
114+
- `Toolkit.UITests.Maui.App\AppBuilderExtensions.cs` adds a Windows automation-tree workaround for MAUI views
115+
- `Toolkit.UITests.Wpf.App\ControlPatcher.cs` patches WPF automation behavior so more text elements appear to Windows automation tools
116+
117+
These changes are important because the tests depend on the native automation and accessibility tree, not only on the visual tree.
118+
119+
## Runtime Architecture
120+
121+
At runtime, the test system works as a layered request chain.
122+
123+
```mermaid
124+
flowchart LR
125+
Runner["<b>UITest Runner</b><br/>MSTest + shared test code"]
126+
Appium["<b>Appium Server</b><br/>Translates request to native framework calls"]
127+
Native["<b>Native automation / accessibility driver</b><br/>(Windows UI Automation, UiAutomator2, XCUITest)"]
128+
App["<b>UITest App</b><br/>WPF / WinUI / MAUI"]
129+
130+
Runner -->|"UI command request"| Appium
131+
Appium -->|"Translated command"| Native
132+
Native -->|"Find, tap, type, screenshot, etc."| App
133+
134+
App -->|"UI state, screenshots, etc."| Native
135+
Native -->|"Automation result"| Appium
136+
Appium -->|"Translated driver response"| Runner
137+
```
138+
139+
## Project Architecture
140+
141+
The UITests projects are split into runners, apps, and shared layers.
142+
143+
```mermaid
144+
flowchart TD
145+
Props["<b>Directory.Build.props</b><br>General settings file"]
146+
147+
148+
SharedTests["<b>Toolkit.UITests.Shared</b><br/>Tests and shared Appium logic"]
149+
Runners["<b>Test Runner Projects</b><br/>Platform-specific appium setup code"]
150+
151+
Toolkits["<b>ArcGIS Maps SDK for .NET Toolkit</b>"]
152+
SharedPages["<b>Toolkit.UITests.TestPages.Shared</b><br/>Shared test page code-behinds"]
153+
Apps["<b>Test App Projects</b><br>Contain mirrored xaml test pages"]
154+
155+
Props --> Runners
156+
Props --> Apps
157+
158+
SharedTests --> Runners
159+
SharedPages --> Apps
160+
161+
Toolkits --> Apps
162+
Runners -->|"Manipulates via Appium"| Apps
163+
```
164+
165+
## Design Decisions
166+
167+
### Shared tests use shared projects
168+
169+
The runners import `Toolkit.UITests.Shared.projitems` instead of referencing a compiled shared test assembly.
170+
171+
This keeps compile-time constants available inside the shared code, which is useful for platform-specific driver types and platform guards.
172+
173+
### Shared page behavior is separate from framework XAML
174+
175+
The app projects keep their framework-specific XAML, while `Toolkit.UITests.TestPages.Shared` keeps the shared behavior.
176+
177+
This reduces duplication without forcing one UI framework model onto the others.
178+
179+
### Runners own platform setup
180+
181+
Each runner project keeps its own Appium setup partial and build target logic.
182+
183+
This is a good fit because app launch rules differ by platform:
184+
185+
- some apps are built automatically
186+
- some must already be installed
187+
- some need a package ID
188+
- iOS needs extra device and WebDriverAgent settings
189+
190+
### Tests use metadata from the app
191+
192+
The test apps expose values like screen density and version text.
193+
194+
This makes tests less fragile and helps normalize checks across devices with different DPI values.
195+
196+
## Current Coverage
197+
198+
The first end-to-end test flow is for Compass behavior:
199+
200+
- test pages exist in all three app frameworks
201+
- shared page logic drives the sample behavior
202+
- shared Appium tests validate auto-hide behavior
203+
- image analysis is used instead of full screenshot matching
204+
205+
This gives the branch a thin but complete vertical slice of the new architecture.
206+
207+
## Benefits
208+
209+
- One test design can be reused across many platforms
210+
- Most test logic lives in one place
211+
- Test pages stay aligned across app frameworks
212+
- Platform-specific launch details are isolated
213+
- The foundation is ready for more controls and more scenarios
214+
215+
## Known Constraints
216+
217+
- Windows runners must run on Windows
218+
- iOS and Mac Catalyst runners must run on Mac
219+
- Android setup differs depending on whether the app is preinstalled
220+
- Appium driver setup is still platform-specific and can require local machine configuration
221+
222+
## Expected Follow-on Work
223+
224+
- Add more shared test scenarios for other toolkit controls
225+
- Improve app install and launch automation where it is still manual
226+
- Expand troubleshooting and setup guidance as usage grows

0 commit comments

Comments
 (0)