Module: JetstreamBridge::TestHelpers

Defined in:
lib/jetstream_bridge/test_helpers.rb,
lib/jetstream_bridge/test_helpers/fixtures.rb,
lib/jetstream_bridge/test_helpers/matchers.rb,
lib/jetstream_bridge/test_helpers/mock_nats.rb,
lib/jetstream_bridge/test_helpers/integration_helpers.rb

Overview

Test helpers for easier testing of JetStream Bridge integrations

Examples:

RSpec configuration

require 'jetstream_bridge/test_helpers'

RSpec.configure do |config|
  config.include JetstreamBridge::TestHelpers

  config.before(:each, :jetstream) do
    JetstreamBridge::TestHelpers.enable_test_mode!
  end

  config.after(:each, :jetstream) do
    JetstreamBridge::TestHelpers.reset_test_mode!
  end
end

Using in tests

RSpec.describe UserService, :jetstream do
  it "publishes user created event" do
    service.create_user(name: "Ada")

    expect(JetstreamBridge).to have_published(
      event_type: "user.created",
      payload: hash_including(name: "Ada")
    )
  end
end

Defined Under Namespace

Modules: Fixtures, IntegrationHelpers, Matchers, MockNats

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.mock_connection ⇒ MockNats::MockConnection? (readonly)

Get the current mock connection

Returns:



125
126
127
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 125

def mock_connection
  @mock_connection
end

Class Method Details

.auto_configure! ⇒ void

This method returns an undefined value.

Auto-configure test helpers when RSpec is detected

This method is called automatically when test_helpers.rb is required. It sets up RSpec configuration to enable test mode for tests tagged with :jetstream.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 47

def auto_configure!
  return unless defined?(RSpec)
  return if @configured

  RSpec.configure do |config|
    config.include JetstreamBridge::TestHelpers
    config.include JetstreamBridge::TestHelpers::Matchers

    config.before(:each, :jetstream) do
      JetstreamBridge::TestHelpers.enable_test_mode!
    end

    config.after(:each, :jetstream) do
      JetstreamBridge::TestHelpers.reset_test_mode!
    end
  end

  @configured = true
end

.build_jetstream_event(event_type:, payload:, event_id: nil, trace_id: nil, occurred_at: nil, **metadata) ⇒ Models::Event

Build a test Event object

Examples:

event = build_jetstream_event(
  event_type: "user.created",
  payload: { id: 1, email: "[email protected]" }
)
handler.call(event)

Parameters:

  • event_type (String) —

    Event type (e.g., “user.created”)

  • payload (Hash) —

    Event payload

  • event_id (String, nil) (defaults to: nil) —

    Optional event ID

  • trace_id (String, nil) (defaults to: nil) —

    Optional trace ID

  • occurred_at (Time, String, nil) (defaults to: nil) —

    Optional timestamp

  • metadata (Hash) —

    Optional metadata

Returns:



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 191

def build_jetstream_event(event_type:, payload:, event_id: nil, trace_id: nil, occurred_at: nil, **metadata)
  event_hash = {
    'event_id' => event_id || SecureRandom.uuid,
    'schema_version' => 1,
    'event_type' => event_type,
    'producer' => 'test',
    'resource_id' => (payload['id'] || payload[:id] || '').to_s,
    'occurred_at' => (occurred_at || Time.now.utc).iso8601,
    'trace_id' => trace_id || SecureRandom.hex(8),
    'resource_type' => event_type.split('.').first || 'event',
    'payload' => payload
  }

  Models::Event.new(
    event_hash,
    metadata: {
      subject: metadata[:subject] || 'test.subject',
      deliveries: metadata[:deliveries] || 1,
      stream: metadata[:stream] || 'test-stream',
      sequence: metadata[:sequence] || 1,
      consumer: metadata[:consumer] || 'test-consumer',
      timestamp: Time.now
    }
  )
end

.configured? ⇒ Boolean

Check if auto-configuration has been applied

Returns:

  • (Boolean) 


70
71
72
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 70

def configured?
  @configured ||= false
end

.consumed_events ⇒ Array<Hash>

Get all consumed events captured in test mode

Returns:

  • (Array<Hash>) —

    Array of consumed event hashes



151
152
153
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 151

def consumed_events
  @consumed_events ||= []
end

.enable_test_mode!(use_mock_nats: true) ⇒ void

This method returns an undefined value.

Enable test mode with in-memory event capture and mock NATS connection

Parameters:

  • use_mock_nats (Boolean) (defaults to: true) —

    Whether to use mock NATS connection (default: true)



78
79
80
81
82
83
84
85
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 78

def enable_test_mode!(use_mock_nats: true)
  @test_mode = true
  @published_events = []
  @consumed_events = []
  @mock_nats_enabled = use_mock_nats

  setup_mock_nats if use_mock_nats
end

.mock_storage ⇒ MockNats::InMemoryStorage

Get the mock storage for direct access in tests

Returns:



130
131
132
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 130

def mock_storage
  MockNats.storage
end

.published_events ⇒ Array<Hash>

Get all published events captured in test mode

Returns:

  • (Array<Hash>) —

    Array of published event hashes



144
145
146
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 144

def published_events
  @published_events ||= []
end

.record_consumed_event(event) ⇒ void

This method returns an undefined value.

Record a consumed event (called internally)

Parameters:

  • event (Hash) —

    Event data



168
169
170
171
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 168

def record_consumed_event(event)
  @consumed_events ||= []
  @consumed_events << event.dup
end

.record_published_event(event) ⇒ void

This method returns an undefined value.

Record a published event (called internally)

Parameters:

  • event (Hash) —

    Event data



159
160
161
162
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 159

def record_published_event(event)
  @published_events ||= []
  @published_events << event.dup
end

.reset_test_mode! ⇒ void

This method returns an undefined value.

Reset test mode and clear captured events



90
91
92
93
94
95
96
97
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 90

def reset_test_mode!
  @test_mode = false
  @published_events = []
  @consumed_events = []

  teardown_mock_nats if @mock_nats_enabled
  @mock_nats_enabled = false
end

.setup_mock_nats ⇒ void

This method returns an undefined value.

Setup mock NATS connection



102
103
104
105
106
107
108
109
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 102

def setup_mock_nats
  MockNats.reset!
  @mock_connection = MockNats.create_mock_connection
  @mock_connection.connect

  # Store the mock for Connection to use
  JetstreamBridge.instance_variable_set(:@mock_nats_client, @mock_connection)
end

.teardown_mock_nats ⇒ void

This method returns an undefined value.

Teardown mock NATS connection



114
115
116
117
118
119
120
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 114

def teardown_mock_nats
  MockNats.reset!
  @mock_connection = nil
  return unless JetstreamBridge.instance_variable_defined?(:@mock_nats_client)

  JetstreamBridge.remove_instance_variable(:@mock_nats_client)
end

.test_mode? ⇒ Boolean

Check if test mode is enabled

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 137

def test_mode?
  @test_mode ||= false
end

Instance Method Details

#trigger_jetstream_event(event, handler = nil) ⇒ void

This method returns an undefined value.

Simulate triggering an event to a consumer

Examples:

event = build_jetstream_event(event_type: "user.created", payload: { id: 1 })
trigger_jetstream_event(event, ->(e) { process_event(e) })

Parameters:

  • event (Models::Event, Hash) —

    Event to trigger

  • handler (Proc, #call) (defaults to: nil) —

    Handler to call with event

Raises:

  • (ArgumentError) 


228
229
230
231
232
233
234
 
# File 'lib/jetstream_bridge/test_helpers.rb', line 228

def trigger_jetstream_event(event, handler = nil)
  handler ||= @handler if defined?(@handler)
  raise ArgumentError, 'handler is required' unless handler

  TestHelpers.record_consumed_event(event.to_h) if TestHelpers.test_mode?
  handler.call(event)
end