AssertJ社区贡献指南：如何参与开源测试库开发

AssertJ社区贡献指南：如何参与开源测试库开发

【免费下载链接】assertjFluent testing assertions for Java and the JVM项目地址: https://gitcode.com/gh_mirrors/as/assertj

AssertJ是一款强大的Java测试断言库，它提供了流畅的API，帮助开发者编写更易读、更易维护的测试代码。作为开源项目，AssertJ的成长离不开社区的积极贡献。本文将为你提供一份详尽的社区贡献指南，助你轻松参与到这个优秀测试库的开发中。

贡献前的准备工作

在开始贡献之前，确保你的开发环境满足以下要求：

• 使用JDK 25或更高版本构建项目
• 配置代码格式化工具，使用项目提供的Eclipse格式化配置（IntelliJ用户可通过Eclipse代码格式化适配器插件导入）

代码贡献规范

代码风格与文档要求

• 为每个断言方法编写完整的Javadoc，包含代码示例（成功和失败的断言）
• 使用JUnit 5，测试类和方法采用包私有可见性
• 测试类命名遵循<AssertClass>_<assertion>_Test格式
• 测试方法命名采用下划线风格，成功的断言测试以should_pass_xxx开头，失败的断言测试以should_fail_xxx开头
• 在每个测试中使用GIVENWHENTHEN步骤，THEN步骤优先使用BDDAssertions.then
• 使用AssertionUtil.expectAssertionError测试预期的AssertionError

测试编写示例

一个良好的单元测试示例：

import static org.assertj.core.api.BDDAssertions.then; import static org.assertj.core.util.AssertionsUtil.expectAssertionError; class OptionalAssert_containsInstanceOf_Test extends BaseTest { @Test void should_fail_if_optional_is_empty() { // GIVEN Optional<Object> actual = Optional.empty(); // WHEN var assertionError = expectAssertionError(() -> assertThat(actual).containsInstanceOf(Object.class)); // THEN then(assertionError).hasMessage(shouldBePresent(actual).create()); } @Test void should_pass_if_optional_contains_required_type() { // GIVEN Optional<String> optional = Optional.of("something"); // WHEN/THEN then(optional).containsInstanceOf(String.class); } }

Javadoc编写规范

良好的Javadoc应包含断言描述、代码示例、参数说明、异常描述和@since标签。以下是一个优秀的Javadoc示例：

/** * Verifies that the actual {@code CharSequence} contains all the given strings <b>in the given order</b>. * <p> * Example: * * <pre><code class='java'> String book = "{ 'title':'A Game of Thrones', 'author':'George Martin'}"; * * // this assertion succeeds ... * assertThat(book).containsSequence("{", "title", "A Game of Thrones", "}"); * * // ... but this one fails as "author" must come after "A Game of Thrones" * assertThat(book).containsSequence("{", "author", "A Game of Thrones", "}"); </code></pre> * * @param values the Strings to look for, in order. * @return {@code this} assertion object. * @throws NullPointerException if the given values is {@code null}. * @throws IllegalArgumentException if the given values is empty. * @throws AssertionError if the actual {@code CharSequence} is {@code null}. * @throws AssertionError if the actual {@code CharSequence} does not contain all the given strings <b>in the given order</b>. * @since 2.1.0 / 3.1.0 */

提交贡献的步骤

1. 准备代码

• 在提交PR前执行./mvnw spotless:apply确保代码格式正确
• 执行./mvnw clean verify确保所有测试通过

2. 提交PR

• 将PR基于main分支进行rebase（不要合并！）
• 我们倾向于通过压缩所有提交并rebase到main来集成PR
• 如果PR有分歧并需要获取更新的main提交，请rebase到main，但不要将main合并到你的PR分支

二进制兼容性注意事项

尽量保持二进制兼容性，以下更改通常是安全的：

• 重写方法、构造函数和初始化器的主体
• 重写以前抛出异常的代码以不再抛出
• 添加字段、方法和构造函数
• 删除声明为私有的元素
• 重新排序字段、方法和构造函数
• 在类层次结构中向上移动方法
• 重新排序类或接口中的直接超接口列表
• 在类型层次结构中插入新的类或接口类型
• 添加泛型（因为编译器会擦除它们）
• 更新包私有元素

其他更改可能会影响二进制兼容性，这些不会被自动拒绝，但我们会仔细评估每个更改的利弊。

法律声明

项目许可证：Apache License Version 2.0

作为贡献者：

• 你提交的贡献必须是你100%原创的内容
• 你必须对提交的贡献拥有必要的权利。这意味着如果你受雇，你已获得雇主的必要许可
• 你贡献的任何内容将根据项目许可证提供

开始你的贡献之旅

现在你已经了解了AssertJ的贡献规范，是时候开始你的贡献之旅了！无论是修复bug、添加新功能还是改进文档，你的每一份贡献都将帮助AssertJ变得更好。克隆仓库开始贡献吧：

git clone https://gitcode.com/gh_mirrors/as/assertj

加入AssertJ社区，一起打造更强大的Java测试断言库！

【免费下载链接】assertjFluent testing assertions for Java and the JVM项目地址: https://gitcode.com/gh_mirrors/as/assertj