0
# Elasticsearch Test Framework
1

2
The Elasticsearch Test Framework (`org.elasticsearch.test:framework`) provides comprehensive testing utilities for Elasticsearch development. This framework includes 386+ classes organized into specialized testing packages, offering everything from basic unit test utilities to complex multi-node integration testing capabilities.
3

4
## Package Information
5

6
- **Package Name**: elasticsearch-test-framework
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.elasticsearch
10
- **Artifact ID**: elasticsearch-test-framework
11
- **Installation**: Add to Maven `pom.xml`:
12
  ```xml
13
  <dependency>
14
    <groupId>org.elasticsearch</groupId>
15
    <artifactId>elasticsearch-test-framework</artifactId>
16
    <version>9.0.3</version>
17
    <scope>test</scope>
18
  </dependency>
19
  ```
20
  
21
  Or to Gradle `build.gradle`:
22
  ```gradle
23
  testImplementation 'org.elasticsearch:elasticsearch-test-framework:9.0.3'
24
  ```
25

26
## Overview
27

28
This testing framework is built on top of Apache Lucene's testing infrastructure and extends it with Elasticsearch-specific functionality. It provides mock implementations, specialized assertion utilities, cluster management capabilities, and data generation tools designed specifically for testing Elasticsearch functionality.
29

30
```{ .api }
31
// Core package structure
32
org.elasticsearch.test
33
├── ESTestCase                    // Base class for all Elasticsearch unit tests  
34
├── ESIntegTestCase              // Base class for integration tests
35
├── InternalTestCluster          // Multi-node test cluster management
36
├── SingleNodeTestCase           // Single node test scenarios
37
└── hamcrest/                    // Custom Hamcrest matchers
38
    └── ElasticsearchAssertions  // Elasticsearch-specific assertions
39
```
40

41
## Architecture
42

43
The framework follows a layered architecture:
44

45
1. **Base Layer**: Core test classes extending Lucene's testing infrastructure
46
2. **Cluster Management**: Multi-node cluster lifecycle and node management
47
3. **Mock Layer**: Mock implementations for transport, storage, and security
48
4. **Assertion Layer**: Custom matchers and validation utilities
49
5. **Specialization Layer**: Domain-specific testing utilities (REST, XContent, etc.)
50
6. **Data Generation**: Synthetic document and field data generators
51

52
## Core Imports
53

54
Standard import patterns for using the Elasticsearch Test Framework:
55

56
```java
57
// Core test base classes
58
import org.elasticsearch.test.ESTestCase;
59
import org.elasticsearch.test.ESIntegTestCase;
60
import org.elasticsearch.test.ESSingleNodeTestCase;
61

62
// Cluster management
63
import org.elasticsearch.test.InternalTestCluster;
64
import org.elasticsearch.test.TestCluster;
65

66
// Custom assertions and matchers  
67
import org.elasticsearch.test.hamcrest.ElasticsearchAssertions;
68
import static org.elasticsearch.test.hamcrest.ElasticsearchAssertions.*;
69

70
// Common Hamcrest matchers
71
import static org.hamcrest.Matchers.*;
72
import static org.junit.Assert.assertThat;
73

74
// Mock implementations
75
import org.elasticsearch.test.transport.MockTransportService;
76
import org.elasticsearch.common.settings.MockSecureSettings;
77
import org.elasticsearch.test.store.MockDirectoryWrapper;
78
```
79

80
## Key Capabilities
81

82
### Core Testing
83
- **Unit Testing**: `ESTestCase` provides randomized testing with Elasticsearch-specific setup
84
- **Integration Testing**: `ESIntegTestCase` manages full Elasticsearch clusters
85
- **Single Node Testing**: `SingleNodeTestCase` for lightweight integration scenarios
86

87
### Cluster Management
88
- **Multi-node Clusters**: Start, stop, and configure multiple Elasticsearch nodes
89
- **Node Lifecycle**: Control individual node startup, shutdown, and restart
90
- **Cluster State**: Wait for cluster health, manage routing, and verify consistency
91

92
### Mock Implementations  
93
- **Transport Layer**: Mock network communication and simulate failures
94
- **Storage Layer**: Mock repositories, blob stores, and filesystem operations
95
- **Security**: Mock secure settings and authentication mechanisms
96

97
### Assertion Utilities
98
- **Custom Matchers**: Elasticsearch-specific Hamcrest matchers for responses, documents, and cluster state
99
- **Fluent Assertions**: Builder pattern for complex assertion scenarios
100
- **Async Testing**: Utilities for testing asynchronous operations and futures
101

102
### Specialized Testing
103
- **REST Testing**: Framework for testing REST APIs with request/response validation
104
- **XContent Testing**: JSON/XML serialization and deserialization testing
105
- **Query Testing**: Query builder validation and Lucene query assertion
106
- **Disruption Testing**: Network partition and service disruption simulation
107

108
## Package Structure
109

110
### Core Test Classes (`org.elasticsearch.test`)
111
```{ .api }
112
import org.elasticsearch.test.ESTestCase;
113
import org.elasticsearch.test.ESIntegTestCase;
114
import org.elasticsearch.test.InternalTestCluster;
115
import org.elasticsearch.test.SingleNodeTestCase;
116
```
117

118
### Assertion and Matching (`org.elasticsearch.test.hamcrest`)
119
```{ .api }
120
import org.elasticsearch.test.hamcrest.ElasticsearchAssertions;
121
import org.elasticsearch.test.hamcrest.OptionalMatchers;
122
import org.elasticsearch.test.hamcrest.TupleMatchers;
123
```
124

125
### Mock Implementations (`org.elasticsearch.test.transport`, `org.elasticsearch.common.settings`)
126
```{ .api }
127
import org.elasticsearch.test.transport.MockTransportService;
128
import org.elasticsearch.common.settings.MockSecureSettings;
129
import org.elasticsearch.test.store.MockDirectoryWrapper;
130
```
131

132
### Disruption Testing (`org.elasticsearch.test.disruption`)
133
```{ .api }
134
import org.elasticsearch.test.disruption.NetworkDisruption;
135
import org.elasticsearch.test.disruption.ServiceDisruptionScheme;
136
import org.elasticsearch.test.disruption.SingleNodeDisruption;
137
```
138

139
### REST Testing (`org.elasticsearch.test.rest`)
140
```{ .api }
141
import org.elasticsearch.test.rest.ESRestTestCase;
142
import org.elasticsearch.test.rest.ObjectPath;
143
import org.elasticsearch.test.rest.RestTestExecutionContext;
144
```
145

146
### Data Generation (`org.elasticsearch.logsdb.datageneration`)
147
```{ .api }
148
import org.elasticsearch.logsdb.datageneration.DocumentGenerator;
149
import org.elasticsearch.logsdb.datageneration.FieldDataGenerator;
150
import org.elasticsearch.logsdb.datageneration.DataGenerator;
151
```
152

153
## Basic Usage
154

155
### Simple Unit Test
156
```java
157
import org.elasticsearch.test.ESTestCase;
158

159
public class MyElasticsearchTest extends ESTestCase {
160
    
161
    public void testBasicFunctionality() {
162
        String randomValue = randomAlphaOfLength(10);
163
        int randomInt = randomIntBetween(1, 100);
164
        
165
        // Your test logic here
166
        assertThat(randomValue, notNullValue());
167
        assertThat(randomInt, allOf(greaterThan(0), lessThanOrEqualTo(100)));
168
    }
169
}
170
```
171

172
### Integration Test with Cluster
173
```java
174
import org.elasticsearch.test.ESIntegTestCase;
175

176
public class MyIntegrationTest extends ESIntegTestCase {
177
    
178
    public void testClusterOperations() {
179
        createIndex("test-index");
180
        ensureGreen("test-index");
181
        
182
        // Index a document
183
        client().prepareIndex("test-index")
184
            .setSource("field", "value")
185
            .get();
186
        
187
        // Search and verify
188
        SearchResponse response = client().prepareSearch("test-index")
189
            .get();
190
            
191
        assertThat(response.getHits().getTotalHits().value, equalTo(1L));
192
    }
193
}
194
```
195

196
## Sub-Documentation
197

198
This comprehensive documentation is organized into focused areas:
199

200
- **[Core Testing](core-testing.md)** - ESTestCase, ESIntegTestCase, and fundamental test classes
201
- **[Cluster Management](cluster-management.md)** - InternalTestCluster and node lifecycle management  
202
- **[Mock Implementations](mock-implementations.md)** - Transport, storage, and security mocks
203
- **[Assertions & Matchers](assertions-matchers.md)** - Custom Hamcrest matchers and assertion utilities
204
- **[Specialized Testing](specialized-testing.md)** - XContent, queries, REST, and disruption testing
205
- **[Data Generation](data-generation.md)** - Document and field data generation utilities
206

207
Each section provides detailed API documentation, usage examples, and best practices for effective Elasticsearch testing.
208

209
## Design Philosophy
210

211
The Elasticsearch Test Framework is designed around several key principles:
212

213
1. **Randomized Testing**: Extensive use of randomization to catch edge cases and improve test coverage
214
2. **Isolation**: Tests are isolated from each other with proper setup/teardown lifecycle management  
215
3. **Realism**: Test environments closely mirror production Elasticsearch deployments
216
4. **Extensibility**: Pluggable architecture allows custom test scenarios and mock implementations
217
5. **Performance**: Optimized for fast test execution while maintaining thoroughness
218

219
This framework enables comprehensive testing of Elasticsearch functionality from simple unit tests to complex distributed scenarios, ensuring robust and reliable Elasticsearch deployments.