Module: Rdkafka::Testing

Defined in:
lib/rdkafka/producer/testing.rb

Overview

Testing utilities for Producer instances. This module is NOT included by default and should only be used in test environments.

This module provides librdkafka native testing utilities that are needed to trigger certain behaviours that are hard to reproduce in stable environments, particularly fatal error scenarios in idempotent and transactional producers.

To use in tests for producers: producer.singleton_class.include(Rdkafka::Testing)

Or include it for all producers in your test suite: Rdkafka::Producer.include(Rdkafka::Testing)

IMPORTANT: Fatal errors leave the producer client in an unusable state. After triggering a fatal error, the producer should be closed and discarded. Do not attempt to reuse a producer that has experienced a fatal error.

Instance Method Summary collapse

Instance Method Details

#fatal_error ⇒ Hash?

Checks if a fatal error has occurred and retrieves error details. Calls rd_kafka_fatal_error to get the actual fatal error code and message.

Examples:

if fatal_error = producer.fatal_error
  puts "Fatal error #{fatal_error[:error_code]}: #{fatal_error[:error_string]}"
end

Returns:

  • (Hash, nil) —

    Hash with :error_code and :error_string if fatal error occurred, nil otherwise



45
46
47
48
49
 
# File 'lib/rdkafka/producer/testing.rb', line 45

def fatal_error
  @native_kafka.with_inner do |inner|
    Rdkafka::Bindings.extract_fatal_error(inner)
  end
end

#trigger_test_fatal_error(error_code, reason) ⇒ Integer

Triggers a test fatal error using rd_kafka_test_fatal_error. This is useful for testing fatal error handling without needing actual broker issues.

Examples:

producer.trigger_test_fatal_error(47, "Test producer fencing")

Parameters:

  • error_code (Integer) —

    The error code to trigger (e.g., 47 for invalid_producer_epoch)

  • reason (String) —

    Descriptive reason for the error

Returns:

  • (Integer) —

    Result code from rd_kafka_test_fatal_error (0 on success)



30
31
32
33
34
 
# File 'lib/rdkafka/producer/testing.rb', line 30

def trigger_test_fatal_error(error_code, reason)
  @native_kafka.with_inner do |inner|
    Rdkafka::Bindings.rd_kafka_test_fatal_error(inner, error_code, reason)
  end
end