6.9 Elasticsearch-单元测试：ESSingleNodeTestCase ESIntegTestCase-编程实验室

6.9 Elasticsearch-单元测试：ESSingleNodeTestCase & ESIntegTestCase

6.9.1 为什么需要两类测试基类

Elasticsearch 的源码里，90 % 的“单元测试”其实都在和磁盘、网络、集群状态打交道。

如果你只想验证一个分词器、一个聚合器或者一个查询解析器，启动 3～5 个节点的集成环境显然太重。
如果你要跑通一条跨节点的聚合、快照、CCR、ILM 链路，单节点又无法暴露分布式边界带来的 bug。

于是官方提供了两条基线：

ESSingleNodeTestCase——轻量级，单进程，零网络，秒级起停。
ESIntegTestCase——重量级，内嵌“迷你”集群，端口随机，可水平扩缩，完整走 Transport 层。

选对基类，可以把单测耗时从 30 s 压到 3 s，也能把分布式缺陷在 PR 阶段就暴露出来，而不是凌晨 3 点在线上爆炸。

6.9.2 ESSingleNodeTestCase 核心机制

1. 启动路径

@BeforeClass→startNode()→ 新建Node实例（内部走NodeBuilder与真实启动流程完全一致，只是把cluster.name设成随机值，并把discovery.type设成single-node）。
整个生命周期跟随 JUnit 的Suite，所有测试方法共用一个Client，方法级并行默认关闭，避免多个线程同时refresh或flush互相干扰。

2. Client 句柄

protectedClientclient(){returninternalCluster().client();}

返回的是NodeClient，请求直接在 JVM 内走TransportService#sendLocalRequest，不经过 Netty，因此抓包工具看不到任何 9200 端口的流量。

3. 索引模板与设置

基类会自动把index.number_of_shards固定为 1，number_of_replicas为 0，避免黄色状态；同时禁用merge scheduler的限流，让段合并更快完成。
如果你的测试依赖自定义分析器，在@Before里调用

createIndex("test",Settings.EMPTY,"my_analyzer","/path/to/test_mapping.json");

即可一次性把 settings + mappings 灌进去。

4. 断言工具

ESSingleNodeTestCase继承了ESTestCase，因此可以直接使用：

assertHitCount(client().prepareSearch("test").setSize(0).get(), 42L);
assertAcked(client().admin().indices().prepareCreate("test2"));
expectThrows(ElasticsearchException.class, () -> client().prepareGet("no", "1").get());

5. 典型耗时

M1 芯片 + SSD 环境下，空跑一个测试方法大约 1.2 s，其中 70 % 花在 Lucene 的目录锁与快照提交上；如果加上 10 万次index请求，总耗时 3～4 s，仍比迷你集群快一个数量级。

6.9.3 ESIntegTestCase 分布式能力

1. 集群拓扑

@Before→InternalTestCluster#beforeTest()根据cluster.scale随机启动 2～6 个节点（可通过-Dtests.cluster.size固定），每个节点独立数据目录、独立Transport端口，但共享同一个JVM（方便调试）。
节点之间走MockTransportService，内部用ConcurrentHashMap模拟网络，因此不会出现端口冲突，也不必真的监听 9300。

2. 随机化与混沌

每次运行会随机轮换以下变量：

主节点选举时机（通过ClusterDisruptionIT注入 100 ms 网络分区）。
分片分配权重（让 3 副本落在 2 节点上，触发ShardAllocator重平衡）。
refresh_interval在-1/1s/100ms之间随机，暴露近实时可见性 bug。
indices.memory.index_buffer_size从10%到20%抖动，验证写队列背压。

3. 断网、杀节点、重启

internalCluster().stopRandomDataNode();internalCluster().restartRandomDataNode(newInternalTestCluster.RestartCallback(){publicbooleanclearData(StringnodeName){returnrandomBoolean();}});

可以模拟磁盘掉盘、节点失联、Master 重新选举等流程，配合ClusterServiceUtils#awaitClusterState等待状态收敛。

4. 多版本升级测试

ESIntegTestCase支持在test资源目录里放置zip格式的旧版本索引，测试启动后通过ElasticsearchAssertions#assertIndexExists验证在线迁移。官方RollingUpgradeIT就是基于该能力，把 7.17 的索引迁移到 8.x，再跑一遍查询对比结果。

6.9.4 如何抉择：一张速查表

场景	推荐基类	备注
写一个新 TokenFilter	`ESSingleNodeTestCase`	无需分布式，只需`analyze`API
验证 Nested 聚合结果	`ESSingleNodeTestCase`	数据量 <10 万，单分片足够
测试`terms`跨分片精度	`ESIntegTestCase`	必须 3+ 分片才能暴露`doc_count_error`
验证 CCR 跟随索引	`ESIntegTestCase`	需要 2 集群，至少 4 节点
快照 repository 异常回滚	`ESIntegTestCase`	需要`blobStore`多节点并发写
只想在 5 s 内跑完 CI	`ESSingleNodeTestCase`	把重型测试放到 nightly 任务

6.9.5 常见踩坑与排查清单

端口被占用
错误日志出现BindTransportException[Address already in use]，99 % 是因为前一个测试进程没退干净。
解决：在 IDEA 的 JUnit 模板里加上-Dtests.cluster.basePort=33000-34000，让InternalTestCluster每次都随机选段。
文件句柄泄漏
测试结束后目录删不掉，Windows 下尤为明显。
解决：在@After里显式调用IOUtils#rm(tmpDir)，并确保Store#close()先于Node#close()，否则MMapDirectory的句柄会被复用。
时间敏感断言
使用assertBusy(() -> assertThat(count, equalTo(100L)), 30, TimeUnit.SECONDS)代替固定Thread.sleep，避免在慢机器上随机失败。
测试数据污染
所有索引名、模板名、管道名统一加上test-method级别的随机前缀：
```
finalStringindex=randomAlphaOfLength(10).toLowerCase(Locale.ROOT);
```
保证并行执行时不会互相覆盖。
Gradle 并行执行
使用./gradlew :server:test --tests "*ESSingleNodeTestCase*"时默认开启maxParallelForks=8，单节点基类没问题，但ESIntegTestCase会抢端口。
解决：在build.gradle里给integTest任务单独设置maxParallelForks = 1，或者加@TestInstance(Lifecycle.PER_METHOD)隔离。