使用说明

Selenium MCP Java测试框架

具有自愈功能的AI驱动测试自动化

一个结合了以下功能的测试自动化框架硒, MCP（模型上下文协议），以及 黄瓜BDD 提供自愈定位器管理和人工智能辅助测试生成。Java通过stdio上的JSON-RPC 2.0与Node.js MCP Selenium服务器通信，提供自动定位器回退和从每次测试执行中学习。

主要特点

自愈定位器：通过多种定位器策略自动回退，按成功率排序
智能学习：跟踪每个定位器策略的成功/失败，并随着时间的推移优化选择
API成本为零：使用本地MCP Selenium服务器(@executeautomation/mcp-selenium)-不需要云API密钥
黄瓜BDD：带有标记执行的完整Gherkin场景支持
综合指标：详细的每个元件修复报告，确定脆性和坚固的元件
页面对象模型：干净的POM结构 BasePage 继承和元素名称常量
人工智能辅助生成：与Claude Code、Cline和Amazon Q合作生成测试工件

建筑

Cucumber BDD (.feature files)
  -> Step Definitions (stepdefinitions/)
    -> Page Objects (pages/ extending BasePage)
      -> SelfHealingElement (healing/) -- retry/fallback chain
        -> LocatorRegistry (locators/) -- multi-strategy, JSON-persisted
          -> MCPSeleniumClient (mcp/) -- JSON-RPC 2.0 stdio bridge
            -> npx @executeautomation/mcp-selenium (Node.js process)
              -> Browser (Chrome, Firefox)

设计模式

模式	实施
页面对象模型	`BasePage` +具有元素常量的页面子类
责任链	定位器回退链 `SelfHealingElement`
战略	`LocatorStrategy` 按成功率动态选择的对象
注册表	`LocatorRegistry` --内存+JSON持久性
装饰师	`SelfHealingElement` 用修复功能包装所有浏览器操作

快速开始

先决条件

Java 21+
Maven 3.6+
Node.js 16+
npm

安装

克隆存储库:

git clone <repository-url>
cd selenium-mcp-framework

安装MCP Selenium:

npm install -g @executeautomation/mcp-selenium

构建项目:
```
mvn clean install
```
运行测试:
```
mvn test
```

项目结构

selenium-mcp-framework/
├── src/
│   ├── main/java/framework/
│   │   ├── mcp/
│   │   │   └── MCPSeleniumClient.java          # JSON-RPC 2.0 client for MCP server
│   │   ├── locators/
│   │   │   └── LocatorRegistry.java            # Element-to-strategies store, JSON persistence
│   │   ├── healing/
│   │   │   ├── SelfHealingElement.java         # Core healing algorithm with retry logic
│   │   │   └── HealingMetrics.java             # Per-element performance tracking and reports
│   │   └── pages/
│   │       ├── BasePage.java                   # POM base class (element(), navigateTo(), assertions)
│   │       ├── LoginPage.java                  # Login page (the-internet.herokuapp.com/login)
│   │       ├── CheckboxPage.java               # Checkboxes page (elements without IDs)
│   │       └── AddRemoveElementsPage.java      # Add/Remove Elements page (dynamic elements)
│   └── test/
│       ├── java/
│       │   ├── runners/
│       │   │   └── RunCucumberTest.java        # Cucumber JUnit runner
│       │   └── stepdefinitions/
│       │       ├── LoginSteps.java             # Login feature step definitions
│       │       ├── CheckboxSteps.java          # Checkbox feature step definitions
│       │       └── AddRemoveElementsSteps.java # Add/Remove feature step definitions
│       └── resources/
│           ├── features/
│           │   ├── login.feature               # Login scenarios (3 scenarios)
│           │   ├── checkbox.feature            # Checkbox scenarios (3 scenarios)
│           │   └── add_remove_elements.feature # Add/Remove scenarios (9 scenarios)
│           └── locators/
│               └── locators.json              # Locator configuration with success stats
├── pom.xml
├── CLAUDE.md
└── README.md

测试覆盖率

所有测试目标互联网.herokuapp.com.有 15种情景 跨越3个特征文件：

登录(`@login` --3种情况）

使用有效凭据成功登录
登录失败，密码无效
登录失败，用户不存在

复选框(`@checkbox` --3种情况）

验证复选框页面显示正确的标题
打开和关闭第一个复选框
关闭和打开第二个复选框

添加/删除元素(`@add_remove` --9个场景）

验证页面标题
添加单个和多个元素
删除元素并验证计数更改
最初没有删除按钮
添加、删除和添加更多元素
逐一删除所有元素
从剩余的中间班次中删除

运作原理

自愈元素发现

当您与元素交互时，框架：

检索所有已注册的定位器策略 对于该元素
按成功率对策略进行排序 （胜率越高；平局时，优先级越低的获胜）
尝试每种策略 最多重试3次，重试之间延迟500ms
记录成功/失败 持续学习策略的重要性
将统计数据保存到locators.json 在测试拆卸以备将来运行时

示例

// Traditional (brittle):
driver.findElement(By.id("login-btn")).click();

// Self-healing:
element("loginButton").click();

在幕后，该框架按照成功率顺序尝试策略：

css=button.login-button （成功率95%）
css=.radius （如果#1失败）
xpath=//button[@type='submit'] （如果#2失败）
css=.fa-sign-in （如果#3失败）

关键文件

文件	目的
`MCPSeleniumClient.java`	将Node.js MCP服务器作为子进程启动，通过stdin发送JSON-RPC请求，从stdout读取响应。30秒超时。
`LocatorRegistry.java`	存储元素到策略的映射，跟踪成功/失败计数，加载/保存到JSON。
`SelfHealingElement.java`	核心修复算法：按成功率尝试策略，每种策略重试3次，延迟500毫秒。
`HealingMetrics.java`	聚合每个元素的统计数据，识别易碎（<80%）和坚固（100%）的元素，生成报告。
`BasePage.java`	POM底座 `element()`, `navigateTo()`, `waitForElementVisible()`, `assertElementVisible()`基本网址：the-internet.herokuapp.com

添加新页面

创建页面类 延伸 BasePage 使用元素名称常量：

public class DashboardPage extends BasePage {

    public static final String WELCOME_MESSAGE = "welcomeMessage";
    public static final String LOGOUT_BUTTON = "logoutButton";

    public DashboardPage(MCPSeleniumClient mcp,
                         LocatorRegistry registry,
                         HealingMetrics metrics) {
        super(mcp, registry, metrics);
    }

    public void initializeLocators() {
        locatorRegistry.addElement(WELCOME_MESSAGE,
            new LocatorStrategy("id", "welcome", 1),
            new LocatorStrategy("css", ".welcome-msg", 2),
            new LocatorStrategy("xpath", "//h1[@class='welcome']", 3)
        );

        locatorRegistry.addElement(LOGOUT_BUTTON,
            new LocatorStrategy("id", "logout-btn", 1),
            new LocatorStrategy("css", "button.logout", 2),
            new LocatorStrategy("xpath", "//button[text()='Logout']", 3)
        );
    }

    public String getWelcomeMessage() throws IOException {
        return element(WELCOME_MESSAGE).getText();
    }

    public void clickLogout() throws IOException {
        element(LOGOUT_BUTTON).click();
    }
}

创建步骤定义 随着 @Before/@After 钩子标记在你的特征上。
注册定位器 在 @Before 钩子：创建MCPSeleniumClient，启动浏览器，加载注册表，初始化页面，调用 initializeLocators().
写一个小黄瓜专题 用钩子标签标记的文件。

运行测试

# Run all tests
mvn test

# Run a specific feature file
mvn test -Dcucumber.options="src/test/resources/features/login.feature"

# Run by tag
mvn test -Dcucumber.options="--tags @smoke"

# Build and generate reports
mvn verify

# Compile only (no tests)
mvn clean test-compile

指标和报告

该框架跟踪每个元素和每个定位器的统计数据。每次测试运行后，调用 printHealingReport() 查看：

=== SELF-HEALING METRICS REPORT ===

OVERALL STATISTICS:
   Total healing attempts: 45
   Successful heals: 42
   Failed heals: 3
   Overall success rate: 93.3%

ELEMENT-BY-ELEMENT BREAKDOWN:

  loginButton
   Success Rate: 100.0% (15/15 attempts)
   Most Reliable Locator: css=button.login-button
   Locator Performance:
      css=button.login-button (100.0% - 15/15)
      css=.radius (0.0% - 0/0)

  usernameInput
   Success Rate: 86.7% (13/15 attempts)
   Most Reliable Locator: id=username
   Locator Performance:
      id=username (92.3% - 12/13)
      css=input[name='username'] (50.0% - 1/2)

ROBUST ELEMENTS (100% success):
   loginButton
   passwordInput

BRITTLE ELEMENTS (<80% success):
   errorMessage - 66.7%

配置

定位器注册表（locators.json）

每个元素都有多个回退策略，具有优先级和跟踪的成功统计数据：

{
  "loginButton": [
    {
      "strategy": "css",
      "value": "button.login-button",
      "priority": 1,
      "successCount": 1,
      "failureCount": 0,
      "successRate": 100.0
    },
    {
      "strategy": "css",
      "value": ".radius",
      "priority": 2,
      "successCount": 0,
      "failureCount": 0,
      "successRate": 0.0
    }
  ]
}

注册表当前跟踪 13个元素 随着 41种定位策略 跨所有页面对象。

浏览器配置

// Chrome (default)
mcp.startBrowser("chrome", false);

// Chrome headless
mcp.startBrowser("chrome", true);

// Firefox
mcp.startBrowser("firefox", false);

故障排除

MCP服务器无法启动

确保MCP Selenium在全球范围内安装：

npm install -g @executeautomation/mcp-selenium

未找到元素

检查定位器注册表并添加更多策略：

locatorRegistry.printRegistry();

成功率低

查看度量报告并更新脆性元素的定位器：

healingMetrics.printHealingReport();
List<String> brittleElements = healingMetrics.getBrittleElements(80.0);

依赖项

依赖关系	版本	目的
Selenium WebDriver	4.15.0	浏览器自动化
Cucumber（Java+JUnit）	7.14.0	BDD框架
Jackson（数据绑定+核心）	2.15.3	定位器和JSON-RPC的JSON处理
JUnit4	4.13.2	测试运行器

其他资源

MCP硒 --此框架与MCP服务器通信
Cucumber文档 --BDD框架
Selenium文档 --浏览器自动化

贡献

分叉存储库
创建要素分支
进行更改
添加测试
提交拉取请求

许可证

该项目根据MIT许可证获得许可。