Serenity BDD 框架：Java + Selenium 全面指南（2026 最新）

Serenity BDD（原名 Thucydides ）是一个强大的开源测试自动化框架，它在 Selenium WebDriver 基础上增强了实时文档生成、可维护性设计和企业级报告能力。以下是 2026 年你需要掌握的核心内容：

🔑 为什么选择 Serenity + Selenium？（核心优势）

特性	优势
自动生成实时文档	生成包含截图、需求追溯和步骤叙述的丰富 HTML 报告
增强版页面对象模式	内置 `PageObject`/`PageComponent`，支持智能等待、AJAX 处理和元素缓存
BDD 原生支持	无缝集成 Cucumber、JBehave 等行为驱动开发工具
并行执行能力	原生支持多浏览器/多线程并行测试
API + UI 混合测试	通过 `serenity-rest-assured` 轻松结合 REST API 与 UI 测试
CI/CD 友好	支持 Jenkins/GitHub Actions 插件，集成 Jira/Xray，支持需求标签
低维护成本	智能定位器（`@FindBy`）、自动截图管理、自愈能力

🚀 现代项目配置（Maven - 2026 推荐）

xml 复制代码

<!-- pom.xml -->
<!-- 公众号：测试工程师成长之路 -->
<properties>
    <serenity.version>4.0.0</serenity.version> <!-- 2026 年初最新稳定版 -->
    <serenity.cucumber.version>4.0.0</serenity.cucumber.version>
    <junit.jupiter.version>5.10.1</junit.jupiter.version>
</properties>

<dependencies>
    <!-- Serenity 核心 -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-core</artifactId>
        <version>${serenity.version}</version>
    </dependency>
    
    <!-- Cucumber BDD 支持 -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-cucumber</artifactId>
        <version>${serenity.cucumber.version}</version>
    </dependency>
    
    <!-- JUnit 5 支持 -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <version>${serenity.version}</version>
    </dependency>
    
    <!-- Selenium（由 Serenity 管理版本） -->
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.18.1</version> <!-- 兼容 Serenity 4.x -->
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>net.serenity-bdd.maven.plugins</groupId>
            <artifactId>serenity-maven-plugin</artifactId>
            <version>${serenity.version}</version>
            <executions>
                <execution>
                    <id>serenity-reports</id>
                    <phase>post-integration-test</phase>
                    <goals><goal>aggregate</goal></goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

📁 标准项目结构（2026 推荐）

复制代码

src/test/java
├── features/          # Cucumber .feature 文件（BDD 场景）
├── pages/             # 页面对象类（继承 PageObject）
├── steps/             # 步骤库（带 @Steps 注解的类）
├── tasks/             # Screenplay 模式任务（高级用法）
├── runners/           # 测试运行器（@CucumberOptions 或 @ExtendWith）
└── hooks/             # 全局钩子（Before/After）
src/test/resources
├── serenity.conf      # 核心配置（浏览器、超时、基础 URL）
└── environment/       # 环境专属配置（dev/staging/prod）

💡 关键代码模式（2026 最佳实践）

1. 页面对象（现代写法）

java 复制代码

@DefaultUrl("https://app.example.com/login")
public class LoginPage extends PageObject {
    
    @FindBy(id = "username") WebElementFacade usernameField;
    @FindBy(id = "password") WebElementFacade passwordField;
    @FindBy(css = "button[type='submit']") WebElementFacade loginBtn;
    
    public void enterCredentials(String user, String pwd) {
        usernameField.type(user);
        passwordField.typeAndEnter(pwd); // 自动提交
    }
    
    // 智能等待示例
    public boolean isErrorMessageVisible() {
        return $("#error-alert").isCurrentlyVisible();
    }
}

2. Screenplay 模式（复杂流程推荐）

java 复制代码

public class Login implements Task {
    private final String username, password;
    
    public static Login as(String user, String pwd) {
        return Tasks.instrumented(Login.class, user, pwd);
    }
    
    @Override
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Enter.theValue(username).into("#username"),
            Enter.theValue(password).into("#password").thenHit(Keys.ENTER),
            WaitUntil.the(LoginPage.SUCCESS_MESSAGE, isVisible()).forNoMoreThan(10).seconds()
        );
    }
}

3. serenity.conf（核心配置）

hocon 复制代码

webdriver {
  driver = chrome
  chrome {
    arguments = ["--headless=new", "--disable-gpu", "--no-sandbox"]
  }
}
serenity {
  take.screenshots = FOR_FAILURES
  requirements.dir = "src/test/resources/features"
  output.directory = "target/site/serenity"
}
environments {
  default {
    base.url = "https://staging.example.com"
  }
  prod {
    base.url = "https://app.example.com"
  }
}

📊 报告能力亮点

执行 mvn clean verify + mvn serenity:aggregate 后，自动生成：

交互式仪表盘：测试结果、需求覆盖率、能力地图
步骤级叙述：每个操作附带时间戳、截图、HTML 源码
需求追溯 ：通过 @capability、@feature、@story 标签关联业务需求
不稳定测试检测：历史趋势分析，识别波动用例
视频录制：配合 Docker/Selenium Grid 可录制完整测试会话

💡 报告示例：target/site/serenity/index.html ------ 完全交互式，支持逐层钻取

🌐 2026 生态系统集成

工具	集成方式
GitHub Actions	`serenity-bdd/report-publisher-action@v2`
Jira/Xray	通过 `serenity-jira-requirements-provider` 自动上传结果
Allure	支持混合报告（Serenity + Allure 双报告）
Docker	官方 `serenitybdd/serenity-cli` 镜像用于 CI 环境
Playwright	社区插件提供实验性支持（GitHub 查看最新进展）

⚠️ 常见陷阱与避坑指南

避免混用 JUnit 4/5 ：JUnit 5 项目使用 @ExtendWith(SerenityRunner.class)
始终使用 WebElementFacade ：替代原生 WebElement，获得内置智能等待
禁止硬编码等待 ：使用 WaitUntil 条件等待替代 Thread.sleep()
CI 环境优化截图 ：配置 serenity.take.screenshots=FOR_FAILURES 减少产物体积
升级注意：Serenity 3.x → 4.x 需要 Selenium 4.15+ 和 Java 17+

📚 必备资源（2026 更新）

官方文档（每周更新）
GitHub 仓库（活跃社区）
Serenity Dojo（付费培训，含最新实践）
Maven Central（查询最新版本）
2025 新增 ：官方 VS Code 插件，支持 .feature 文件智能提示

💡 专家建议 ：2026 年新项目建议直接采用 Screenplay 模式 而非传统页面对象------它更适合复杂业务流程，能实现真正的业务语言测试。推荐从 Serenity Starter 项目快速启动。

✅ 总结

Serenity BDD 依然是企业级 Selenium 自动化的黄金标准，特别适合对可维护性、报告质量和 BDD 协作有高要求的团队。2025 年底发布的 4.0+ 版本持续活跃开发，全面兼容 Selenium 4 新特性及主流云测试平台，是 2026 年自动化测试架构的可靠选择。🚀