0
# Mock Implementations
1

2
The Elasticsearch test framework provides comprehensive mock implementations for transport, storage, security, and other core systems. These mocks enable controlled testing environments, failure simulation, and isolation of specific components during testing.
3

4
## Mock Transport Layer
5

6
### MockTransportService
7

8
The core mock transport service that enables network failure simulation and transport behavior testing.
9

10
```{ .api }
11
package org.elasticsearch.test.transport;
12

13
import org.elasticsearch.action.ActionListener;
14
import org.elasticsearch.cluster.node.DiscoveryNode;
15
import org.elasticsearch.common.component.Lifecycle;
16
import org.elasticsearch.common.settings.Settings;
17
import org.elasticsearch.transport.*;
18

19
/**
20
 * Mock implementation of TransportService that allows injection of transport rules
21
 * for simulating network failures, delays, and other transport-level behaviors.
22
 */
23
public class MockTransportService extends TransportService {
24
    
25
    /**
26
     * Creates a new MockTransportService with the specified transport.
27
     * 
28
     * @param settings service configuration
29
     * @param transport underlying transport implementation
30
     * @param threadPool thread pool for async operations
31
     * @param interceptor transport interceptor for request/response handling
32
     * @param localNodeFactory factory for creating local node representation
33
     * @param clusterSettings cluster-level settings
34
     * @param taskHeaders task header registry
35
     */
36
    public MockTransportService(Settings settings, 
37
                               Transport transport, 
38
                               ThreadPool threadPool,
39
                               TransportInterceptor interceptor,
40
                               Function<BoundTransportAddress, DiscoveryNode> localNodeFactory,
41
                               ClusterSettings clusterSettings, 
42
                               Set<String> taskHeaders);
43
    
44
    /**
45
     * Adds a rule that causes connections to fail when sending to specified nodes.
46
     * 
47
     * @param targetNode node to target for failures
48
     * @param action action pattern to match (can use wildcards)
49
     */
50
    public void addFailToSendNoConnectRule(DiscoveryNode targetNode, String action);
51
    
52
    /**
53
     * Adds a rule that causes connections to fail for all actions to a node.
54
     * 
55
     * @param targetNode target node for connection failures
56
     */
57
    public void addFailToSendNoConnectRule(DiscoveryNode targetNode);
58
    
59
    /**
60
     * Adds a rule that introduces delays when sending to specified nodes.
61
     * 
62
     * @param targetNode node to introduce delays for
63
     * @param action action pattern to match
64
     * @param delay time delay to introduce
65
     */
66
    public void addSendBehaviorRule(DiscoveryNode targetNode, String action, TimeValue delay);
67
    
68
    /**
69
     * Adds a rule that randomly fails requests to simulate unreliable networks.
70
     * 
71
     * @param targetNode target node
72
     * @param action action pattern
73
     * @param failureRate probability of failure (0.0 to 1.0)
74
     */
75
    public void addRandomFailureRule(DiscoveryNode targetNode, String action, double failureRate);
76
    
77
    /**
78
     * Adds a rule that blocks requests indefinitely to simulate network partitions.
79
     * 
80
     * @param targetNode node to block requests to
81
     * @param action action pattern to block
82
     */
83
    public void addUnresponsiveRule(DiscoveryNode targetNode, String action);
84
    
85
    /**
86
     * Removes all transport rules and returns to normal operation.
87
     */
88
    public void clearAllRules();
89
    
90
    /**
91
     * Removes rules targeting a specific node.
92
     * 
93
     * @param targetNode node to clear rules for
94
     */
95
    public void clearRules(DiscoveryNode targetNode);
96
    
97
    /**
98
     * Gets the transport instance used by this service.
99
     * 
100
     * @return underlying Transport
101
     */
102
    public MockTransport transport();
103
    
104
    /**
105
     * Interface for defining transport behavior rules.
106
     */
107
    public static interface TransportRule {
108
        /**
109
         * Applies the rule to an outgoing request.
110
         * 
111
         * @param request transport request
112
         * @param connection target connection
113
         * @param requestId request identifier
114
         * @param action action being performed
115
         * @param listener response listener
116
         * @return true if rule was applied, false to continue processing
117
         */
118
        boolean apply(TransportRequest request, 
119
                     Connection connection,
120
                     long requestId, 
121
                     String action,
122
                     TransportResponseHandler<?> listener);
123
    }
124
}
125
```
126

127
### CapturingTransport
128

129
Transport implementation that captures requests for analysis and verification.
130

131
```{ .api }
132
package org.elasticsearch.test.transport;
133

134
import org.elasticsearch.action.ActionListener;
135
import org.elasticsearch.cluster.node.DiscoveryNode;
136
import org.elasticsearch.transport.Transport;
137
import org.elasticsearch.transport.TransportRequest;
138

139
/**
140
 * Transport implementation that captures all requests and responses for test verification.
141
 * Useful for verifying that specific transport operations occur during testing.
142
 */
143
public class CapturingTransport implements Transport {
144
    
145
    /**
146
     * Represents a captured transport request.
147
     */
148
    public static class CapturedRequest {
149
        /** The target node for this request */
150
        public final DiscoveryNode node;
151
        /** The request identifier */
152
        public final long requestId;
153
        /** The action being performed */
154
        public final String action;
155
        /** The request object */
156
        public final TransportRequest request;
157
        
158
        public CapturedRequest(DiscoveryNode node, long requestId, String action, TransportRequest request);
159
    }
160
    
161
    /**
162
     * Returns all captured requests.
163
     * 
164
     * @return list of captured requests
165
     */
166
    public List<CapturedRequest> getCapturedRequests();
167
    
168
    /**
169
     * Returns captured requests for a specific action.
170
     * 
171
     * @param action action name to filter by
172
     * @return filtered list of captured requests
173
     */
174
    public List<CapturedRequest> getCapturedRequestsAndClear(String action);
175
    
176
    /**
177
     * Clears all captured requests.
178
     */
179
    public void clear();
180
    
181
    /**
182
     * Sets a response handler for specific actions.
183
     * 
184
     * @param action action to handle
185
     * @param response response to return
186
     */
187
    public void setResponseHandler(String action, TransportResponse response);
188
    
189
    /**
190
     * Sets an exception handler for specific actions.
191
     * 
192
     * @param action action to handle
193
     * @param exception exception to throw
194
     */
195
    public void setExceptionHandler(String action, Exception exception);
196
}
197
```
198

199
### StubbableTransport
200

201
Transport with advanced stubbing capabilities for complex test scenarios.
202

203
```{ .api }
204
package org.elasticsearch.test.transport;
205

206
/**
207
 * Transport implementation with sophisticated stubbing capabilities for complex testing scenarios.
208
 * Allows detailed control over request/response patterns and behavior simulation.
209
 */
210
public class StubbableTransport implements Transport {
211
    
212
    /**
213
     * Represents a request pattern for stubbing.
214
     */
215
    public static class RequestPattern {
216
        private final String action;
217
        private final Predicate<TransportRequest> requestMatcher;
218
        
219
        public static RequestPattern forAction(String action);
220
        public static RequestPattern matching(String action, Predicate<TransportRequest> matcher);
221
    }
222
    
223
    /**
224
     * Stubs responses for requests matching the specified pattern.
225
     * 
226
     * @param pattern request pattern to match
227
     * @param response response to return
228
     */
229
    public StubbableTransport stub(RequestPattern pattern, TransportResponse response);
230
    
231
    /**
232
     * Stubs exceptions for requests matching the specified pattern.
233
     * 
234
     * @param pattern request pattern to match
235
     * @param exception exception to throw
236
     */  
237
    public StubbableTransport stub(RequestPattern pattern, Exception exception);
238
    
239
    /**
240
     * Stubs delayed responses.
241
     * 
242
     * @param pattern request pattern to match
243
     * @param response response to return after delay
244
     * @param delay time to wait before responding
245
     */
246
    public StubbableTransport stubWithDelay(RequestPattern pattern, 
247
                                          TransportResponse response, 
248
                                          TimeValue delay);
249
    
250
    /**
251
     * Removes all stubs and returns to pass-through behavior.
252
     */
253
    public void clearStubs();
254
}
255
```
256

257
### Transport Mock Usage Examples
258

259
```java
260
import org.elasticsearch.test.ESIntegTestCase;
261
import org.elasticsearch.test.transport.MockTransportService;
262

263
public class TransportMockTest extends ESIntegTestCase {
264
    
265
    public void testNetworkPartition() {
266
        InternalTestCluster cluster = internalCluster();
267
        cluster.ensureAtLeastNumDataNodes(3);
268
        
269
        // Get transport service for a specific node
270
        MockTransportService transportService = 
271
            (MockTransportService) cluster.getInstance(TransportService.class, "node1");
272
        
273
        // Simulate network partition - block all communication to node2
274
        DiscoveryNode node2 = cluster.clusterService("node2").localNode();
275
        transportService.addUnresponsiveRule(node2);
276
        
277
        // Test that operations handle the partition gracefully
278
        try {
279
            createIndex("partition-test");
280
            // Operations should still succeed on available nodes
281
            ensureYellow("partition-test");
282
        } finally {
283
            // Clear rules to restore connectivity
284
            transportService.clearAllRules();
285
            ensureGreen("partition-test");
286
        }
287
    }
288
    
289
    public void testTransportFailures() {
290
        InternalTestCluster cluster = internalCluster();
291
        MockTransportService transportService = 
292
            (MockTransportService) cluster.getInstance(TransportService.class);
293
        
294
        DiscoveryNode targetNode = cluster.clusterService().state().nodes().getDataNodes().values().iterator().next();
295
        
296
        // Simulate 50% failure rate for search actions
297
        transportService.addRandomFailureRule(targetNode, "indices:data/read/search", 0.5);
298
        
299
        // Test search resilience
300
        createIndex("failure-test");
301
        client().prepareIndex("failure-test")
302
            .setSource("field", "value")
303
            .setRefreshPolicy(WriteRequest.RefreshPolicy.IMMEDIATE)
304
            .get();
305
        
306
        // Some searches may fail, but retries should succeed
307
        int successCount = 0;
308
        for (int i = 0; i < 10; i++) {
309
            try {
310
                client().prepareSearch("failure-test").get();
311
                successCount++;
312
            } catch (Exception e) {
313
                // Expected occasional failures
314
            }
315
        }
316
        
317
        assertThat("Some searches should succeed", successCount, greaterThan(0));
318
        
319
        transportService.clearAllRules();
320
    }
321
}
322
```
323

324
## Mock Storage Layer
325

326
### MockSecureSettings
327

328
Mock implementation for secure settings testing.
329

330
```{ .api }
331
package org.elasticsearch.common.settings;
332

333
import java.io.InputStream;
334

335
/**
336
 * Mock implementation of SecureSettings for testing secure configuration handling.
337
 * Allows controlled testing of secure settings without requiring actual keystore files.
338
 */
339
public class MockSecureSettings implements SecureSettings {
340
    
341
    /**
342
     * Creates a new empty MockSecureSettings instance.
343
     */
344
    public MockSecureSettings();
345
    
346
    /**
347
     * Creates a MockSecureSettings with the specified settings.
348
     * 
349
     * @param settings map of setting names to values
350
     */
351
    public MockSecureSettings(Map<String, String> settings);
352
    
353
    /**
354
     * Sets a string value for the specified setting.
355
     * 
356
     * @param setting setting name
357
     * @param value string value to set
358
     * @return this MockSecureSettings for fluent chaining
359
     */
360
    public MockSecureSettings setString(String setting, String value);
361
    
362
    /**
363
     * Sets a file content value for the specified setting.
364
     * 
365
     * @param setting setting name
366
     * @param bytes file content as byte array
367
     * @return this MockSecureSettings for fluent chaining
368
     */
369
    public MockSecureSettings setFile(String setting, byte[] bytes);
370
    
371
    /**
372
     * Sets a file content value from an InputStream.
373
     * 
374
     * @param setting setting name
375
     * @param input stream containing file content
376
     * @return this MockSecureSettings for fluent chaining
377
     */
378
    public MockSecureSettings setFile(String setting, InputStream input);
379
    
380
    /**
381
     * Removes a setting from the mock secure settings.
382
     * 
383
     * @param setting setting name to remove
384
     * @return this MockSecureSettings for fluent chaining
385
     */
386
    public MockSecureSettings remove(String setting);
387
    
388
    /**
389
     * Checks if the specified setting exists.
390
     * 
391
     * @param setting setting name to check
392
     * @return true if setting exists, false otherwise
393
     */
394
    @Override
395
    public boolean isLoaded();
396
    
397
    /**
398
     * Returns all setting names.
399
     * 
400
     * @return set of setting names
401
     */
402
    @Override
403
    public Set<String> getSettingNames();
404
    
405
    /**
406
     * Gets a secure string value.
407
     * 
408
     * @param setting setting name
409
     * @return SecureString containing the value
410
     */
411
    @Override
412
    public SecureString getString(String setting);
413
    
414
    /**
415
     * Gets a secure file input stream.
416
     * 
417
     * @param setting setting name
418
     * @return InputStream for the file content
419
     */
420
    @Override 
421
    public InputStream getFile(String setting);
422
    
423
    /**
424
     * Gets the SHA-256 digest of a file setting.
425
     * 
426
     * @param setting setting name
427
     * @return byte array containing SHA-256 hash
428
     */
429
    @Override
430
    public byte[] getSHA256Digest(String setting);
431
}
432
```
433

434
### MockRepository
435

436
Mock repository implementation for testing backup and restore operations.
437

438
```{ .api }
439
package org.elasticsearch.repositories;
440

441
import org.elasticsearch.cluster.metadata.RepositoryMetadata;
442
import org.elasticsearch.cluster.service.ClusterService;
443
import org.elasticsearch.common.blobstore.BlobStore;
444

445
/**
446
 * Mock repository implementation for testing snapshot and restore operations
447
 * without requiring actual storage backends.
448
 */
449
public class MockRepository extends BlobStoreRepository {
450
    
451
    /**
452
     * Creates a MockRepository with the specified configuration.
453
     * 
454
     * @param metadata repository metadata
455
     * @param clusterService cluster service instance
456
     */
457
    public MockRepository(RepositoryMetadata metadata, ClusterService clusterService);
458
    
459
    /**
460
     * Sets the failure mode for repository operations.
461
     * 
462
     * @param failureMode type of failures to simulate
463
     */
464
    public void setFailureMode(FailureMode failureMode);
465
    
466
    /**
467
     * Sets a specific failure for the next operation.
468
     * 
469
     * @param operation operation to fail
470
     * @param exception exception to throw
471
     */
472
    public void setNextFailure(String operation, Exception exception);
473
    
474
    /**
475
     * Gets the underlying mock blob store.
476
     * 
477
     * @return MockBlobStore instance
478
     */
479
    public MockBlobStore getMockBlobStore();
480
    
481
    /**
482
     * Enumeration of failure modes for repository operations.
483
     */
484
    public enum FailureMode {
485
        /** No failures */
486
        NONE,
487
        /** Random failures */  
488
        RANDOM,
489
        /** All operations fail */
490
        ALL,
491
        /** Only write operations fail */
492
        WRITE_ONLY,
493
        /** Only read operations fail */
494
        READ_ONLY
495
    }
496
}
497
```
498

499
### MockBlobStore
500

501
Mock blob store for testing blob storage operations.
502

503
```{ .api }
504
package org.elasticsearch.common.blobstore;
505

506
/**
507
 * Mock implementation of BlobStore for testing blob storage operations
508
 * without requiring actual storage infrastructure.
509
 */
510
public class MockBlobStore implements BlobStore {
511
    
512
    /**
513
     * Creates a new MockBlobStore.
514
     */
515
    public MockBlobStore();
516
    
517
    /**
518
     * Sets the failure probability for blob operations.
519
     * 
520
     * @param probability failure probability (0.0 to 1.0)
521
     */
522
    public void setFailureProbability(double probability);
523
    
524
    /**
525
     * Enables or disables atomic move operations.
526
     * 
527
     * @param atomic true to enable atomic moves
528
     */
529
    public void setAtomicMoveSupported(boolean atomic);
530
    
531
    /**
532
     * Gets statistics about blob operations performed.
533
     * 
534
     * @return BlobStoreStats with operation counts
535
     */
536
    public BlobStoreStats getStats();
537
    
538
    /**
539
     * Resets all statistics counters.
540
     */
541
    public void resetStats();
542
    
543
    /**
544
     * Statistics tracking for mock blob store operations.
545
     */
546
    public static class BlobStoreStats {
547
        public long readOperations;
548
        public long writeOperations; 
549
        public long deleteOperations;
550
        public long listOperations;
551
        public long bytesRead;
552
        public long bytesWritten;
553
    }
554
}
555
```
556

557
## Mock Utilities
558

559
### MockBigArrays
560

561
Mock implementation for large array management testing.
562

563
```{ .api }
564
package org.elasticsearch.common.util;
565

566
import org.elasticsearch.common.breaker.CircuitBreaker;
567
import org.elasticsearch.indices.breaker.CircuitBreakerService;
568

569
/**
570
 * Mock implementation of BigArrays for testing memory management and circuit breaker behavior.
571
 */
572
public class MockBigArrays extends BigArrays {
573
    
574
    /**
575
     * Creates MockBigArrays with the specified page cache and circuit breaker.
576
     * 
577
     * @param pageCacheRecycler page cache for memory reuse
578
     * @param circuitBreakerService circuit breaker for memory tracking
579
     * @param name identifier for this BigArrays instance
580
     */
581
    public MockBigArrays(PageCacheRecycler pageCacheRecycler, 
582
                        CircuitBreakerService circuitBreakerService, 
583
                        String name);
584
    
585
    /**
586
     * Sets whether array allocation should be tracked by circuit breakers.
587
     * 
588
     * @param track true to enable tracking
589
     */
590
    public void setTrackAllocations(boolean track);
591
    
592
    /**
593
     * Gets the total number of bytes allocated by this instance.
594
     * 
595
     * @return bytes allocated
596
     */
597
    public long getAllocatedBytes();
598
    
599
    /**
600
     * Gets the number of active array allocations.
601
     * 
602
     * @return active allocation count
603
     */
604
    public long getActiveAllocations();
605
}
606
```
607

608
### MockPageCacheRecycler
609

610
Mock page cache recycler for memory management testing.
611

612
```{ .api }
613
package org.elasticsearch.common.util;
614

615
/**
616
 * Mock implementation of PageCacheRecycler for testing page-based memory management.
617
 */
618
public class MockPageCacheRecycler extends PageCacheRecycler {
619
    
620
    /**
621
     * Creates a MockPageCacheRecycler with specified settings.
622
     * 
623
     * @param settings configuration settings
624
     */
625
    public MockPageCacheRecycler(Settings settings);
626
    
627
    /**
628
     * Sets the maximum number of pages to cache.
629
     * 
630
     * @param maxPages maximum cached page count
631
     */
632
    public void setMaxCachedPages(int maxPages);
633
    
634
    /**
635
     * Gets statistics about page recycling operations.
636
     * 
637
     * @return RecyclerStats with operation counts
638
     */
639
    public RecyclerStats getStats();
640
    
641
    /**
642
     * Forces garbage collection of cached pages.
643
     */
644
    public void forceRecycle();
645
    
646
    /**
647
     * Statistics for page recycler operations.
648
     */
649
    public static class RecyclerStats {
650
        public long pagesAllocated;
651
        public long pagesRecycled;
652
        public long pagesCached;
653
        public long cacheHits;
654
        public long cacheMisses;
655
    }
656
}
657
```
658

659
### Usage Examples
660

661
```java
662
import org.elasticsearch.common.settings.MockSecureSettings;
663
import org.elasticsearch.repositories.MockRepository;
664

665
public class MockStorageTest extends ESIntegTestCase {
666
    
667
    public void testSecureSettings() {
668
        MockSecureSettings secureSettings = new MockSecureSettings()
669
            .setString("xpack.security.authc.api_key.hashing.algorithm", "pbkdf2")
670
            .setFile("xpack.ssl.keystore.path", keystoreBytes);
671
        
672
        Settings settings = Settings.builder()
673
            .setSecureSettings(secureSettings)
674
            .build();
675
        
676
        // Test that secure settings are properly loaded
677
        assertTrue(settings.getSecureSettings().isLoaded());
678
        assertThat(settings.getSecureSettings().getSettingNames(), 
679
                  hasItems("xpack.security.authc.api_key.hashing.algorithm", 
680
                          "xpack.ssl.keystore.path"));
681
    }
682
    
683
    public void testRepositoryFailures() {
684
        // Create a mock repository with failure simulation
685
        MockRepository mockRepo = new MockRepository(
686
            new RepositoryMetadata("test-repo", "mock", Settings.EMPTY),
687
            clusterService()
688
        );
689
        
690
        // Configure to fail write operations randomly
691
        mockRepo.setFailureMode(MockRepository.FailureMode.WRITE_ONLY);
692
        
693
        // Test snapshot creation with failures
694
        try {
695
            client().admin().cluster().prepareCreateSnapshot("test-repo", "test-snapshot")
696
                .setWaitForCompletion(true)
697
                .get();
698
            fail("Expected snapshot to fail");
699
        } catch (SnapshotException e) {
700
            // Expected failure due to mock repository configuration
701
        }
702
        
703
        // Reset to normal operation
704
        mockRepo.setFailureMode(MockRepository.FailureMode.NONE);
705
    }
706
}
707
```
708

709
## Best Practices
710

711
### Transport Mocking
712
- Use specific action patterns rather than wildcards when possible
713
- Always clear transport rules in test cleanup to avoid affecting other tests
714
- Test both failure and recovery scenarios
715

716
### Storage Mocking  
717
- Configure mock settings that match your production environment
718
- Test edge cases like partial failures and timeouts
719
- Verify proper resource cleanup after mock operations
720

721
### Security Mocking
722
- Use realistic secure settings values in tests
723
- Test both successful and failed security scenarios
724
- Ensure mock security settings don't leak into other tests
725

726
### Performance Considerations
727
- Mock implementations may be slower than real implementations for some operations
728
- Use mocks judiciously - don't mock everything unnecessarily
729
- Profile test performance when using extensive mocking
730

731
The mock implementations provide comprehensive testing capabilities while maintaining isolation and enabling controlled failure simulation for robust test coverage.