or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bookkeeper-client-mocking.mdbookkeeper-server-testing.mdbookkeeper-testing-utilities.mdindex.mdzookeeper-mocking.md
tile.json

tessl/maven-org-apache-pulsar--testmocks

Mock implementations and test utilities for Apache Pulsar components including ZooKeeper and BookKeeper mocking functionality

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.pulsar/testmocks@4.0.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-pulsar--testmocks@4.0.0

index.mddocs/

Pulsar TestMocks

Mock implementations and test utilities for Apache Pulsar components, providing lightweight alternatives to ZooKeeper and BookKeeper for isolated unit testing. This library enables developers to test Pulsar-dependent code without requiring external distributed services.

Package Information

  • Package Name: testmocks
  • Group ID: org.apache.pulsar
  • Language: Java
  • Version: 4.0.6
  • Installation: Include as Maven dependency in your project
<dependency>
    <groupId>org.apache.pulsar</groupId>
    <artifactId>testmocks</artifactId>
    <version>4.0.6</version>
    <scope>test</scope>
</dependency>

Core Imports

import org.apache.zookeeper.MockZooKeeper;
import org.apache.zookeeper.MockZooKeeperSession;
import org.apache.bookkeeper.client.PulsarMockBookKeeper;
import org.apache.bookkeeper.client.BookKeeperTestClient;

Basic Usage

ZooKeeper Mocking

import org.apache.zookeeper.MockZooKeeper;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.ZooDefs;

// Create a mock ZooKeeper instance
MockZooKeeper mockZk = MockZooKeeper.newInstance();

// Use it like a real ZooKeeper client
mockZk.create("/test", "data".getBytes(), ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);
byte[] data = mockZk.getData("/test", null, null);

BookKeeper Mocking

import org.apache.bookkeeper.client.PulsarMockBookKeeper;
import org.apache.bookkeeper.client.LedgerHandle;
import org.apache.bookkeeper.client.api.DigestType;

// Create mock BookKeeper with ordered executor
PulsarMockBookKeeper mockBk = new PulsarMockBookKeeper(executor);

// Create and use ledgers
LedgerHandle ledger = mockBk.createLedger(DigestType.CRC32, "password".getBytes());
ledger.addEntry("entry data".getBytes());
ledger.close();

Architecture

The testmocks library is organized into three main packages that mirror the Apache ecosystem structure:

  • org.apache.zookeeper: Mock ZooKeeper implementations for coordination service testing

    • MockZooKeeper: Complete in-memory ZooKeeper implementation with failure injection
    • MockZooKeeperSession: Session-based wrapper for multi-client testing scenarios

  • org.apache.bookkeeper.client: Mock BookKeeper client implementations for distributed ledger testing

    • PulsarMockBookKeeper: In-memory BookKeeper client with full API support
    • PulsarMockLedgerHandle: Mock ledger handle with ReadHandle interface support
    • PulsarMockReadHandle: Separate read-only handle implementation
    • BookKeeperTestClient: Enhanced client with internal component access
    • TestStatsProvider: In-memory statistics collection and analysis

  • org.apache.bookkeeper.test: Testing utilities and server components for comprehensive BookKeeper testing

    • ServerTester: Server testing infrastructure with auto-recovery management
    • MockUncleanShutdownDetection: Shutdown lifecycle testing utilities

Key Design Patterns

Drop-in Replacement: All mock implementations extend or implement the same interfaces as their real counterparts, enabling seamless substitution in existing code.

Failure Injection: Comprehensive failure injection capabilities allow testing of error handling and recovery scenarios without complex test infrastructure.

Statistics Collection: Built-in metrics collection enables performance testing and behavior analysis without external monitoring systems.

Interceptor Pattern: Read operation interception enables advanced testing scenarios like data transformation and latency simulation.

Session Management: Session-based testing supports multi-client scenarios and isolation between test cases.

This structure enables comprehensive testing of Pulsar components without requiring external distributed services, while maintaining full API compatibility and providing enhanced testing capabilities.

Capabilities

ZooKeeper Mocking

Complete ZooKeeper API implementation with in-memory storage, session management, and configurable failure injection for testing coordination service interactions.

class MockZooKeeper extends ZooKeeper {
    static MockZooKeeper newInstance();
    static MockZooKeeper newInstance(int readOpDelayMs);
    String create(String path, byte[] data, List<ACL> acl, CreateMode createMode);
    byte[] getData(String path, Watcher watcher, Stat stat);
    List<String> getChildren(String path, Watcher watcher);
    void setData(String path, byte[] data, int version);
    void delete(String path, int version);
    void failConditional(KeeperException.Code rc, BiPredicate<Op, String> predicate);
    void setAlwaysFail(KeeperException.Code rc);
}

class MockZooKeeperSession extends ZooKeeper {
    static MockZooKeeperSession newInstance(MockZooKeeper mockZooKeeper);
    static MockZooKeeperSession newInstance(MockZooKeeper mockZooKeeper, boolean closeMockZooKeeperOnClose);
}

ZooKeeper Mocking

BookKeeper Client Mocking

In-memory BookKeeper client implementation with full ledger lifecycle management, read/write operations, and configurable testing behaviors.

class PulsarMockBookKeeper extends BookKeeper {
    PulsarMockBookKeeper(OrderedExecutor orderedExecutor);
    LedgerHandle createLedger(DigestType digestType, byte[] passwd);
    LedgerHandle createLedger(int ensSize, int writeQuorumSize, int ackQuorumSize, DigestType digestType, byte[] passwd);
    void asyncOpenLedger(long lId, DigestType digestType, byte[] passwd, OpenCallback cb, Object ctx);
    void asyncDeleteLedger(long lId, DeleteCallback cb, Object ctx);
    OpenBuilder newOpenLedgerOp();
    DeleteBuilder newDeleteLedgerOp();
    void setReadHandleInterceptor(PulsarMockReadHandleInterceptor readHandleInterceptor);
    void failAfter(int steps, int rc);
    void addEntryDelay(long delay, TimeUnit unit);
}

interface PulsarMockReadHandleInterceptor {
    CompletableFuture<LedgerEntries> interceptReadAsync(long ledgerId, long firstEntry, long lastEntry, LedgerEntries entries);
}

BookKeeper Client Mocking

BookKeeper Testing Utilities

Enhanced testing components including specialized test clients, in-memory stats providers, and server testing infrastructure for comprehensive BookKeeper testing scenarios.

class BookKeeperTestClient extends BookKeeper {
    BookKeeperTestClient(ClientConfiguration conf);
    BookKeeperTestClient(ClientConfiguration conf, TestStatsProvider statsProvider);
    ZooKeeper getZkHandle();
    BookieClient getBookieClient();
    void waitForReadOnlyBookie(BookieId id);
}

class TestStatsProvider implements StatsProvider {
    TestStatsLogger getStatsLogger(String scope);
    TestOpStatsLogger getOpStatsLogger(String path);
    TestCounter getCounter(String path);
    void forEachOpStatLogger(BiConsumer<String, TestOpStatsLogger> f);
    void clear();
}

BookKeeper Testing Utilities

BookKeeper Server Testing

Server-side testing infrastructure including server setup, auto-recovery management, and comprehensive testing utilities for integration testing scenarios.

class ServerTester {
    ServerTester(ServerConfiguration conf);
    ServerTester(ServerConfiguration conf, Bookie b);
    void startAutoRecovery();
    void stopAutoRecovery();
    Auditor getAuditor();
    ReplicationWorker getReplicationWorker();
    BookieServer getServer();
    TestStatsProvider getStatsProvider();
    BookieSocketAddress getAddress();
    void shutdown();
}

static class MockUncleanShutdownDetection implements UncleanShutdownDetection {
    void registerStartUp();
    void registerCleanShutdown();
    boolean lastShutdownWasUnclean();
    boolean getStartRegistered();
    boolean getShutdownRegistered();
}

BookKeeper Server Testing

Error Handling

All mock implementations can be configured to simulate various failure scenarios:

  • Network failures: Configurable delays and timeouts
  • Service failures: Specific error codes and exception injection
  • State transitions: Simulated connection state changes
  • Resource exhaustion: Controlled failure after specified operations

This enables comprehensive testing of error handling and recovery logic in client applications.