💎 Ruby SMTP mock - flexible Ruby wrapper over smtpmock. Mimic any 📤 SMTP server behavior for your test environment and even more.

Table of Contents

• Features
• Requirements
• Installation
• Usage
  • Dependency manager
    • Available flags
  • DSL
    • Available server options
    • Example of usage
  • RSpec integration
    • SmtpMock RSpec helper
    • SmtpMock RSpec interface
• Contributing
• License
• Code of Conduct
• Credits
• Versioning
• Changelog

Features

• Ability to handle configurable behavior and life cycles of SMTP mock server(s)
• Dynamic/manual port assignment
• Test framework agnostic (it's PORO, so you can use it outside of RSpec, Test::Unit or MiniTest)
• Simple and intuitive DSL
• RSpec integration out of the box
• Includes easy system dependency manager

Requirements

Ruby MRI 2.5.0+

Installation

Add this line to your application's Gemfile:

group :development, :test do
  gem 'smtp_mock', require: false
end

And then execute:

bundle

Or install it yourself as:

gem install smtp_mock

Then install smtpmock as system dependency:

bundle exec smtp_mock -i ~

Usage

Dependency manager

This gem includes easy system dependency manager. Run bundle exec smtp_mock with options for manage smtpmock system dependency.

Available flags

DSL

Available server options

Example of usage

# Public SmtpMock interface
# Without kwargs creates SMTP mock server with default behavior.
# A free port for server will be randomly assigned in the range
# from 49152 to 65535. Returns current smtp mock server instance
smtp_mock_server = SmtpMock.start_server(not_registered_emails: %w[[email protected]]) # => SmtpMock::Server instance

# returns current smtp mock server port
smtp_mock_server.port # => 55640

# returns current smtp mock server process identification number (PID)
smtp_mock_server.pid # => 38195

# returns current smtp mock server version
smtp_mock_server.version # => '1.5.2'

# interface for graceful shutdown current smtp mock server
smtp_mock_server.stop # => true

# interface for force shutdown current smtp mock server
smtp_mock_server.stop! # => true

# interface to check state of current smtp mock server
# returns true if server is running, otherwise returns false
smtp_mock_server.active? # => true

# returns list of running smtp mock servers
SmtpMock.running_servers # => [SmtpMock::Server instance]

# interface to stop all running smtp mock servers
SmtpMock.stop_running_servers! # => true

RSpec integration

Require this either in your Gemfile or in RSpec's support scripts. So either:

# Gemfile

group :test do
  gem 'rspec'
  gem 'smtp_mock', require: 'smtp_mock/test_framework/rspec'
end

or

# spec/support/config/smtp_mock.rb

require 'smtp_mock/test_framework/rspec'

SmtpMock RSpec helper

Just add SmtpMock::TestFramework::RSpec::Helper if you wanna use shortcut smtp_mock_server for SmtpMock server instance inside of your RSpec.describe blocks:

# spec/support/config/smtp_mock.rb

RSpec.configure do |config|
  config.include SmtpMock::TestFramework::RSpec::Helper
end

# your awesome smtp_client_spec.rb

RSpec.describe SmtpClient do
  subject(:smtp_response) do
    described_class.call(
      host: 'localhost',
      port: smtp_mock_server.port,
      mailfrom: mailfrom,
      rcptto: rcptto,
      message: message
    )
  end

  let(:mailfrom) { '[email protected]' }
  let(:rcptto) { '[email protected]' }
  let(:message) { 'Email message context' }
  let(:expected_response_message) { '250 Custom successful response' }

  before { smtp_mock_server(msg_msg_received: expected_response_message) }

  it do
    expect(smtp_response).to be_success
    expect(smtp_response).to have_status(expected_response_status)
    expect(smtp_response).to have_message_context(expected_response_message)
  end
end

SmtpMock RSpec interface

If you won't use SmtpMock::TestFramework::RSpec::Helper you can use SmtpMock::TestFramework::RSpec::Interface directly instead:

SmtpMock::TestFramework::RSpec::Interface.start_server  # creates and runs SmtpMock server instance
SmtpMock::TestFramework::RSpec::Interface.stop_server!  # stops and clears current SmtpMock server instance
SmtpMock::TestFramework::RSpec::Interface.clear_server! # clears current SmtpMock server instance

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mocktools/ruby-smtp-mock. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. Please check the open tickets. Be sure to follow Contributor Code of Conduct below and our Contributing Guidelines.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the SmtpMock project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Credits

• The Contributors for code and awesome suggestions
• The Stargazers for showing their support

Versioning

SmtpMock uses Semantic Versioning 2.0.0