Module: Servus::Testing::ExampleBuilders

Defined in:
lib/servus/testing/example_builders.rb

Overview

Provides helper methods for extracting example values from service schemas.

This module is designed to be included in test files (RSpec, Minitest, etc.) to provide convenient access to schema example values. It’s particularly useful for generating test fixtures without manually maintaining separate factory files.

The ‘servus_` prefix on method names prevents naming collisions with other testing libraries and makes it clear these are Servus-specific helpers.

Examples:

Include in RSpec

# spec/spec_helper.rb
require 'servus/testing/example_builders'

RSpec.configure do |config|
  config.include Servus::Testing::ExampleBuilders
end

Include in Rails console (development)

# config/environments/development.rb
config.to_prepare do
  require 'servus/testing/example_builders'

  if defined?(Rails::Console)
    include Servus::Testing::ExampleBuilders
  end
end

Use in tests

RSpec.describe ProcessPayment::Service do
  it 'processes payment successfully' do
    args = servus_arguments_example(ProcessPayment::Service, amount: 50.0)
    result = ProcessPayment::Service.call(**args)

    expect(result).to be_success
  end
end

Instance Method Summary collapse

Instance Method Details

#servus_arguments_example(service_class, overrides = {}) ⇒ Hash<Symbol, Object>

Note:

Override keys can be strings or symbols; they’ll be converted to symbols

Note:

Returns empty hash if service has no arguments schema defined

Extracts example argument values from a service’s schema.

Looks for ‘example` or `examples` keywords in the service’s arguments schema and returns them as a hash ready to be passed to the service’s ‘.call` method.

Examples:

Basic usage

args = servus_arguments_example(ProcessPayment::Service)
# => { user_id: 123, amount: 100.0, currency: 'USD' }

result = ProcessPayment::Service.call(**args)

With overrides

args = servus_arguments_example(ProcessPayment::Service, amount: 50.0, currency: 'EUR')
# => { user_id: 123, amount: 50.0, currency: 'EUR' }

In RSpec tests

it 'processes different currencies' do
  %w[USD EUR GBP].each do |currency|
    result = ProcessPayment::Service.call(
      **servus_arguments_example(ProcessPayment::Service, currency: currency)
    )
    expect(result).to be_success
  end
end

Parameters:

  • service_class (Class) —

    The service class to extract examples from

  • overrides (Hash) (defaults to: {}) —

    Optional values to override the schema examples

Returns:

  • (Hash<Symbol, Object>) —

    Hash of example argument values with symbolized keys



75
76
77
 
# File 'lib/servus/testing/example_builders.rb', line 75

def servus_arguments_example(service_class, overrides = {})
  extract_example_from(service_class, :arguments, overrides)
end

#servus_failure_example(service_class, overrides = {}) ⇒ Servus::Support::Response

Note:

Override keys can be strings or symbols; they’ll be converted to symbols

Note:

Returns empty hash if service has no failure schema defined

Extracts example failure data values from a service’s schema.

Looks for ‘example` or `examples` keywords in the service’s failure schema and returns them wrapped in a failure Response. Useful for validating failure response structure in tests.

Examples:

Basic usage

expected = servus_failure_example(ProcessPayment::Service)
# => Servus::Support::Response with failure? == true, data:
#    { reason: 'card_declined', decline_code: 'insufficient_funds' }

Parameters:

  • service_class (Class) —

    The service class to extract examples from

  • overrides (Hash) (defaults to: {}) —

    Optional values to override the schema examples

Returns:



136
137
138
139
 
# File 'lib/servus/testing/example_builders.rb', line 136

def servus_failure_example(service_class, overrides = {})
  example = extract_example_from(service_class, :failure, overrides)
  Servus::Support::Response.new(false, example, Servus::Support::Errors::ServiceError.new)
end

#servus_failure_response(message = nil, data: nil, type: Servus::Support::Errors::ServiceError) ⇒ Servus::Support::Response

Builds a failure Response object with the given message and error type.

Convenience method for creating failure responses in tests. Mirrors the signature of Base#failure.

Examples:

Basic usage

response = servus_failure_response("Insufficient funds")
response.failure?      # => true
response.error.message # => "Insufficient funds"

With custom error type

response = servus_failure_response("Not found", type: Servus::Support::Errors::NotFoundError)
response.error.http_status # => :not_found

With structured failure data

response = servus_failure_response("Failed", data: { reason: "expired" })
response.data[:reason] # => "expired"

Parameters:

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

    the error message (uses error type’s default if nil)

  • data (Hash, nil) (defaults to: nil) —

    optional structured data to include with the failure

  • type (Class) (defaults to: Servus::Support::Errors::ServiceError) —

    the error class to use (default: ServiceError)

Returns:

See Also:



188
189
190
191
 
# File 'lib/servus/testing/example_builders.rb', line 188

def servus_failure_response(message = nil, data: nil, type: Servus::Support::Errors::ServiceError)
  error = type.new(message)
  Servus::Support::Response.new(false, data, error)
end

#servus_result_example(service_class, overrides = {}) ⇒ Servus::Support::Response

Note:

Override keys can be strings or symbols; they’ll be converted to symbols

Note:

Returns empty hash if service has no result schema defined

Extracts example result values from a service’s schema.

Looks for ‘example` or `examples` keywords in the service’s result schema and returns them as a hash. Useful for validating service response structure and expected data shapes in tests.

Examples:

Basic usage

expected = servus_result_example(ProcessPayment::Service)
# => Servus::Support::Response with data:
#    { transaction_id: 'txn_abc123', status: 'approved', amount_charged: 100.0 }

Validate result structure

result = ProcessPayment::Service.call(**servus_arguments_example(ProcessPayment::Service))

expect(result.data).to match(
  hash_including(servus_result_example(ProcessPayment::Service).data)
)

Check result has expected keys

result = ProcessPayment::Service.call(**args)
expected_keys = servus_result_example(ProcessPayment::Service).data.keys

expect(result.data.keys).to match_array(expected_keys)

With overrides

expected = servus_result_example(ProcessPayment::Service, status: 'pending').data
# => { transaction_id: 'txn_abc123', status: 'pending', amount_charged: 100.0 }

Parameters:

  • service_class (Class) —

    The service class to extract examples from

  • overrides (Hash) (defaults to: {}) —

    Optional values to override the schema examples

Returns:



113
114
115
116
117
 
# File 'lib/servus/testing/example_builders.rb', line 113

def servus_result_example(service_class, overrides = {})
  example = extract_example_from(service_class, :result, overrides)
  # Wrap in a successful Response object
  Servus::Support::Response.new(true, example, nil)
end

#servus_success_response(data = {}) ⇒ Servus::Support::Response

Builds a successful Response object with the given data.

Convenience method for creating successful responses in tests without calling Servus::Support::Response.new directly.

Examples:

Basic usage

response = servus_success_response(transferred: 50)
response.success?           # => true
response.data[:transferred] # => 50

Stubbing a service call

allow(TransferService).to receive(:call).and_return(
  servus_success_response(transferred: 50)
)

Parameters:

  • data (Hash) (defaults to: {}) —

    the success data to wrap in the response

Returns:

See Also:



160
161
162
 
# File 'lib/servus/testing/example_builders.rb', line 160

def servus_success_response(data = {})
  Servus::Support::Response.new(true, data, nil)
end