glennr-email_spec 0.3.5

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,149 @@
+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={})
+      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)
+      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)
+      mailbox_for(address) - read_emails_for(address)
+    end
+
+    def read_emails_for(address)
+      email_spec_hash[:read_emails][convert_address(address)] ||= []
+    end
+
+    def find_email(address, opts={})
+      address = convert_address(address)
+      if opts[:with_subject]
+        mailbox_for(address).find { |m| m.subject =~ Regexp.new(opts[:with_subject]) }
+      elsif opts[:with_text]
+        mailbox_for(address).find { |m| m.body =~ Regexp.new(opts[:with_text]) }
+      else
+        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={})
+      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 parse_email_count(amount)
+      case amount
+      when "no"
+        0
+      when "an"
+        1
+      else
+        amount.to_i
+      end
+    end
+
+    attr_reader :last_email_address
+
+    def convert_address(address)
+      @last_email_address = (address || current_email_address)
+      AddressConverter.instance.convert(@last_email_address)
+    end
+
+
+    def mailbox_for(address)
+      super(convert_address(address)) # super resides in Deliveries
+    end
+
+    def email_spec_deprecate(text)
+      puts ""
+      puts "DEPRECATION: #{text.split.join(' ')}"
+      puts ""
+    end
+
+  end
+end
+

data/lib/email_spec/matchers.rb

@@ -0,0 +1,186 @@
+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 delivered 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
+
+    class DeliverFrom
+
+      def initialize(email)
+        @expected_email_addresses = email
+      end
+
+      def description
+        "be delivered from #{@expected_email_addresses.inspect}"
+      end
+
+      def matches?(email)
+        @email = email
+        @actual_sender = (email.from || []).first
+        @actual_sender.eql? @expected_email_addresses
+      end
+
+      def failure_message
+        "expected #{@email.inspect} to deliver from #{@expected_email_addresses.inspect}, but it delivered from #{@actual_sender.inspect}"
+      end
+
+      def negative_failure_message
+        "expected #{@email.inspect} not to deliver from #{@expected_email_addresses.inspect}, but it did"
+      end
+    end
+
+    def deliver_from(email)
+      DeliverFrom.new(email)
+    end
+
+    alias :be_delivered_from :deliver_from
+
+    class BccTo
+
+      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 bcc'd to #{@expected_email_addresses.inspect}"
+      end
+
+      def matches?(email)
+        @email = email
+        @actual_recipients = (email.bcc || []).sort
+        @actual_recipients == @expected_email_addresses
+      end
+
+      def failure_message
+        "expected #{@email.inspect} to bcc to #{@expected_email_addresses.inspect}, but it was bcc'd to #{@actual_recipients.inspect}"
+      end
+
+      def negative_failure_message
+        "expected #{@email.inspect} not to bcc to #{@expected_email_addresses.inspect}, but it did"
+      end
+    end
+
+    def bcc_to(*expected_email_addresses_or_objects_that_respond_to_email)
+      BccTo.new(expected_email_addresses_or_objects_that_respond_to_email.flatten)
+    end
+
+    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

data/rails_generators/email_spec/email_spec_generator.rb

@@ -0,0 +1,17 @@
+# This generator adds email steps to the step definitions directory 
+generator_base = defined?(Rails) ? Rails::Generator::Base : RubiGen::Base
+class EmailSpecGenerator < generator_base
+  def manifest
+    record do |m|
+      m.directory 'features/step_definitions'
+      m.file      'email_steps.rb', 'features/step_definitions/email_steps.rb'
+    end
+  end
+
+protected
+
+  def banner
+    "Usage: #{$0} email_spec"
+  end
+
+end

data/rails_generators/email_spec/templates/email_steps.rb

@@ -0,0 +1,122 @@
+# Commonly used email steps
+#
+# To add your own steps make a custom_email_steps.rb
+# The provided methods are:
+#
+# last_email_address
+# reset_mailer
+# open_last_email
+# visit_in_email
+# unread_emails_for
+# mailbox_for
+# current_email
+# open_email
+# read_emails_for
+# find_email
+#
+# General form for email scenarios are:
+#   - clear the email queue (done automatically by email_spec)
+#   - execute steps that sends an email
+#   - check the user received an/no/[0-9] emails
+#   - open the email
+#   - inspect the email contents
+#   - interact with the email (e.g. click links)
+#
+# The Cucumber steps below are setup in this order.
+
+module EmailHelpers
+  def current_email_address
+    # Replace with your a way to find your current email. e.g @current_user.email
+    # last_email_address will return the last email address used by email spec to find an email.
+    # Note that last_email_address will be reset after each Scenario.
+    last_email_address || "example@example.com"
+  end
+end
+
+World(EmailHelpers)
+
+#
+# Reset the e-mail queue within a scenario.
+# This is done automatically before each scenario.
+#
+
+Given /^(?:a clear email queue|no emails have been sent)$/ do
+  reset_mailer
+end
+
+#
+# Check how many emails have been sent/received
+#
+
+Then /^(?:I|they|"([^"]*?)") should receive (an|no|\d+) emails?$/ do |address, amount|
+  unread_emails_for(address).size.should == parse_email_count(amount)
+end
+
+Then /^(?:I|they|"([^"]*?)") should have (an|no|\d+) emails?$/ do |address, amount|
+  mailbox_for(address).size.should == parse_email_count(amount)
+end
+
+# DEPRECATED
+# The following methods are left in for backwards compatibility and
+# should be removed by version 0.4.0
+Then /^(?:I|they|"([^"]*?)") should not receive an email$/ do |address|
+  email_spec_deprecate "The step 'I/they/[email] should not receive an email' is no longer supported.
+                      Please use 'I/they/[email] should receive no emails' instead."
+  unread_emails_for(address).size.should == 0
+end
+
+#
+# Accessing emails
+#
+
+# Opens the most recently received email
+When /^(?:I|they|"([^"]*?)") opens? the email$/ do |address|
+  open_email(address)
+end
+
+When /^(?:I|they|"([^"]*?)") opens? the email with subject "([^"]*?)"$/ do |address, subject|
+  open_email(address, :with_subject => subject)
+end
+
+When /^(?:I|they|"([^"]*?)") opens? the email with text "([^"]*?)"$/ do |address, text|
+  open_email(address, :with_text => text)
+end
+
+#
+# Inspect the Email Contents
+#
+
+Then /^(?:I|they) should see "([^"]*?)" in the email subject$/ do |text|
+  current_email.should have_subject(Regexp.new(text))
+end
+
+Then /^(?:I|they) should see "([^"]*?)" in the email body$/ do |text|
+  current_email.body.should =~ Regexp.new(text)
+end
+
+# DEPRECATED
+# The following methods are left in for backwards compatibility and
+# should be removed by version 0.4.0.
+Then /^(?:I|they) should see "([^"]*?)" in the subject$/ do |text|
+  email_spec_deprecate "The step 'I/they should see [text] in the subject' is no longer supported.
+                      Please use 'I/they should see [text] in the email subject' instead."
+  current_email.should have_subject(Regexp.new(text))
+end
+Then /^(?:I|they) should see "([^"]*?)" in the email$/ do |text|
+  email_spec_deprecate "The step 'I/they should see [text] in the email' is no longer supported.
+                      Please use 'I/they should see [text] in the email body' instead."
+  current_email.body.should =~ Regexp.new(text)
+end
+
+#
+# Interact with Email Contents
+#
+
+When /^(?:I|they) follow "([^"]*?)" in the email$/ do |link|
+  visit_in_email(link)
+end
+
+When /^(?:I|they) click the first link in the email$/ do
+  click_first_link_in_email
+end
+