Java中Protobuf3文本消息快照测试方法及可用工具咨询

核心思路 #

Protobuf3的快照测试本质是将目标Message实例序列化为人类可读的文本格式，再与预先存储的基准快照文件做一致性校验。核心依赖Protobuf官方的TextFormat工具类，它能把结构化的Protobuf消息转成易读的文本格式（类似JSON但更贴合Protobuf语法）。测试流程如下：

1. 生成待测试的Protobuf消息实例
2. 用TextFormat将其序列化为标准文本
3. 与已存储的快照文本对比：
   • 一致则测试通过
   • 不一致时，要么确认是预期变更并更新快照，要么修复代码逻辑

可用Java库/实现方式 #

1. AssertJ-Protobuf（推荐） #

AssertJ的Protobuf扩展库，原生支持Protobuf消息的断言，包括直接与文本快照对比的能力，集成简单，语法友好。

• 依赖配置（Maven）：

<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-protobuf</artifactId>
    <version>3.24.2</version>
    <scope>test</scope>
</dependency>

• 测试示例：

import com.google.protobuf.TextFormat;
import org.assertj.core.api.Assertions;
import org.junit.jupiter.api.Test;
import java.nio.file.Files;
import java.nio.file.Paths;

public class ProtobufSnapshotTest {
    @Test
    void testProtobufSnapshot() throws Exception {
        // 生成待测试的Protobuf消息
        UserProto.User user = UserProto.User.newBuilder()
                .setId(123)
                .setName("Alice")
                .setEmail("alice@example.com")
                .build();

        // 读取基准快照文件内容
        String snapshotContent = Files.readString(Paths.get("src/test/resources/snapshots/user_snapshot.txt"));

        // 断言消息与快照文本匹配
        Assertions.assertThat(user).isEqualTo(TextFormat.parse(snapshotContent, UserProto.User.class));
    }
}

如果需要更新快照，只需将当前消息的文本输出写入快照文件即可：

// 更新快照逻辑
Files.writeString(Paths.get("src/test/resources/snapshots/user_snapshot.txt"), TextFormat.printToString(user));

2. 自定义快照实现（无第三方依赖） #

如果不想引入额外库，可基于Junit + Protobuf原生API快速实现：

import com.google.protobuf.TextFormat;
import org.junit.jupiter.api.Test;
import java.nio.file.Files;
import java.nio.file.Paths;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class CustomProtobufSnapshotTest {
    private static final String SNAPSHOT_PATH = "src/test/resources/snapshots/user_snapshot.txt";

    @Test
    void testUserSnapshot() throws Exception {
        UserProto.User user = UserProto.User.newBuilder()
                .setId(123)
                .setName("Alice")
                .setEmail("alice@example.com")
                .build();

        String actualText = TextFormat.printToString(user);
        String expectedText = Files.readString(Paths.get(SNAPSHOT_PATH));

        // 对比文本内容
        assertEquals(expectedText.trim(), actualText.trim());
    }

    // 手动更新快照的方法（可单独执行或加注解控制）
    // @Test
    void updateSnapshot() throws Exception {
        UserProto.User user = UserProto.User.newBuilder()
                .setId(123)
                .setName("Alice")
                .setEmail("alice@example.com")
                .build();
        Files.writeString(Paths.get(SNAPSHOT_PATH), TextFormat.printToString(user));
    }
}

3. Spring Boot Test 快照支持 #

如果是Spring Boot项目，可使用org.springframework.boot.test.autoconfigure.json.SnapshotAssertions结合TextFormat实现：

import com.google.protobuf.TextFormat;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.JsonTest;
import org.springframework.boot.test.autoconfigure.json.SnapshotAssertions;

@JsonTest
public class SpringProtobufSnapshotTest {
    @Autowired
    private SnapshotAssertions snapshotAssertions;

    @Test
    void testUserSnapshot() throws Exception {
        UserProto.User user = UserProto.User.newBuilder()
                .setId(123)
                .setName("Alice")
                .setEmail("alice@example.com")
                .build();

        // 将Protobuf文本转为字符串后对比快照
        snapshotAssertions.assertThat(TextFormat.printToString(user)).matchesSnapshot();
    }
}

注意事项 #

• 确保TextFormat的输出格式稳定：Protobuf的TextFormat默认会按字段声明顺序输出，避免因字段顺序变化导致不必要的快照不匹配
• 快照文件建议放在src/test/resources/snapshots目录，纳入版本控制
• 批量更新快照时，可编写统一的工具方法或脚本，避免手动修改

内容的提问来源于stack exchange，提问作者tuk