Generate email list automatically with automaildoc

Hello, diligent developers who manage systems to send emails to somewhere. In this article, I'd like to introduce a Ruby gem named automaildoc, which generates mail list from RSpec automatically.

How to use

After installing the gem, run AUTOMAILDOC = 1 rspec from the command line to generate HTML to list the mail. Easy!

Let me elaborate a bit for beginners.

Add this line to your application's Gemfile:

gem 'automaildoc', group: :test

And then execute:

$ bundle

Add an automaildoc tag to your mail spec. (Don't you have it? Then it's an exact chance to write them right now!)

RSpec.describe 'Sign up mail', automaildoc: true do
  let!(:user) { create(:user) }
  let!(:mail) { SignupMailer.mail(user) }

  it 'should send to a user' do
    expect(mail.to).to eq user
  end
end

Run Rspec test with AUTOMAILDOC=1.

$ AUTOMAILDOC=1 bundle exec rspec

That's it. Then automaildoc generates an HTML file to ./doc/mails. The file should be what you've wanted.

Background of automaildoc

Have you received such inquiries from stakeholders like product managers, a business side, customer support, etc.?

"May I confirm emails sent from our system for legal/brand check?"

"Can you show the text of a similar past email to think of the sentence of the newly sent email?"

Then developers respond each time by checking code or I18n translation files. I have experienced such a situation many times.

However, due to the A/B test and CS request, a content of an email is frequently updated. A total number of emails will increase or decrease without noticing during daily development. Besides, there is also a problem that even if the mail is same, it varies depending on the context or condition. I finally found the task repeatable, annoying, and not more comfortable than I'd expect.

As a solution to this problem, my colleague gave me an idea that it would be convenient to generate from RSpec automatically like autodoc. After that, when I received a request like "I want to see email list" again, then I remembered this and tried it with great force.

I hope this article and gem would be helpful for you too.