If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/WinAppDriver shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 22+ active contributors
• Distributed ownership (top contributor 47% of recent commits)
• MIT licensed
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/WinAppDriver repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/WinAppDriver.

What it runs against: a local clone of microsoft/WinAppDriver — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/WinAppDriver | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 421 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/WinAppDriver. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/WinAppDriver.git
#   cd WinAppDriver
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/WinAppDriver and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/WinAppDriver(\\.git)?\\b" \\
  && ok "origin remote is microsoft/WinAppDriver" \\
  || miss "origin remote is not microsoft/WinAppDriver (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "ApplicationUnderTests/AppUIBasics/App.xaml.cs" \\
  && ok "ApplicationUnderTests/AppUIBasics/App.xaml.cs" \\
  || miss "missing critical file: ApplicationUnderTests/AppUIBasics/App.xaml.cs"
test -f "ApplicationUnderTests/AppUIBasics/AppUIBasics.csproj" \\
  && ok "ApplicationUnderTests/AppUIBasics/AppUIBasics.csproj" \\
  || miss "missing critical file: ApplicationUnderTests/AppUIBasics/AppUIBasics.csproj"
test -f "ApplicationUnderTests/AppUIBasics/Common/NavigationHelper.cs" \\
  && ok "ApplicationUnderTests/AppUIBasics/Common/NavigationHelper.cs" \\
  || miss "missing critical file: ApplicationUnderTests/AppUIBasics/Common/NavigationHelper.cs"
test -f "ApplicationUnderTests/AppUIBasics/ControlExample.xaml" \\
  && ok "ApplicationUnderTests/AppUIBasics/ControlExample.xaml" \\
  || miss "missing critical file: ApplicationUnderTests/AppUIBasics/ControlExample.xaml"
test -f "ApplicationUnderTests/AppUIBasics/ControlExample.xaml.cs" \\
  && ok "ApplicationUnderTests/AppUIBasics/ControlExample.xaml.cs" \\
  || miss "missing critical file: ApplicationUnderTests/AppUIBasics/ControlExample.xaml.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 421 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~391d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/WinAppDriver"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Windows Application Driver (WinAppDriver) is a Selenium-compatible automation service that enables UI testing of Windows desktop applications—UWP, WinForms, WPF, and Win32 apps—by exposing a WebDriver protocol API on port 4723. It bridges the gap between Appium/Selenium test frameworks and native Windows app automation, letting testers write cross-platform scripts that interact with window elements, buttons, text fields, and dialogs the same way browser automation works. Monorepo structure: WinAppDriver.exe service binary at the root listens on 127.0.0.1:4723 and implements WebDriver protocol. ApplicationUnderTests/AppUIBasics is a sample UWP test harness with XAML pages and asset images. Tests/ directory contains full API test suite. Samples/ folder has runnable examples against Windows built-ins (Calculator, Alarms, Notepad). Docs/ holds protocol specs, authoring guides, and troubleshooting. Dependencies managed via Maven POM with Selenium, Appium, and JUnit.

QA engineers and test automation developers who maintain Windows desktop applications (not web apps) and want to write maintainable, cross-platform UI tests using Selenium/Appium conventions. Also used by enterprise teams testing LOB apps built in WinForms, WPF, or UWP on Windows 10.

Production-ready and actively maintained by Microsoft. The repo demonstrates maturity via comprehensive test coverage (Tests/ directory with full API endpoint coverage), CI integration docs (CI_AzureDevOps.md), sample applications (ApplicationUnderTests/AppUIBasics), and detailed documentation (Docs/ folder). Codebase is 826KB C# + 37KB C++ with structured Maven test dependencies (selenium-java 3.3.1, Appium java-client 5.0.0), indicating stable, established tooling.

Low risk for core functionality, but Windows-OS-specific: this only runs on Windows 10+ with Developer Mode enabled, creating a platform lock-in. Dependency versions (Selenium 3.3.1, JUnit 4.11, Appium 5.0.0) are somewhat dated relative to current releases, which may signal slower update cadence or compatibility concerns for projects on newer Selenium 4.x. Admin-mode execution requirement (WinAppDriver.exe must run as administrator) and single service port model could create bottlenecks in distributed test scenarios.

Based on file structure, active development includes: sample test apps (AppUIBasics with multiple XAML control samples—Button, CheckBox, ComboBox, ListView, etc.), comprehensive test coverage across UI Recorder integration, remote machine execution, CI/Azure DevOps pipelines, and Selenium Grid support. Documentation is extensive and recent, suggesting ongoing community support and feature refinement rather than new major features.

1. Clone: git clone https://github.com/microsoft/WinAppDriver.git. 2. Install: Download WinAppDriver.exe from releases and run installer on Windows 10. 3. Enable Developer Mode: Settings > Update & Security > For developers > Toggle Developer Mode. 4. Run service: WinAppDriver.exe (as Administrator; default listens on 127.0.0.1:4723). 5. Run tests: Navigate to Samples/ or Tests/ and execute Maven tests with mvn test (requires JDK, Maven, and Selenium/Appium deps from pom.xml).

Daily commands: Start WinAppDriver service: WinAppDriver.exe (default 127.0.0.1:4723) or WinAppDriver.exe 10.0.0.10 4725 (custom IP/port). Run sample tests: cd Samples/ and execute Maven: mvn test (runs against Calculator, Notepad, Alarms & Clock via Selenium client). Run internal test suite: cd Tests/ and mvn test (validates all WebDriver endpoints and WinAppDriver protocol compliance).

• ApplicationUnderTests/AppUIBasics/App.xaml.cs — Entry point for the test application; demonstrates XAML app initialization and must be understood to grasp how WinAppDriver interacts with Windows apps
• ApplicationUnderTests/AppUIBasics/AppUIBasics.csproj — Project configuration showing UWP/WinForms/WPF test app setup; essential for understanding build and deployment targets
• ApplicationUnderTests/AppUIBasics/Common/NavigationHelper.cs — Core navigation abstraction used across all control pages; critical for understanding how the test app manages UI state and page transitions
• ApplicationUnderTests/AppUIBasics/ControlExample.xaml — Master template for all control test pages; defines the layout and binding patterns that every control page inherits
• ApplicationUnderTests/AppUIBasics/ControlExample.xaml.cs — Codebehind for ControlExample that manages control lifecycle and state; every test page uses this pattern
• .gitmodules — Tracks submodule dependencies; necessary to understand external test harnesses and sample repos integrated into the project
• ApplicationUnderTests/AppUIBasics/AppUIBasics.sln — Solution file defining all projects and their dependencies; entry point for building the entire test suite

Add a new control test page

1. Create a new XAML file in ApplicationUnderTests/AppUIBasics/ControlPages/ following the naming convention (e.g., NewControlPage.xaml) (ApplicationUnderTests/AppUIBasics/ControlPages/ButtonPage.xaml)
2. Add the root element as local:ControlExample to inherit the master control example template and styling (ApplicationUnderTests/AppUIBasics/ControlExample.xaml)
3. Create the corresponding C# codebehind (e.g., NewControlPage.xaml.cs) that inherits from Page and calls NavigationHelper.LoadState (ApplicationUnderTests/AppUIBasics/ControlPages/ButtonPage.xaml.cs)
4. Register the page in the navigation system by adding a route in App.xaml.cs or the NavigationHelper (ApplicationUnderTests/AppUIBasics/Common/NavigationHelper.cs)

Add a new value converter for data binding

1. Create a new C# class in ApplicationUnderTests/AppUIBasics/Common/ that implements IValueConverter (ApplicationUnderTests/AppUIBasics/Common/BooleanToVisibilityConverter.cs)
2. Implement Convert() and ConvertBack() methods with your transformation logic (ApplicationUnderTests/AppUIBasics/Common/BooleanToVisibilityConverter.cs)
3. Register the converter in App.xaml under Resources with an x:Key attribute for XAML reference (ApplicationUnderTests/AppUIBasics/App.xaml)
4. Use the converter in XAML bindings with {Binding Path=Property, Converter={StaticResource ConverterName}} (ApplicationUnderTests/AppUIBasics/ControlExample.xaml)

Extend the common utilities library

1. Create a new utility class in ApplicationUnderTests/AppUIBasics/Common/ (e.g., NewUtility.cs) (ApplicationUnderTests/AppUIBasics/Common/RelayCommand.cs)
2. Implement the utility following MVVM patterns (INotifyPropertyChanged for observable classes, ICommand for commands) (ApplicationUnderTests/AppUIBasics/Common/ObservableDictionary.cs)
3. If persistence is needed, integrate with SuspensionManager.SessionState for app lifecycle management (ApplicationUnderTests/AppUIBasics/Common/SuspensionManager.cs)
4. Add unit tests in the Tests/ directory to validate the utility behavior across app suspend/resume cycles (ApplicationUnderTests/AppUIBasics/AppUIBasics.csproj)

• XAML (Extensible Application Markup Language) — Declarative UI markup standard for UWP, WPF, and WinForms; enables separation of UI design from logic and supports data binding
• C# with .NET Framework — Primary language for Windows desktop application development; integrates deeply with Windows UI Automation APIs and provides strong type safety
• Windows UI Automation API — Microsoft's native framework for programmatic UI control discovery and interaction; essential for WinAppDriver to locate and manipulate controls
• Selenium WebDriver Protocol — Industry-standard API for test automation; WinAppDriver implements Selenium semantics to unify testing across web and desktop applications

• Single test application (AppUIBasics) covering multiple control types

  • Why: Consolidates all UI control demonstrations in one place for easier maintenance and navigation
  • Consequence: ControlExample.xaml becomes a load-bearing abstraction; changes to the template affect all ~70+ control pages

• MVVM pattern with observable collections and relay commands rather than direct event handlers

  • Why: Enables data-driven UI testing and cleaner separation of concerns; supports time-travel debugging in test scenarios
  • Consequence: Adds complexity for simple controls; requires understanding of binding syntax and property notification overhead

• Windows-only platform targeting (no Linux/macOS support)

  • Why: Leverages native Windows UI Automation APIs which have no cross-platform equivalent; critical for accessing Win32, WinForms, WPF internals
  • Consequence: Cannot test Windows apps on non-Windows CI/CD systems; limits cross-platform test infrastructure

• Support for testing applications on Linux or macOS platforms
• Real-time performance profiling or memory leak detection during test execution
• Automated code generation from recorded UI interactions
• Built-in test report generation or integration with CI/CD pipelines (delegated to test runners)

1. Admin privilege required: WinAppDriver.exe must run as Administrator to listen on non-default IP/port; tests fail silently if service isn't elevated. 2. Developer Mode mandatory: Windows 10 Developer Mode must be explicitly enabled via Settings, else UI Automation framework lacks permissions. 3. Single service instance: Only one WinAppDriver.exe per machine by default (port 4723); parallel test runs require custom port allocation or service restart between sessions. 4. Appium version lock: pom.xml pins java-client to 5.0.0 (released ~2017); newer Appium server versions may have protocol drift. 5. App-under-test lifetime: Some tests assume the target app (Calculator, Notepad) is already running or auto-launches; failure modes unclear if app crashes mid-test. 6. Locator fragility: WinAppDriver relies on UIA element names/AutomationId; app UI changes (re-theming, control refactoring) break existing locators; no built-in recording fallback for dynamic locators.

• UI Automation Framework (UIA) — WinAppDriver's core mechanism: it queries the Windows UI Automation tree to find elements, inspect properties (text, enabled state), and invoke actions; understanding UIA element hierarchy and locator strategies (by Name, AutomationId, ClassName, XPath) is essential for writing reliable tests
• WebDriver Protocol (JSON Wire Protocol / W3C) — WinAppDriver implements the WebDriver specification (HTTP REST API) so tests written in Selenium/Appium style work unchanged; knowing the difference between JSONWireProtocol (older, used here) and W3C WebDriver spec helps troubleshoot compatibility
• Desired Capabilities (Appium) — Tests define app-under-test parameters via a JSON capabilities object (platform name, app path, launch args); WinAppDriver requires specific caps like app: 'C:\\path\\to\\app.exe' and platformName: 'Windows' which differ from browser/mobile caps
• XPath for UI Element Locators — WinAppDriver supports XPath queries (e.g., //Window[Name='Calculator']/Button[@AutomationId='num1']) to find elements in the UIA tree; XPath proficiency is critical because GUI changes break CSS selectors, making tree-based queries more resilient
• XAML (Extensible Application Markup Language) — Sample app (AppUIBasics) is built with XAML/C# (UWP); understanding XAML structure, data binding, and how controls expose AutomationId helps test authors write better locators for modern Windows apps

• appium/appium — Appium is the upstream cross-platform automation framework; WinAppDriver plugs into Appium via the java-client dependency and shares WebDriver protocol conventions, making it a Windows-specific adapter in the Appium ecosystem
• SeleniumHQ/selenium — Selenium WebDriver is the foundational API contract WinAppDriver implements (port 4723 serves the JSON Wire Protocol); tests in this repo use selenium-java 3.3.1 as the client library
• microsoft/appium-windows-driver — Successor/complement to WinAppDriver; modern Appium plugin for Windows automation with WebDriver2 protocol support; users evaluating WinAppDriver may also want this higher-level integration
• microsoft/WinUI — WinUI is Microsoft's native UI framework for Windows; WinAppDriver tests rely on UI Automation exposure which WinUI controls must implement, making this repo useful for WinUI app test authors
• pywinauto/pywinauto — Alternative Python-based Windows UI automation library; solves the same problem (test Windows desktop apps) but via win32api introspection rather than Selenium WebDriver protocol, relevant for teams choosing between Selenium and pyautogui/pywinauto stacks

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test suite for AppUIBasics sample application

The ApplicationUnderTests/AppUIBasics folder contains a full UWP sample app with 50+ UI control types (Button, CheckBox, ComboBox, GridView, etc.) but there are no corresponding automated test files. This is a critical gap since WinAppDriver's purpose is UI test automation. Creating a test suite that validates interaction with these controls would serve as both documentation and validation of WinAppDriver's capabilities. This would be high-value for new contributors learning the framework and for users validating their setup.

• [ ] Create Tests/ or UITests/ directory in ApplicationUnderTests/AppUIBasics/
• [ ] Add test class for each major control category (Button controls, Text controls, Selection controls, etc.)
• [ ] Write test cases covering basic interactions: click, text input, selection verification for at least 15 control types
• [ ] Reference specific .xaml pages in AppUIBasics and use WinAppDriver session to locate and interact with controls by AutomationId
• [ ] Ensure tests use the existing pom.xml dependencies (Selenium, Appium Java client, JUnit)

Add GitHub Actions CI workflow for Windows Application Driver build and test validation

The repo has no visible CI/CD pipeline configuration (.github/workflows/ appears absent from the file list). For a Windows-specific application testing tool, having CI that builds WinAppDriver on Windows 10+ and validates basic functionality would catch regressions early and signal project health to contributors. This should build the core WinAppDriver service, validate it starts correctly, and optionally run basic AppUIBasics tests.

• [ ] Create .github/workflows/windows-build.yml with windows-latest runner
• [ ] Add steps to build WinAppDriver core components and the AppUIBasics sample application
• [ ] Include step to start WinAppDriver.exe and verify it's listening on 127.0.0.1:4723
• [ ] Add optional step to run a basic smoke test (e.g., launch AppUIBasics and verify window is accessible via WinAppDriver REST API)
• [ ] Document any required setup (Developer Mode enablement, dependencies) in comments

Document WinAppDriver REST API endpoints and add request/response examples for common operations

The README cuts off mid-sentence about the default IP/port but provides no API documentation. New contributors and users need clear documentation of WinAppDriver's REST endpoints (e.g., POST /session to create session, POST /session/{sessionId}/element to find elements, etc.). Creating a structured API reference with concrete JSON examples for session creation, element location strategies (by name, className, AutomationId), and element interactions would dramatically reduce onboarding friction.

• [ ] Create docs/API.md or docs/rest-api.md documenting all HTTP endpoints (session, element, click, send_keys, etc.)
• [ ] Include endpoint purpose, HTTP method, URL pattern, request body schema, and response examples
• [ ] Add section on element location strategies specific to Windows apps (by AutomationId, ClassName, Name, XPath equivalents)
• [ ] Provide 3-5 complete curl/JSON examples (e.g., 'Create session and launch Calculator', 'Find button by AutomationId and click it')
• [ ] Reference this in the main README with a link to the full API documentation

• Add comprehensive documentation for error codes and troubleshooting: Currently Docs/ lacks a mapping of HTTP status codes and WinAppDriver-specific errors (e.g., what happens when UIA element is stale, when app crashes, when locator is ambiguous). Create Docs/ErrorCodesAndTroubleshooting.md with real examples from Tests/.
• Extend Samples/ with a WinForms and WPF test example: Repo shows UWP (AppUIBasics) but lacks runnable samples for WinForms or WPF apps. Add Samples/WinFormsCalculator and Samples/WPFNotepad with pom.xml test harnesses to demonstrate Appium capability format and element finding for each framework.
• Create a CI/CD pipeline template for GitHub Actions: Docs/CI_AzureDevOps.md only covers Azure Pipelines. Add Docs/CI_GitHubActions.md with a .github/workflows/test.yml example showing WinAppDriver installation, enabling Developer Mode, running Tests/, and artifact collection—useful for contributors and downstream users.

The codebase has significant security concerns primarily due to severely outdated and vulnerable dependencies (Selenium 3.3.1 from 2017 and Appium Client 5.0.0). These dependencies contain multiple known CVEs and lack security patches. The WinAppDriver service itself exposes an automation API that requires careful input validation to prevent injection attacks. The project lacks automated dependency vulnerability scanning in its build pipeline. Immediate remediation should focus on upgrading all dependencies to current versions and implementing security testing infrastructure.

• High · Outdated Selenium Dependency with Known Vulnerabilities — pom.xml - selenium-java:3.3.1. The pom.xml file specifies Selenium 3.3.1 (released in 2017), which contains multiple known security vulnerabilities including CVE-2019-12402. This version is severely outdated and lacks security patches for command injection, XSS, and other web driver protocol vulnerabilities. Fix: Upgrade to Selenium 4.x or the latest stable version. Run 'mvn dependency:tree' to identify all transitive dependencies and their vulnerabilities. Consider using OWASP Dependency-Check or Snyk for continuous vulnerability scanning.
• High · Outdated Appium Java Client with Known Vulnerabilities — pom.xml - io.appium:java-client:5.0.0. Appium Java Client version 5.0.0 (released in 2017) is outdated and contains known security vulnerabilities. This version predates many critical security fixes in the Appium ecosystem. Fix: Upgrade to Appium Java Client 8.x or latest stable version. Review release notes for security fixes and breaking changes.
• Medium · Outdated JUnit Dependency — pom.xml - junit:junit:4.11. JUnit version 4.11 is from 2013 and is outdated. While primarily a testing framework, outdated dependencies can introduce unexpected behavior and security issues. Fix: Upgrade to JUnit 4.13.2 or migrate to JUnit 5.x for better security and feature support.
• Medium · Hardcoded Default IP Address in Documentation — README.md - default IP address documentation. The README specifies that WinAppDriver listens on 127.0.0.1 (localhost) by default. While localhost binding is secure, the documentation should emphasize that binding to 0.0.0.0 or public IPs would expose the automation service to network attacks. No evidence of this configuration being enforced in code. Fix: Ensure WinAppDriver binding is restricted to 127.0.0.1 by default. Add security documentation warning against exposing the service on public networks. Implement IP whitelist validation if binding to non-localhost addresses.
• Medium · Missing Input Validation for UI Automation Commands — WinAppDriver service (core driver code not visible in provided file structure). WinAppDriver is a UI automation service that processes external commands. Without reviewing the actual driver code, common risks include: injection attacks via XPath/CSS selectors, command injection through application path parameters, and path traversal vulnerabilities when handling file operations. Fix: Implement strict input validation and sanitization for all user inputs, especially XPath expressions, CSS selectors, and file paths. Use parameterized/safe APIs where available. Implement rate limiting and request validation.
• Low · No Evidence of Dependency Security Scanning in Build Pipeline — pom.xml - missing security plugins. The pom.xml file lacks Maven security plugins (maven-dependency-check-plugin, OWASP DependencyCheck) to automatically scan for vulnerable dependencies during build. Fix: Add OWASP Dependency-Check Maven plugin to the build process. Configure it to fail builds on detection of high-severity vulnerabilities: <plugin><groupId>org.owasp</groupId><artifactId>dependency-check-maven</artifactId></plugin>

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.