不降级Selenium4.7.2，如何修复WinAppDriver会话启动错误？

问题背景 #

使用WinAppDriver进行桌面自动化时，遇到错误：

Bad capabilities. Specify either app or appTopLevelWindow to create a session

该错误源于Selenium 4.x采用的W3C协议与WinAppDriver的旧协议不兼容，无需降级Selenium至3.x版本，可通过Appium作为中间件实现协议转换，解决兼容问题。

解决方案步骤 #

1. 环境准备 #

• 安装最新稳定版Appium
• 安装Appium Windows驱动：执行命令 appium driver install windows
• 确保WinAppDriver已安装（Appium会自动调用WinAppDriver服务）

2. 修改自动化代码 #

核心变化：

• 不再手动启动WinAppDriver，由Appium自动管理
• 使用Selenium 4推荐的MutableCapabilities替代过时的DesiredCapabilities
• 新增automationName配置，指定使用Windows自动化引擎
• 连接地址改为Appium服务端点http://127.0.0.1:4723/wd/hub

修改后的完整代码：

import io.appium.java_client.windows.WindowsDriver;
import org.openqa.selenium.MutableCapabilities;
import java.net.URL;
import java.time.Duration;

public void setupDesktopAutomation(String appName, String platformName, String deviceName) {
    try {
        // 初始化Selenium 4标准的能力配置对象
        MutableCapabilities caps = new MutableCapabilities();
        caps.setCapability("app", appName);
        caps.setCapability("platformName", platformName);
        caps.setCapability("deviceName", deviceName);
        // 指定自动化引擎为Windows，Appium将桥接WinAppDriver
        caps.setCapability("automationName", "Windows");

        // 连接到Appium服务，注意端点为/wd/hub
        windowsDriver = new WindowsDriver(new URL("http://127.0.0.1:4723/wd/hub"), caps);
        // 设置隐式等待（替代原代码中的wait方法，Selenium 4已更新API）
        windowsDriver.manage().timeouts().implicitlyWait(Duration.ofSeconds(5));
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

3. 运行前检查 #

• 启动Appium服务：在命令行执行 appium，确认服务正常启动（默认监听4723端口）
• 若自定义了Appium端口，需同步修改代码中的URL端口
• 通过 appium driver list 命令确认Windows驱动已正确安装

原理说明 #

Appium作为协议中间件，会自动处理Selenium 4.x的W3C协议请求，转换为WinAppDriver兼容的旧协议格式，同时负责WinAppDriver服务的启动与管理，从而实现Selenium 4.x与WinAppDriver的兼容，无需降级Selenium版本。

内容的提问来源于stack exchange，提问作者Suresh Madhusanka Rodrigo