email_spec 0.2.0

data/lib/email-spec.rb

@@ -0,0 +1 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'email_spec'))

data/lib/email_spec.rb

@@ -0,0 +1,14 @@
+unless defined?(ActionMailer)
+  Kernel.warn("ActionMailer did not appear to be loaded so email-spec is requiring it.")
+  require 'actionmailer'
+end
+
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__))) unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'email_spec/deliveries'
+require 'email_spec/address_converter'
+require 'email_spec/email_viewer'
+require 'email_spec/helpers'
+require 'email_spec/matchers'
+
+

data/lib/email_spec/address_converter.rb

@@ -0,0 +1,27 @@
+module EmailSpec
+  class AddressConverter
+    include Singleton
+  
+    attr_accessor :converter
+  
+    # The block provided to conversion should convert to an email
+    # address string or return the input untouched. For example:
+    #
+    #  EmailSpec::AddressConverter.instance.conversion do |input|
+    #   if input.is_a?(User)
+    #     input.email
+    #   else
+    #     input
+    #   end
+    #  end
+    #    
+    def conversion(&block)
+      self.converter = block
+    end
+  
+    def convert(input)
+      return input unless converter
+      converter.call(input)
+    end
+  end
+end

data/lib/email_spec/cucumber.rb

@@ -0,0 +1,19 @@
+# require this in your env.rb file after you require cucumber/rails/world
+
+# Global Setup
+ActionMailer::Base.delivery_method = :test unless ActionMailer::Base.delivery_method == :activerecord
+ActionMailer::Base.perform_deliveries = true
+
+Before do
+  # Scenario setup
+  ActionMailer::Base.deliveries.clear if ActionMailer::Base.delivery_method == :test
+end
+
+After do
+  EmailSpec::EmailViewer.save_and_open_all_raw_emails if ENV['SHOW_EMAILS']
+  EmailSpec::EmailViewer.save_and_open_all_html_emails if ENV['SHOW_HTML_EMAILS']
+  EmailSpec::EmailViewer.save_and_open_all_text_emails if ENV['SHOW_TEXT_EMAILS']
+end
+
+World(EmailSpec::Helpers)
+World(EmailSpec::Matchers)

data/lib/email_spec/deliveries.rb

@@ -0,0 +1,55 @@
+module EmailSpec
+  module TestDeliveries
+    def all_emails
+      ActionMailer::Base.deliveries
+    end
+    
+    def last_email_sent
+      ActionMailer::Base.deliveries.last || raise("No email has been sent!")
+    end
+
+    def reset_mailer
+      ActionMailer::Base.deliveries.clear
+    end
+    
+    def mailbox_for(address)
+      address = AddressConverter.instance.convert(address)
+      ActionMailer::Base.deliveries.select { |m| m.to.include?(address) }
+    end
+  end
+  
+  module ARMailerDeliveries
+    def all_emails
+      Email.all.map{ |email| parse_to_tmail(email) }
+    end
+    
+    def last_email_sent
+      if email = Email.last
+        TMail::Mail.parse(email.mail)
+      else
+        raise("No email has been sent!")
+      end
+    end
+
+    def reset_mailer
+      Email.delete_all
+    end
+    
+    def mailbox_for(address)
+      address = AddressConverter.instance.convert(address)
+      Email.all.select { |email| email.to.include?(address) }.map{ |email| parse_to_tmail(email) }
+    end
+    
+    def parse_to_tmail(email)
+      TMail::Mail.parse(email.mail)
+    end    
+  end
+  
+  module Deliveries
+    if ActionMailer::Base.delivery_method == :activerecord
+      include EmailSpec::ARMailerDeliveries
+    else
+      include EmailSpec::TestDeliveries
+    end    
+  end
+end

data/lib/email_spec/email_viewer.rb

@@ -0,0 +1,70 @@
+module EmailSpec
+  class EmailViewer
+    extend Deliveries
+    
+    def self.save_and_open_all_raw_emails
+      filename = "#{RAILS_ROOT}/tmp/email-#{Time.now.to_i}.txt"
+
+      File.open(filename, "w") do |f|
+        all_emails.each do |m|
+          f.write m.to_s
+          f.write "\n" + '='*80 + "\n"
+        end
+      end
+
+      open_in_text_editor(filename)
+    end
+
+    def self.save_and_open_all_html_emails
+      all_emails.each_with_index do |m, index|
+        if m.multipart? && html_part = m.parts.detect{ |p| p.content_type == 'text/html' }
+          filename = tmp_email_filename("-#{index}.html")
+          File.open(filename, "w") do |f|
+            f.write m.parts[1].body
+          end
+          open_in_browser(filename)
+        end
+      end
+    end
+
+    def self.save_and_open_all_text_emails
+      filename = tmp_email_filename
+
+      File.open(filename, "w") do |f|
+        all_emails.each do |m|
+          if m.multipart? && text_part = m.parts.detect{ |p| p.content_type == 'text/plain' }
+            m.ordered_each{|k,v| f.write "#{k}: #{v}\n" }
+            f.write text_part.body
+          else
+            f.write m.to_s
+          end
+          f.write "\n" + '='*80 + "\n"
+        end
+      end
+
+      open_in_text_editor(filename)
+    end
+  
+    def self.save_and_open_email(mail)
+      filename = "#{RAILS_ROOT}/tmp/email-#{Time.now.to_i}.txt"
+
+      File.open(filename, "w") do |f|
+        f.write mail.to_s
+      end
+
+      open_in_text_editor(filename)
+    end
+    
+    def self.open_in_text_editor(filename)
+      `mate #{filename}`
+    end
+    
+    def self.open_in_browser(filename)
+      `open #{filename}`
+    end
+    
+    def self.tmp_email_filename(extension = '.txt')
+      "#{RAILS_ROOT}/tmp/email-#{Time.now.to_i}#{extension}"
+    end
+  end
+end

data/lib/email_spec/helpers.rb

@@ -0,0 +1,129 @@
+require 'uri'
+require 'email_spec/deliveries'
+
+module EmailSpec
+
+  module Helpers
+    include Deliveries
+    
+    def visit_in_email(link_text)
+      visit(parse_email_for_link(current_email, link_text))
+    end
+    
+    def click_email_link_matching(regex, email = current_email)
+      url = links_in_email(email).detect { |link| link =~ regex }
+      raise "No link found matching #{regex.inspect} in #{email.body}" unless url
+      request_uri = URI::parse(url).request_uri
+      visit request_uri
+    end
+    
+    def click_first_link_in_email(email = current_email)
+      link = links_in_email(email).first
+      request_uri = URI::parse(link).request_uri
+      visit request_uri
+    end
+    
+    def open_email(address, opts={})
+      address = convert_address(address)
+      set_current_email(find_email!(address, opts))
+    end
+    
+    alias_method :open_email_for, :open_email
+
+    def open_last_email
+      set_current_email(last_email_sent)
+    end
+
+    def open_last_email_for(address)
+      address = convert_address(address)
+      set_current_email(mailbox_for(address).last)
+    end
+    
+    def current_email(address=nil)
+      address = convert_address(address)
+      email = address ? email_spec_hash[:current_emails][address] : email_spec_hash[:current_email]
+      raise Spec::Expectations::ExpectationNotMetError, "Expected an open email but none was found. Did you forget to call open_email?" unless email  
+      email
+    end
+    
+    def unread_emails_for(address)
+      address = convert_address(address)
+      mailbox_for(address) - read_emails_for(address)
+    end
+    
+    def read_emails_for(address)
+      address = convert_address(address)
+      email_spec_hash[:read_emails][address] ||= []
+    end
+    
+    def find_email(address, opts={})
+      address = convert_address(address)
+     if opts[:with_subject]
+        email = mailbox_for(address).find { |m| m.subject =~ Regexp.new(opts[:with_subject]) }
+      elsif opts[:with_text]
+        email = mailbox_for(address).find { |m| m.body =~ Regexp.new(opts[:with_text]) }
+      else
+        email = mailbox_for(address).first
+      end
+    end
+    
+    def links_in_email(email)
+      URI.extract(email.body, ['http', 'https'])
+    end
+
+    private
+
+    def email_spec_hash
+      @email_spec_hash ||= {:read_emails => {}, :unread_emails => {}, :current_emails => {}, :current_email => nil}
+    end
+
+    def find_email!(address, opts={})
+      address = convert_address(address)
+      email = find_email(address, opts)
+      if email.nil?
+        error = "#{opts.keys.first.to_s.humanize unless opts.empty?} #{('"' + opts.values.first.to_s.humanize + '"') unless opts.empty?}"
+        raise Spec::Expectations::ExpectationNotMetError, "Could not find email #{error}. \n Found the following emails:\n\n #{all_emails.to_s}"
+       end
+      email
+    end
+
+    def set_current_email(email)
+      return unless email
+      email.to.each do |to|
+        read_emails_for(to) << email      
+        email_spec_hash[:current_emails][to] = email
+      end
+      email_spec_hash[:current_email] = email
+    end
+        
+    def parse_email_for_link(email, text_or_regex)
+      email.should have_body_text(text_or_regex)
+      
+      url = parse_email_for_explicit_link(email, text_or_regex) 
+      url ||= parse_email_for_anchor_text_link(email, text_or_regex)
+
+      raise "No link found matching #{text_or_regex.inspect} in #{email}" unless url
+      url
+    end
+    
+    # e.g. confirm in http://confirm
+    def parse_email_for_explicit_link(email, regex)
+      regex = /#{Regexp.escape(regex)}/ unless regex.is_a?(Regexp)
+      url = links_in_email(email).detect { |link| link =~ regex }
+      URI::parse(url).request_uri if url
+    end
+    
+    # e.g. Click here in  <a href="http://confirm">Click here</a>
+    def parse_email_for_anchor_text_link(email, link_text)
+      email.body =~ %r{<a[^>]*href=['"]?([^'"]*)['"]?[^>]*?>[^<]*?#{link_text}[^<]*?</a>}
+      URI.split($~[1])[5..-1].compact!.join("?").gsub("&amp;", "&")
+      # sub correct ampersand after rails switches it (http://dev.rubyonrails.org/ticket/4002) 
+    end
+
+    
+    def convert_address(address)
+      AddressConverter.instance.convert(address)
+    end
+  end
+end
+

data/lib/email_spec/matchers.rb

@@ -0,0 +1,122 @@
+module EmailSpec
+
+    module Matchers
+
+    class DeliverTo
+
+      def initialize(expected_email_addresses_or_objects_that_respond_to_email)
+        emails = expected_email_addresses_or_objects_that_respond_to_email.map do |email_or_object|
+          email_or_object.kind_of?(String) ? email_or_object : email_or_object.email
+        end
+
+        @expected_email_addresses = emails.sort
+      end
+
+      def description
+        "be delivered to #{@expected_email_addresses.inspect}"
+      end
+
+      def matches?(email)
+        @email = email
+        @actual_recipients = (email.to || []).sort
+        @actual_recipients == @expected_email_addresses
+      end
+
+      def failure_message
+        "expected #{@email.inspect} to deliver to #{@expected_email_addresses.inspect}, but it delievered to #{@actual_recipients.inspect}"
+      end
+
+      def negative_failure_message
+        "expected #{@email.inspect} not to deliver to #{@expected_email_addresses.inspect}, but it did"
+      end
+    end
+
+    def deliver_to(*expected_email_addresses_or_objects_that_respond_to_email)
+      DeliverTo.new(expected_email_addresses_or_objects_that_respond_to_email.flatten)
+    end
+
+    alias :be_delivered_to :deliver_to
+
+    def have_subject(expected)
+      simple_matcher do |given, matcher|
+        given_subject = given.subject
+
+        if expected.is_a?(String)
+          matcher.description = "have subject of #{expected.inspect}"
+          matcher.failure_message = "expected the subject to be #{expected.inspect} but was #{given_subject.inspect}"
+          matcher.negative_failure_message = "expected the subject not to be #{expected.inspect} but was"
+
+          given_subject == expected
+        else
+          matcher.description = "have subject matching #{expected.inspect}"
+          matcher.failure_message = "expected the subject to match #{expected.inspect}, but did not.  Actual subject was: #{given_subject.inspect}"
+          matcher.negative_failure_message = "expected the subject not to match #{expected.inspect} but #{given_subject.inspect} does match it."
+
+          !!(given_subject =~ expected)
+        end
+      end
+     end
+
+     def include_email_with_subject(expected)
+       simple_matcher do |given_emails, matcher|
+
+         if expected.is_a?(String)
+           matcher.description = "include email with subject of #{expected.inspect}"
+           matcher.failure_message = "expected at least one email to have the subject #{expected.inspect} but none did. Subjects were #{given_emails.map(&:subject).inspect}"
+           matcher.negative_failure_message = "expected no email with the subject #{expected.inspect} but found at least one. Subjects were #{given_emails.map(&:subject).inspect}"
+
+           given_emails.map(&:subject).include?(expected)
+         else
+           matcher.description = "include email with subject matching #{expected.inspect}"
+           matcher.failure_message = "expected at least one email to have a subject matching #{expected.inspect}, but none did. Subjects were #{given_emails.map(&:subject).inspect}"
+           matcher.negative_failure_message = "expected no email to have a subject matching #{expected.inspect} but found at least one. Subjects were #{given_emails.map(&:subject).inspect}"
+
+           !!(given_emails.any?{ |mail| mail.subject =~ expected })
+         end
+       end
+     end
+
+     def have_body_text(expected)
+       simple_matcher do |given, matcher|
+
+         if expected.is_a?(String)
+           normalized_body = given.body.gsub(/\s+/, " ")
+           normalized_expected = expected.gsub(/\s+/, " ")
+           matcher.description = "have body including #{normalized_expected.inspect}"
+           matcher.failure_message = "expected the body to contain #{normalized_expected.inspect} but was #{normalized_body.inspect}"
+           matcher.negative_failure_message = "expected the body not to contain #{normalized_expected.inspect} but was #{normalized_body.inspect}"
+
+           normalized_body.include?(normalized_expected)
+         else
+           given_body = given.body
+           matcher.description = "have body matching #{expected.inspect}"
+           matcher.failure_message = "expected the body to match #{expected.inspect}, but did not.  Actual body was: #{given_body.inspect}"
+           matcher.negative_failure_message = "expected the body not to match #{expected.inspect} but #{given_body.inspect} does match it."
+
+           !!(given_body =~ expected)
+         end
+       end
+      end
+
+      def have_header(expected_name, expected_value)
+        simple_matcher do |given, matcher|
+          given_header = given.header
+
+          if expected_value.is_a?(String)
+            matcher.description = "have header #{expected_name}: #{expected_value}"
+            matcher.failure_message = "expected the headers to include '#{expected_name}: #{expected_value}' but they were #{given_header.inspect}"
+            matcher.negative_failure_message = "expected the headers not to include '#{expected_name}: #{expected_value}' but they were #{given_header.inspect}"
+
+            given_header[expected_name].to_s == expected_value
+          else
+            matcher.description = "have header #{expected_name} with value matching #{expected_value.inspect}"
+            matcher.failure_message = "expected the headers to include '#{expected_name}' with a value matching #{expected_value.inspect} but they were #{given_header.inspect}"
+            matcher.negative_failure_message = "expected the headers not to include '#{expected_name}' with a value matching #{expected_value.inspect} but they were #{given_header.inspect}"
+
+            given_header[expected_name].to_s =~ expected_value
+          end
+        end
+      end
+
+  end
+end