Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mocktools/ruby-smtp-mock

💎 Ruby SMTP mock. Mimic any 📤 SMTP server behavior for your test environment with fake SMTP server.
https://github.com/mocktools/ruby-smtp-mock

fake-server fake-smtp-server hacktoberfest mock mock-server mocktools rspec ruby ruby-gem smtp smtp-fake smtp-mail smtp-mock smtp-server testing testing-tools

Last synced: about 2 months ago
JSON representation

💎 Ruby SMTP mock. Mimic any 📤 SMTP server behavior for your test environment with fake SMTP server.

Host: GitHub
URL: https://github.com/mocktools/ruby-smtp-mock
Owner: mocktools
License: mit
Created: 2022-01-02T15:06:08.000Z (almost 3 years ago)
Default Branch: master
Last Pushed: 2024-07-16T11:59:31.000Z (5 months ago)
Last Synced: 2024-10-01T03:41:21.034Z (2 months ago)
Topics: fake-server, fake-smtp-server, hacktoberfest, mock, mock-server, mocktools, rspec, ruby, ruby-gem, smtp, smtp-fake, smtp-mail, smtp-mock, smtp-server, testing, testing-tools
Language: Ruby
Homepage:
Size: 162 KB
Stars: 65
Watchers: 2
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-rspec - ruby-smtp-mock - Mimic any SMTP server behaviour for your test environment with fake SMTP server. (Mocks)

README

        # ![Ruby SmtpMock - mimic any 📤 SMTP server behavior for your test environment with fake SMTP server](https://repository-images.githubusercontent.com/443795043/81ce5b00-0915-4dd0-93ad-88e6699e18cd)

[![Maintainability](https://api.codeclimate.com/v1/badges/315c5fff7449a11868dd/maintainability)](https://codeclimate.com/github/mocktools/ruby-smtp-mock/maintainability)

[![Test Coverage](https://api.codeclimate.com/v1/badges/315c5fff7449a11868dd/test_coverage)](https://codeclimate.com/github/mocktools/ruby-smtp-mock/test_coverage)

[![CircleCI](https://circleci.com/gh/mocktools/ruby-smtp-mock/tree/master.svg?style=svg)](https://circleci.com/gh/mocktools/ruby-smtp-mock/tree/master)

[![Gem Version](https://badge.fury.io/rb/smtp_mock.svg)](https://badge.fury.io/rb/smtp_mock)

[![Downloads](https://img.shields.io/gem/dt/smtp_mock.svg?colorA=004d99&colorB=0073e6)](https://rubygems.org/gems/smtp_mock)

[![In Awesome Ruby](https://raw.githubusercontent.com/sindresorhus/awesome/main/media/mentioned-badge.svg)](https://github.com/markets/awesome-ruby)

[![GitHub](https://img.shields.io/github/license/mocktools/ruby-smtp-mock)](LICENSE.txt)

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)

💎 Ruby SMTP mock - flexible Ruby wrapper over [`smtpmock`](https://github.com/mocktools/go-smtp-mock). Mimic any 📤 SMTP server behavior for your test environment and even more.

## Table of Contents

- [Features](#features)

- [Requirements](#requirements)

- [Installation](#installation)

- [Usage](#usage)

  - [Dependency manager](#dependency-manager)

    - [Available flags](#available-flags)

  - [DSL](#dsl)

    - [Available server options](#available-server-options)

    - [Example of usage](#example-of-usage)

  - [RSpec integration](#rspec-integration)

    - [SmtpMock RSpec helper](#smtpmock-rspec-helper)

    - [SmtpMock RSpec interface](#smtpmock-rspec-interface)

- [Contributing](#contributing)

- [License](#license)

- [Code of Conduct](#code-of-conduct)

- [Credits](#credits)

- [Versioning](#versioning)

- [Changelog](CHANGELOG.md)

## 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`:

```ruby

group :development, :test do

  gem 'smtp_mock', require: false

end

```

And then execute:

```bash

bundle

```

Or install it yourself as:

```bash

gem install smtp_mock

```

Then install [`smtpmock`](https://github.com/mocktools/go-smtp-mock) as system dependency:

```bash

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

| Flag | Description | Example of usage |

| --- | --- | --- |

| `-s`, `--sudo` | Run command as sudo | `bundle exec smtp_mock -s -i ~` |

| `-i`, `--install=PATH` | Install `smtpmock` to the existing path | `bundle exec smtp_mock -i ~/existent_dir` |

| `-u`, `--uninstall` | Uninstall `smtpmock` | `bundle exec smtp_mock -u` |

| `-g`, `--upgrade` | Upgrade to latest version of `smtpmock` | `bundle exec smtp_mock -g` |

| `-v`, `--version` | Prints current version of `smtpmock` | `bundle exec smtp_mock -v` |

| `-h`, `--help` | Prints help | `bundle exec smtp_mock -h` |

### DSL

#### Available server options

| Example of usage kwarg | Description |

| --- | --- |

| `host: '0.0.0.0'` | Host address where `smtpmock` will run. It's equal to 127.0.0.1 by default |

| `port: 2525` | Server port number. If not specified it will be assigned dynamically |

| `log: true` | Enables log server activity. Disabled by default |

| `session_timeout: 60` | Session timeout in seconds. It's equal to 30 seconds by default |

| `shutdown_timeout: 5` | Graceful shutdown timeout in seconds. It's equal to 1 second by default |

| `fail_fast: true` | Enables fail fast scenario. Disabled by default |

| `multiple_rcptto: true` | Enables multiple `RCPT TO` receiving scenario. Disabled by default |

| `multiple_message_receiving: true` | Enables multiple message receiving scenario. Disabled by default |

| `blacklisted_helo_domains: %w[a.com b.com]` | Blacklisted `HELO` domains |

| `blacklisted_mailfrom_emails: %w[[email protected] [email protected]]` | Blacklisted `MAIL FROM` emails |

| `blacklisted_rcptto_emails: %w[[email protected] [email protected]]` | blacklisted `RCPT TO` emails |

| `not_registered_emails: %w[[email protected] [email protected]]` | Not registered (non-existent) `RCPT TO` emails |

| `response_delay_helo: 2` | `HELO` response delay in seconds. It's equal to 0 seconds by default |

| `response_delay_mailfrom: 2` | `MAIL FROM` response delay in seconds. It's equal to 0 seconds by default |

| `response_delay_rcptto: 2` | `RCPT TO` response delay in seconds. It's equal to 0 seconds by default |

| `response_delay_data: 2` | `DATA` response delay in seconds. It's equal to 0 seconds by default |

| `response_delay_message: 2` | Message response delay in seconds. It's equal to 0 seconds by default |

| `response_delay_rset: 2` | `RSET` response delay in seconds. It's equal to 0 seconds by default |

| `response_delay_quit: 2` | `QUIT` response delay in seconds. It's equal to 0 seconds by default |

| `msg_size_limit: 42` | Message body size limit in bytes. It's equal to 10485760 bytes by default |

| `msg_greeting: 'Greeting message'` | Custom server greeting message |

| `msg_invalid_cmd: 'Invalid command message'` | Custom invalid command message |

| `msg_invalid_cmd_helo_sequence: 'Invalid command HELO sequence message'` | Custom invalid command `HELO` sequence message |

| `msg_invalid_cmd_helo_arg: 'Invalid command HELO argument message'` | Custom invalid command `HELO` argument message |

| `msg_helo_blacklisted_domain: 'Blacklisted domain message'` | Custom `HELO` blacklisted domain message |

| `msg_helo_received: 'HELO received message'` | Custom `HELO` received message |

| `msg_invalid_cmd_mailfrom_sequence: 'Invalid command MAIL FROM sequence message'` | Custom invalid command `MAIL FROM` sequence message |

| `msg_invalid_cmd_mailfrom_arg: 'Invalid command MAIL FROM argument message'` | Custom invalid command `MAIL FROM` argument message |

| `msg_mailfrom_blacklisted_email: 'Blacklisted email message'` | Custom `MAIL FROM` blacklisted email message |

| `msg_mailfrom_received: 'MAIL FROM received message'` | Custom `MAIL FROM` received message |

| `msg_invalid_cmd_rcptto_sequence: 'Invalid command RCPT TO sequence message'` | Custom invalid command `RCPT TO` sequence message |

| `msg_invalid_cmd_rcptto_arg: 'Invalid command RCPT TO argument message'` | Custom invalid command `RCPT TO` argument message |

| `msg_rcptto_not_registered_email: 'Not registered email message'` | Custom `RCPT TO` not registered email message |

| `msg_rcptto_blacklisted_email: 'Blacklisted email message'` | Custom `RCPT TO` blacklisted email message |

| `msg_rcptto_received: 'RCPT TO received message'` | Custom `RCPT TO` received message |

| `msg_invalid_cmd_data_sequence: 'Invalid command DATA sequence message'` | Custom invalid command `DATA` sequence message |

| `msg_data_received: 'DATA received message'` | Custom `DATA` received message |

| `msg_msg_size_is_too_big: 'Message size is too big'` | Custom size is too big message |

| `msg_invalid_cmd_rset_sequence: 'Invalid command RSET sequence message'` | Custom invalid command `RSET` sequence message |

| `msg_invalid_cmd_rset_arg: 'Invalid command RSET argument message'` | Custom invalid command `RSET` argument message |

| `msg_rset_received: 'RSET received message'` | Custom `RSET` received message |

| `msg_quit_cmd: 'Quit command message'` | Custom quit command message |

#### Example of usage

```ruby

# 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:

```ruby

# Gemfile

group :test do

  gem 'rspec'

  gem 'smtp_mock', require: 'smtp_mock/test_framework/rspec'

end

```

or

```ruby

# 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:

```ruby

# spec/support/config/smtp_mock.rb

RSpec.configure do |config|

  config.include SmtpMock::TestFramework::RSpec::Helper

end

```

```ruby

# 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:

```ruby

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 . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. Please check the [open tickets](https://github.com/mocktools/ruby-smtp-mock/issues). Be sure to follow Contributor Code of Conduct below and our [Contributing Guidelines](CONTRIBUTING.md).

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## 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](CODE_OF_CONDUCT.md).

## Credits

- [The Contributors](https://github.com/mocktools/ruby-smtp-mock/graphs/contributors) for code and awesome suggestions

- [The Stargazers](https://github.com/mocktools/ruby-smtp-mock/stargazers) for showing their support

## Versioning

SmtpMock uses [Semantic Versioning 2.0.0](https://semver.org)