hectoregm-email_spec 0.1.2

data/lib/email_spec/helpers.rb

@@ -0,0 +1,128 @@
+require 'uri'
+
+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

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/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,74 @@
+#Commonly used email steps
+#
+# To add your own steps make a custom_email_steps.rb
+# The provided methods are:
+#
+# reset_mailer 
+# open_last_email
+# visit_in_email
+# unread_emails_for
+# mailbox_for
+# current_email
+# open_email
+# read_emails_for
+# find_email
+
+module EmailHelpers
+  def current_email_address
+    "quentin@example.com" # Replace with your a way to find your current_email. e.g current_user.email
+  end
+end
+World(EmailHelpers)
+
+# Use this step to 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
+
+# Use this step to open the most recently sent e-mail. 
+When /^I open the email$/ do
+  open_email(current_email_address)
+end
+
+When /^I follow "(.*)" in the email$/ do |link|
+  visit_in_email(link)
+end
+
+Then /^I should receive (an|\d+) emails?$/ do |amount|
+  amount = 1 if amount == "an"
+  unread_emails_for(current_email_address).size.should == amount.to_i
+end
+
+Then /^"([^']*?)" should receive (\d+) emails?$/ do |address, n|
+  unread_emails_for(address).size.should == n.to_i 
+end
+
+Then /^"([^']*?)" should have (\d+) emails?$/ do |address, n|
+  mailbox_for(address).size.should == n.to_i
+end
+
+Then /^"([^']*?)" should not receive an email$/ do |address|
+  find_email(address).should be_nil
+end
+
+Then /^I should see "(.*)" in the subject$/ do |text|
+  current_email.should have_subject(Regexp.new(text))
+end
+
+Then /^I should see "(.*)" in the email$/ do |text|
+  current_email.body.should =~ Regexp.new(text)
+end
+
+When %r{^"([^']*?)" opens? the email with subject "([^']*?)"$} do |address, subject|
+  open_email(address, :with_subject => subject)
+end
+
+When %r{^"([^']*?)" opens? the email with text "([^']*?)"$} do |address, text|
+  open_email(address, :with_text => text)
+end
+
+When /^I click the first link in the email$/ do
+  click_first_link_in_email
+end
+

data/spec/email_spec/matchers_spec.rb

@@ -0,0 +1,159 @@
+
+require File.dirname(__FILE__) + '/../spec_helper'
+
+
+
+describe EmailSpec::Matchers do
+
+
+    class MatcherMatch
+
+      def initialize(object_to_test_match)
+        @object_to_test_match = object_to_test_match
+      end
+
+      def description
+        "match when provided #{@object_to_test_match.inspect}"
+      end
+
+      def matches?(matcher)
+        @matcher = matcher
+        matcher.matches?(@object_to_test_match)
+      end
+
+      def failure_message
+        "expected #{@matcher.inspect} to match when provided #{@object_to_test_match.inspect}, but it did not"
+      end
+
+      def negative_failure_message
+        "expected #{@matcher.inspect} not to match when provided #{@object_to_test_match.inspect}, but it did"
+      end
+    end
+
+    def match(object_to_test_match)
+      if object_to_test_match.is_a?(Regexp)
+        super # delegate to rspec's built in 'match' matcher
+      else
+        MatcherMatch.new(object_to_test_match)
+      end
+    end
+
+  include EmailSpec::Matchers
+
+  def mock_email(stubs)
+    mock("email", stubs)
+  end
+
+  describe "#deliver_to" do
+
+    it "should match when the email is set to deliver to the specidied address" do
+      email = mock_email(:to => "jimmy_bean@yahoo.com")
+
+      deliver_to("jimmy_bean@yahoo.com").should match(email)
+    end
+
+    it "should match when a list of emails is exact same as all of the email's recipients" do
+      email = mock_email(:to => ["james@yahoo.com", "karen@yahoo.com"])
+
+      deliver_to("karen@yahoo.com", "james@yahoo.com").should match(email)
+      deliver_to("karen@yahoo.com").should_not match(email)
+    end
+
+    it "should match when an array of emails is exact same as all of the email's recipients" do
+      addresses = ["james@yahoo.com", "karen@yahoo.com"]
+      email = mock_email(:to => addresses)
+      deliver_to(addresses).should match(email)
+    end
+
+    it "should use the passed in objects :email method if not a string" do
+      email = mock_email(:to => "jimmy_bean@yahoo.com")
+      user = mock("user", :email => "jimmy_bean@yahoo.com")
+
+      deliver_to(user).should match(email)
+    end
+
+  end
+
+  describe "#have_subject" do
+
+    describe "when regexps are used" do
+
+      it "should match when the subject mathches regexp" do
+        email = mock_email(:subject => ' -- The Subject --')
+
+        have_subject(/The Subject/).should match(email)
+        have_subject(/The Subject/).should match(email)
+        have_subject(/foo/).should_not match(email)
+      end
+
+      it "should have a helpful description" do
+        matcher = have_subject(/foo/)
+        matcher.matches?(mock_email(:subject => "bar"))
+
+        matcher.description.should == "have subject matching /foo/"
+      end
+
+      it "should offer helpful failing messages" do
+        matcher = have_subject(/foo/)
+        matcher.matches?(mock_email(:subject => "bar"))
+
+        matcher.failure_message.should == 'expected the subject to match /foo/, but did not.  Actual subject was: "bar"'
+      end
+
+      it "should offer helpful negative failing messages" do
+        matcher = have_subject(/b/)
+        matcher.matches?(mock_email(:subject => "bar"))
+
+        matcher.negative_failure_message.should == 'expected the subject not to match /b/ but "bar" does match it.'
+      end
+
+    end
+
+    describe "when strings are used" do
+
+      it "should match when the subject equals the passed in string exactly" do
+        email = mock_email(:subject => 'foo')
+
+        have_subject("foo").should match(email)
+        have_subject(" - foo -").should_not match(email)
+      end
+
+      it "should have a helpful description" do
+        matcher = have_subject("foo")
+        matcher.matches?(mock_email(:subject => "bar"))
+
+        matcher.description.should == 'have subject of "foo"'
+      end
+
+      it "should offer helpful failing messages" do
+        matcher = have_subject("foo")
+        matcher.matches?(mock_email(:subject => "bar"))
+
+        matcher.failure_message.should == 'expected the subject to be "foo" but was "bar"'
+      end
+
+
+      it "should offer helpful negative failing messages" do
+        matcher = have_subject("bar")
+        matcher.matches?(mock_email(:subject => "bar"))
+
+        matcher.negative_failure_message.should == 'expected the subject not to be "bar" but was'
+      end
+
+    end
+
+
+  end
+
+  describe "#include_email_with_subject" do
+    it "should have specs!"
+  end
+
+  describe "#have_body_text" do
+    it "should have specs!"
+  end
+  
+  describe "#have_header" do
+    it "should have specs!"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--colour
+--format s
+--loadby mtime
+--reverse

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'actionmailer'
+require 'spec'
+require File.expand_path(File.dirname(__FILE__) + '/../lib/email_spec.rb')