sanitize_email 1.0.0.rc3 → 1.0.2

data/CHANGELOG

@@ -1,3 +1,16 @@
+Version 1.0.0.rc4 - AUG.11.2012
+- Massive improvement to spec suite, and found bleeding
+  - needed to unregister the interceptors:
+    - Mail.class_variable_get(:@@delivery_interceptors).pop
+- Added SanitizeEmail.deprecate_in_silence
+- Added SanitizeEmail.sanitary &block
+  - Local overrides to SanitizeEmail config for specific local purpose
+  - Force Sanitization On for a block
+- Added SanitizeEmail.unsanitary &block
+  - Force Sanitization Off for a block
+- Added SanitizeEmail.force_sanitize = true # or false
+  - Force Sanitization On or Off
+
 Version 1.0.0.rc3 - AUG.08.2012
 - Forgot to switch from jeweler to gem-release, so making appropriate changes and bumping again
 - Aligning closer to bundler gem defaults
@@ -5,7 +18,6 @@ Version 1.0.0.rc3 - AUG.08.2012
 - Added facets dependency to get cattr functionality (and hopefully other cool stuff)
 - Gem dependencies in gemspec
 
-
 Version 1.0.0.rc2 - AUG.08.2012 - botched
 - Bug: loading the gem in a rails app broke mailer specs in the app - Fixed
   - https://github.com/pboling/sanitize_email/issues/4

data/Gemfile

@@ -1,4 +1,4 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in mygem.gemspec
+# Specify your gem's dependencies in sanitize_email.gemspec
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sanitize_email (1.0.0.rc2)
+    sanitize_email (1.0.0.rc3)
       facets (> 0)
 
 GEM

data/README.rdoc

@@ -1,25 +1,23 @@
-= sanitize_email {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/pboling/sanitize_email]
+= sanitize_email {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/pboling/sanitize_email] {<img src="https://secure.travis-ci.org/pboling/sanitize_email.png?branch=master" alt="Build Status" />}[http://travis-ci.org/pboling/sanitize_email]
 
 This gem allows you to globally override your mail delivery settings.  It's particularly helpful when you want to omit the delivery of email (e.g. in development/test environments) or alter the to/cc/bcc (e.g. in staging or demo environments) of all email generated from your application.
 
-It is a "configure it and forget it" type gem that requires very little setup.  It includes some very innocuous monkey patching of ActionMailer::Base to work its magic.
+It is a "configure it and forget it" type gem that requires very little setup.  It uses the 'register_interceptor' API of ActionMailer or the Mail gem.  It should work with Rails >3 or any Ruby app that is using Mail or ActionMailer gems.
 
-It currently solves five (3!) common problems in ruby web applications that use ActionMailer, or the Mail gem, or anything that follows Mailer's register_interceptor pattern:
+It currently solves five (3!) common problems in ruby web applications that use email:
 
-=== Working Locally with Production Data
-
-Peter described this common problem in his original plugin implementation as such:
+=== #1 Working Locally with Production Data
 
 * I have a production site with live data.
 * I dump the live data and securely transfer it to another machine (rync -e ssh), and import it using a few rake tasks here: http://github.com/pboling/sir-du-bob
 * On this separate machine (staging, or development) I run tests, and test various features which often send out email (registration/signup, order placement, etc.)
 * I usually want the emails to get sent from these non-production environments so I can verify what they look like when sent, but I don't ever want to risk them getting sent to addresses that are not mine.
 
-=== Re-routing Email on a Staging or QA Server
+=== #2 Re-routing Email on a Staging or QA Server
 
 Another very important use case for me is to transparently re-route email generated from a staging or QA server to an appropriate person.  For example, it's common for us to set up a staging server for a client to use to view our progress and test out new features.  It's important for any email that is generated from our web application be delivered to the client's inbox so that they can review the content and ensure that it's acceptable.  Similarly, we set up QA instances for our own QA team and we use {rails-caddy}[http://github.com/jtrupiano/rails-caddy] to allow each QA person to configure it specifically for them.
 
-=== Testing Email from a Hot Production Server
+=== #3 Testing Email from a Hot Production Server
 
 If you install this gem on a production server (which I don't always do), you can load up script/console and override the to/cc/bcc on all emails for the duration of your console session.  This allows you to poke and prod a live production instance, and route all email to your own inbox for inspection.  The best part is that this can all be accomplished without changing a single line of your application code.
 
@@ -33,9 +31,10 @@ Customize and add to an initializer:
 
   SanitizeEmail::Config.configure do |config|
     config[:sanitized_recipients] = 'to@sanitize_email.org'
-    config[:sanitized_bcc] =        'bcc@sanitize_email.org'
     config[:sanitized_cc] =         'cc@sanitize_email.org'
-    config[:local_environment_proc] =   Proc.new { %w(development test).include?(Rails.env) }
+    config[:sanitized_bcc] =        'bcc@sanitize_email.org'
+    # sanitize emails from development and test, or set whatever logic should turn sanitize_email on and off here:
+    config[:activation_proc] =   Proc.new { %w(development test).include?(Rails.env) }
     config[:use_actual_email_prepended_to_subject] = true   # or false
     config[:use_actual_email_as_sanitized_user_name] = true # or false
   end
@@ -46,64 +45,16 @@ But wait there's more:
 
 Let's say you have a method in your model that you can call to test the signup email. You want to be able to test sending it to any user at any time... but you don't want the user to ACTUALLY get the email, even in production. A dilemma, yes?  Not anymore!
 
-To override the environment based switch use force_sanitize, which is nil, and ignored by default. When set to true or false it will turn sanitization on or off:
-
-  SanitizeEmail::Config.configure do |config|
-    config[:force_sanitize] = true
-  end
-
-== Example
-
-So here's how you can use force_sanitize to override the override.
-
-Even if you set:
-
-  ActionMailer::Base.local_environments = %w( development )
-
-and are in the development environment, you can override the override anywhere in your code.
-
-    class User < ActiveRecord::Base
-      def test_signup_email_me_only
-        SanitizeEmail::Config.configure do |config|
-          config[:force_sanitize] = true
-        end
-        UserMailer.deliver_signup_notification(self)
-        UserMailer.force_sanitize = nil
-      end
-
-      def test_signup_email_user_only
-        SanitizeEmail::Config.configure do |config|
-          config[:force_sanitize] = false
-        end
-        UserMailer.deliver_signup_notification(self)
-        UserMailer.force_sanitize = nil
-      end
-
-      # this third method would conditionally use the overridden recipients based on inclusion of current Rails environment in the local_environments configuration option.
-      def test_signup_email_environment
-        UserMailer.deliver_signup_notification(self)
-      end
-    end
-
-Load the console with ruby script/console and regardless of what environment you are in:
-
-    > User.find(4).test_signup_email_me_only
-
-and the email will have it's recipients, bcc, and cc overridden to be whatever you set the sanitized values to be.
-Then if you want to send it to the actual user, instead of yourself
-
-    > User.find(4).test_signup_email_user_only
+To override the environment based switch use force_sanitize, which is normally nil, and ignored by default. When set to true or false it will turn sanitization on or off:
 
-== Install as a Plugin
+  SanitizeEmail.force_sanitize = true
 
-Plugin using Git:
+== Deprecations
 
-  # Installation as plugin works too! (let me know if you find any bugs, as I don't ever run it this way.)
-  ./script/plugin install git://github.com/pboling/sanitize_email.git
+Sometimes things get deprecated (meaning they still work, but are noisy about it).  If this happens to you, and you like your head in the sand, call this number:
 
-== Install as a Git Submodule (plugin)
+  SanitizeEmail::Deprecation.deprecate_in_silence = true
 
-  git submodule add git://github.com/pboling/sanitize_email.git vendor/plugins/sanitize_email
 
 == Authors
 

data/init.rb

@@ -1,3 +1,2 @@
-require 'action_mailer'
 require 'sanitize_email'
 

data/lib/sanitize_email.rb

@@ -5,6 +5,7 @@ module SanitizeEmail
   require 'sanitize_email/version'
   require 'sanitize_email/config'
   require 'sanitize_email/bleach'
+  require 'sanitize_email/email_matchers'
   require 'sanitize_email/deprecation'
 
   # Allow non-rails implementations to use this gem
@@ -29,17 +30,74 @@ module SanitizeEmail
     SanitizeEmail[name]
   end
 
+  # NOTE: Deprecated method
+  # We have to actually define because we can't deprecate methods that are hooked up via method_missing
   def self.sanitized_recipients
     SanitizeEmail[:sanitized_recipients]
   end
 
+  # NOTE: Deprecated method
+  # We have to actually define because we can't deprecate methods that are hooked up via method_missing
   def self.local_environments
     SanitizeEmail[:local_environments]
   end
 
+  mattr_reader :force_sanitize
+  mattr_writer :force_sanitize
+  self.force_sanitize = nil
+
+  # Regardless of the Config settings of SanitizeEmail you can do a local override to send sanitary email in any environment.
+  # You have access to all the same configuration options in the parameter hash as you can set in the actual
+  # SanitizeEmail.configure block.
+  #
+  # SanitizeEmail.sanitary(config_options = {}) do
+  #   Mail.deliver do
+  #     from      'from@example.org'
+  #     to        'to@example.org' # Will actually be sent to the override addresses setup in Config
+  #     reply_to  'reply_to@example.org'
+  #     subject   'subject'
+  #   end
+  # end
+  #
+  def self.sanitary(config_options = {}, &block)
+    janitor({:forcing => true}) do
+      original = SanitizeEmail::Config.config.dup
+      SanitizeEmail::Config.config.merge!(config_options)
+      yield
+      SanitizeEmail::Config.config = original
+    end
+  end
+
+  # Regardless of the Config settings of SanitizeEmail you can do a local override to force unsanitary email in any environment.
+  #
+  # SanitizeEmail.unsanitary do
+  #   Mail.deliver do
+  #     from      'from@example.org'
+  #     to        'to@example.org'
+  #     reply_to  'reply_to@example.org'
+  #     subject   'subject'
+  #   end
+  # end
+  #
+  def self.unsanitary &block
+    janitor({:forcing => false}) do
+      yield
+    end
+  end
+
+  def self.janitor(options, &block)
+    return false unless block_given?
+    original = SanitizeEmail.force_sanitize
+    SanitizeEmail.force_sanitize = options[:forcing]
+    yield
+    SanitizeEmail.force_sanitize = original
+  end
+
+  # Setup Deprecations!
   class << self
     extend SanitizeEmail::Deprecation
     deprecated_alias :sanitized_recipients, :sanitized_to
-    deprecated :local_environments, :local_environment_proc
+    deprecated :local_environments, :activation_proc
   end
+
 end

data/lib/sanitize_email/bleach.rb

@@ -4,6 +4,10 @@
 module SanitizeEmail
   class Bleach
 
+    mattr_reader :deprecate_in_silence
+    mattr_writer :deprecate_in_silence
+    self.deprecate_in_silence = false
+
     class MissingTo < StandardError; end
     class UnknownOverride < StandardError; end
 
@@ -15,7 +19,7 @@ module SanitizeEmail
       :injected  # Track whether or not the subject has been injected with usernames
 
     def initialize(args = {})
-      # Not using extract_options! because no-rails compatibility is a goal
+      # Not using extract_options! because non-rails compatibility is a goal
       @sanitized_to = args[:sanitized_to]    || SanitizeEmail[:sanitized_to]
       @sanitized_cc = args[:sanitized_cc]    || SanitizeEmail[:sanitized_cc]
       @sanitized_bcc = args[:sanitized_bcc]  || SanitizeEmail[:sanitized_bcc]
@@ -35,14 +39,36 @@ module SanitizeEmail
       end
     end
 
-    # Only relevant
-    def consider_local?
-      SanitizeEmail.local_environment_proc.call if SanitizeEmail.local_environment_proc.respond_to?(:call)
+    def activate?
+      SanitizeEmail.activation_proc.call if SanitizeEmail.activation_proc.respond_to?(:call)
     end
 
     # This method will be called by the Hook to determine if an override should occur
+    # There are three ways SanitizeEmail can be turned on; in order of precedence they are:
+    #
+    # 1. SanitizeEmail.force_sanitize = true # by default it is nil
+    # 2. Mail.register_interceptor(SanitizeEmail::Bleach.new(:engage => true)) # by default it is nil
+    # 3. SanitizeEmail::Config.configure {|config| config[:activation_proc] = Proc.new { true } } be default it is false
+    #
+    # Note: Number 1 is the method used by the SanitizeEmail.sanitary block
+    # Note: Number 2 would not be used unless you setup your own register_interceptor)
+    # If installed but not configured, sanitize email DOES NOTHING.  Until configured the defaults leave it turned off.
     def sanitize_engaged?
-      !SanitizeEmail.force_sanitize.nil? ? SanitizeEmail.force_sanitize : self.consider_local?
+
+      # Has it been forced via the force_sanitize mattr?
+      forced = !SanitizeEmail.force_sanitize.nil?
+      #puts "forced: #{SanitizeEmail.force_sanitize.inspect}" if forced
+      return SanitizeEmail.force_sanitize if forced
+
+     # Is this particular instance of Bleach engaged
+      engaged = !self.engage.nil?
+      #puts "engaged: #{self.engage.inspect}" if engaged
+      return self.engage if engaged
+
+      # Should we sanitize due to the activation_proc?
+      #puts "activated: #{self.activate?}"
+      return self.activate?
+
     end
 
     def subject_override(real_subject, actual_addresses)

data/lib/sanitize_email/config.rb

@@ -7,9 +7,6 @@ module SanitizeEmail
     cattr_writer :config
 
     self.config ||= {
-      # Adds the following class attributes to the classes that include NinthBit::SanitizeEmail
-      :force_sanitize => nil,
-
       # Specify the BCC addresses for the messages that go out in 'local' environments
       :sanitized_bcc => nil,
 
@@ -34,18 +31,21 @@ module SanitizeEmail
       # e.g. "real@example.com rest of subject"
       :use_actual_email_prepended_to_subject => false,
 
-      :local_environment_proc => Proc.new { true }
+      :activation_proc => Proc.new { false }
     }
     def self.configure &block
-      yield self.config
+      yield @@config
 
       # Gracefully handle deprecated config values.
       # Actual deprecation warnings are thrown in the top SanitizeEmail module thanks to our use of dynamic methods.
-      if config[:local_environments] && defined?(Rails)
-        config[:local_environment_proc] = Proc.new { SanitizeEmail.local_environments.include?(Rails.env) }
+      if @@config[:local_environments] && defined?(Rails)
+        @@config[:activation_proc] = Proc.new { SanitizeEmail.local_environments.include?(Rails.env) }
       end
-      if config[:sanitize_recipients]
-        config[:sanitize_to] = SanitizeEmail.sanitized_recipients
+      if @@config[:sanitized_recipients]
+        SanitizeEmail.sanitized_recipients # calling it to trigger the deprecation warning.
+                                           #Won't actually be set with any value,
+                                           # because we are still inside the configure block.
+        @@config[:sanitized_to] = @@config[:sanitized_recipients]
       end
     end
 

data/lib/sanitize_email/deprecation.rb

@@ -1,15 +1,20 @@
 # See http://www.seejohncode.com/2012/01/09/deprecating-methods-in-ruby/
+require 'facets/module/mattr' # gives cattr
 
 module SanitizeEmail
   module Deprecation
 
+    mattr_reader :deprecate_in_silence
+    mattr_writer :deprecate_in_silence
+    self.deprecate_in_silence = false
+
     # Define a deprecated alias for a method
     # @param [Symbol] name - name of method to define
     # @param [Symbol] replacement - name of method to (alias)
     def deprecated_alias(name, replacement)
       # Create a wrapped version
       define_method(name) do |*args, &block|
-        warn "SanitizeEmail: ##{name} deprecated (please use ##{replacement})"
+        warn "SanitizeEmail: ##{name} deprecated (please use ##{replacement})" unless @@deprecate_in_silence
         send replacement, *args, &block
       end
     end
@@ -23,10 +28,12 @@ module SanitizeEmail
       alias_method old_name, name
       # And replace it with a wrapped version
       define_method(name) do |*args, &block|
-        if replacement
-          warn "SanitizeEmail: ##{name} deprecated (please use ##{replacement})"
-        else
-          warn "SanitizeEmail: ##{name} deprecated"
+        unless @@deprecate_in_silence
+          if replacement
+            warn "SanitizeEmail: ##{name} deprecated (please use ##{replacement})"
+          else
+            warn "SanitizeEmail: ##{name} deprecated"
+          end
         end
         send old_name, *args, &block
       end

data/lib/sanitize_email/email_matchers.rb

@@ -0,0 +1,51 @@
+module SanitizeEmail
+  module EmailMatchers
+    class UnexpectedMailType < StandardError; end
+
+    def string_matching(matcher, part, mail_or_part)
+      if mail_or_part.respond_to?(:=~) # Can we match a regex against it?
+        mail_or_part =~ Regexp.new(Regexp.escape(matcher))
+      else
+        raise UnexpectedMailType, "Cannot match #{matcher} for #{part}"
+      end
+    end
+
+    # Normalize arrays to strings
+    def array_matching(matcher, part, mail_or_part)
+      mail_or_part = mail_or_part.join(', ') if mail_or_part.respond_to?(:join)
+      string_matching(matcher, part, mail_or_part)
+    end
+
+    def email_matching(matcher, part, mail_or_part)
+      array_matching(matcher, part, mail_or_part.send(part))
+    end
+
+    if defined?(Rspec)
+      [:from, :to, :cc, :bcc, :subject, :reply_to].each do |attribute|
+        RSpec::Matchers.define "have_#{attribute}" do |matcher|
+          match do |actual|
+            email_matching(matcher, attribute, actual)
+          end
+        end
+      end
+
+      [:from, :to, :cc, :bcc, :subject, :reply_to].each do |attribute|
+        RSpec::Matchers.define "be_#{attribute}" do |matcher|
+          match do |actual|
+            string_matching(matcher, attribute, actual)
+          end
+        end
+      end
+
+      RSpec::Matchers.define "have_to_username" do |matcher|
+        def get_username(email_message)
+          email_message.header.fields[3].value
+        end
+        match do |actual|
+          string_matching(matcher, :to_username, get_username(actual))
+        end
+      end
+    end
+
+  end
+end

data/lib/sanitize_email/version.rb

@@ -1,5 +1,5 @@
 #Copyright (c) 2008-12 Peter H. Boling of 9thBit LLC
 #Released under the MIT license
 module SanitizeEmail
-  VERSION = '1.0.0.rc3'
+  VERSION = '1.0.2'
 end

data/sanitize_email.gemspec

@@ -8,10 +8,11 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
   s.authors = ["Peter Boling", "John Trupiano", "George Anderson"]
   s.date = "2012-08-08"
-  s.summary = "In Rails, Sinatra, or any framework using a Mail-like API: Test an application's email abilities without ever sending a message to actual live addresses"
-  s.description = "In Rails, Sinatra, or any framework using a Mail-like API: Aids in development, testing, qa, and production troubleshooting of email issues without worrying that emails will get sent to actual live addresses."
+  s.summary = "Rails/Sinatra/Mail gem: Test email abilities without ever sending a message to actual live addresses"
+  s.description = "In Rails, Sinatra, or simply the mail gem: Aids in development, testing, qa, and production troubleshooting of email issues without worrying that emails will get sent to actual live addresses."
   s.email = ["peter.boling@gmail.com", "jtrupiano@gmail.com", "george@benevolentcode.com"]
   s.extra_rdoc_files = [
+    "CHANGELOG",
     "LICENSE",
     "README.rdoc"
   ]
@@ -23,46 +24,20 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.24"
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+  # Runtime Dependencies
+  # to replace the cattr_accessor method we lost when removing rails from run time dependencies
+  s.add_runtime_dependency(%q<facets>, ["> 0"])
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<facets>, ["> 0"]) # to replace the cattr_accessor method we lost when removing rails
-      s.add_development_dependency(%q<rails>, ["> 3"])
-      s.add_development_dependency(%q<actionmailer>, ["> 3"])
-      s.add_development_dependency(%q<jeweler>, [">= 0"])
-      s.add_development_dependency(%q<letter_opener>, [">= 0"])
-      s.add_development_dependency(%q<launchy>, [">= 0"])
-      s.add_development_dependency(%q<rspec>, [">= 0"])
-      s.add_development_dependency(%q<mail>, [">= 0"])
-      s.add_development_dependency(%q<rdoc>, [">= 3.12"])
-      s.add_development_dependency(%q<reek>, [">= 1.2.8"])
-      s.add_development_dependency(%q<roodi>, [">= 2.1.0"])
-    else
-      s.add_dependency(%q<facets>, ["> 0"]) # to replace the cattr_accessor method we lost when removing rails
-      s.add_dependency(%q<rails>, ["> 3"])
-      s.add_dependency(%q<actionmailer>, ["> 3"])
-      s.add_dependency(%q<jeweler>, [">= 0"])
-      s.add_dependency(%q<letter_opener>, [">= 0"])
-      s.add_dependency(%q<launchy>, [">= 0"])
-      s.add_dependency(%q<rspec>, [">= 0"])
-      s.add_dependency(%q<mail>, [">= 0"])
-      s.add_dependency(%q<rdoc>, [">= 3.12"])
-      s.add_dependency(%q<reek>, [">= 1.2.8"])
-      s.add_dependency(%q<roodi>, [">= 2.1.0"])
-    end
-  else
-    s.add_dependency(%q<facets>, ["> 0"]) # to replace the cattr_accessor method we lost when removing rails
-    s.add_dependency(%q<rails>, ["> 3"])
-    s.add_dependency(%q<actionmailer>, ["> 3"])
-    s.add_dependency(%q<jeweler>, [">= 0"])
-    s.add_dependency(%q<letter_opener>, [">= 0"])
-    s.add_dependency(%q<launchy>, [">= 0"])
-    s.add_dependency(%q<rspec>, [">= 0"])
-    s.add_dependency(%q<mail>, [">= 0"])
-    s.add_dependency(%q<rdoc>, [">= 3.12"])
-    s.add_dependency(%q<reek>, [">= 1.2.8"])
-    s.add_dependency(%q<roodi>, [">= 2.1.0"])
-  end
+  # Development Dependencies
+  s.add_development_dependency(%q<rails>, ["> 3"])
+  s.add_development_dependency(%q<actionmailer>, ["> 3"])
+  s.add_development_dependency(%q<jeweler>, [">= 0"])
+  s.add_development_dependency(%q<letter_opener>, [">= 0"])
+  s.add_development_dependency(%q<launchy>, [">= 0"])
+  s.add_development_dependency(%q<rspec>, [">= 0"])
+  s.add_development_dependency(%q<mail>, [">= 0"])
+  s.add_development_dependency(%q<rdoc>, [">= 3.12"])
+  s.add_development_dependency(%q<reek>, [">= 1.2.8"])
+  s.add_development_dependency(%q<roodi>, [">= 2.1.0"])
 end
 

data/spec/sanitize_email_spec.rb

@@ -3,63 +3,67 @@ require 'spec_helper'
 #
 # TODO: Letter Opener should *not* be required, but setting the delivery method to :file was causing connection errors... WTF?
 #
-# Letter Opener won't let us test the to when the to has a 'user name'
-#   @email_file.should have_to("~to at example.org~ <to@sanitize_email.org>")
-# TODO: Also not sure how to test the user name part of the To: header via the mail object
-#
-# Letter Opener won't let us test the bcc
-#   @email_file.should have_cc("cc@sanitize_email.org")
-# Fortunately we can still test the mail object returned by the deliver call
-#
-
 describe SanitizeEmail do
 
+  DEFAULT_TEST_CONFIG = {
+    :sanitized_cc =>  'cc@sanitize_email.org',
+    :sanitized_bcc => 'bcc@sanitize_email.org',
+    :use_actual_email_prepended_to_subject => false,
+    :use_actual_email_as_sanitized_user_name => false
+  }
+
+  before(:all) do
+    SanitizeEmail::Deprecation.deprecate_in_silence = true
+  end
+
+  # Cleanup, so tests don't bleed
   after(:each) do
     SanitizeEmail::Config.config = {}
+    SanitizeEmail.force_sanitize = nil
+    Mail.class_variable_get(:@@delivery_interceptors).pop
   end
 
   def sanitize_spec_dryer(rails_env = 'test')
     Launchy.stub(:open)
+    Launchy.should_receive(:open)
     location = File.expand_path('../tmp/mail_dump', __FILE__)
     FileUtils.rm_rf(location)
     Mail.defaults do
       delivery_method LetterOpener::DeliveryMethod, :location => location
     end
-
     Rails.stub(:env).and_return(rails_env)
-    @location = location
   end
 
   def configure_sanitize_email(sanitize_hash = {})
-    defaults = {
-      :sanitized_to =>  'to@sanitize_email.org',
-      :sanitized_cc =>  'cc@sanitize_email.org',
-      :sanitized_bcc => 'bcc@sanitize_email.org',
-      :use_actual_email_prepended_to_subject => true,
-      :use_actual_email_as_sanitized_user_name => true
-    }
-    sanitize_hash = defaults.merge(sanitize_hash)
+    options = DEFAULT_TEST_CONFIG.merge(sanitize_hash)
+    options.reverse_merge!({ :sanitized_to => 'to@sanitize_email.org' }) unless sanitize_hash.has_key?(:sanitized_recipients)
     SanitizeEmail::Config.configure do |config|
-      config[:sanitized_to] =         sanitize_hash[:sanitized_to]
-      config[:sanitized_cc] =         sanitize_hash[:sanitized_cc]
-      config[:sanitized_bcc] =        sanitize_hash[:sanitized_bcc]
-      config[:use_actual_email_prepended_to_subject] = sanitize_hash[:use_actual_email_prepended_to_subject]
-      config[:use_actual_email_as_sanitized_user_name] = sanitize_hash[:use_actual_email_as_sanitized_user_name]
+      config[:sanitized_to] =         options[:sanitized_to]
+      config[:sanitized_cc] =         options[:sanitized_cc]
+      config[:sanitized_bcc] =        options[:sanitized_bcc]
+      config[:use_actual_email_prepended_to_subject] = options[:use_actual_email_prepended_to_subject]
+      config[:use_actual_email_as_sanitized_user_name] = options[:use_actual_email_as_sanitized_user_name]
       # For testing deprecated configuration options:
-      config[:local_environments] =   sanitize_hash[:local_environments] if sanitize_hash[:local_environments]
-      config[:sanitized_to] ||= sanitize_hash[:sanitized_recipients] if sanitize_hash[:sanitized_recipients]
+      config[:local_environments] =   options[:local_environments] if options[:local_environments]
+      config[:sanitized_recipients] = options[:sanitized_recipients] if options[:sanitized_recipients]
     end
     Mail.register_interceptor(SanitizeEmail::Bleach.new)
   end
 
-  def sanitized_mail_delivery(options = {})
-    unless options.has_key?(:force_sanitize)
-      options[:force_sanitize] = false
+  def sanitary_mail_delivery(config_options = {})
+    SanitizeEmail.sanitary(config_options) do
+      mail_delivery
     end
-    # Ensure that localish? will return sanitization_switch if true or false, and use proc when nil
-    SanitizeEmail::Config.config[:force_sanitize] = options[:force_sanitize]
-    Launchy.should_receive(:open)
-    @mail_message = Mail.deliver do
+  end
+
+  def unsanitary_mail_delivery
+    SanitizeEmail.unsanitary do
+      mail_delivery
+    end
+  end
+
+  def mail_delivery
+    @email_message = Mail.deliver do
       from      'from@example.org'
       to        'to@example.org'
       cc        'cc@example.org'
@@ -67,75 +71,200 @@ describe SanitizeEmail do
       reply_to  'reply_to@example.org'
       subject   'original subject'
     end
-    # All the email gets dumped to file once for each type of recipient (:to, :cc, :bcc)
-    # Each file is identical, so we only need to check one of them:
-    @email_file = File.read(Dir["#{@location}/*/plain.html"].first)
   end
 
-  context "localish?" do
-    before(:each) do
-      sanitize_spec_dryer
-      configure_sanitize_email
-    end
+  context "en email" do
+    context "engaged" do
+      before(:each) do
+        sanitize_spec_dryer
+        configure_sanitize_email
+      end
 
-    context "false" do
-      it "alters nothing" do
-        sanitized_mail_delivery(:force_sanitize => false)
-        @email_file.should have_from("from@example.org")
-        @email_file.should have_to("to@example.org")
-        @mail_message.header.fields[3].value.should_not have_to("to at example.org")
-        @mail_message.should have_cc("cc@example.org")
-        @mail_message.should have_bcc("bcc@example.org")
-        @email_file.should have_subject("original subject")
+      context "false" do
+        before(:each) do
+          unsanitary_mail_delivery
+        end
+        it "should not alter non-sanitized attributes" do
+          @email_message.should have_from('from@example.org')
+          @email_message.should have_reply_to('reply_to@example.org')
+        end
+        it "should not prepend overrides" do
+          @email_message.should_not have_to_username("to at sanitize_email.org")
+          @email_message.should_not have_subject("(to at sanitize_email.org)")
+        end
+        it "alters nothing" do
+          @email_message.should have_from('from@example.org')
+          @email_message.should have_reply_to('reply_to@example.org')
+          @email_message.should have_from("from@example.org")
+          @email_message.should have_to("to@example.org")
+          @email_message.should_not have_to_username("to at")
+          @email_message.should have_cc("cc@example.org")
+          @email_message.should have_bcc("bcc@example.org")
+          @email_message.should have_subject("original subject")
+        end
       end
-    end
 
-    context "true" do
-      it "should override" do
-        sanitized_mail_delivery(:force_sanitize => true)
-        @email_file.should have_from("from@example.org")
-        #puts "@mail_message.header.fields[3]: #{@mail_message.header.fields[3]}"
-        #@mail_message.header.fields[3].value.should have_to("to at example.org")
-        @mail_message.should have_cc("cc@sanitize_email.org")
-        @mail_message.should have_bcc("bcc@sanitize_email.org")
-        @email_file.should have_subject("(to at example.org) original subject")
+      context "true" do
+        before(:each) do
+          sanitary_mail_delivery
+        end
+        it "should not alter non-sanitized attributes" do
+          @email_message.should have_from('from@example.org')
+          @email_message.should have_reply_to('reply_to@example.org')
+        end
+        it "should not prepend overrides" do
+          @email_message.should_not have_to_username("to at sanitize_email.org")
+          @email_message.should_not have_subject("(to at sanitize_email.org)")
+        end
+        it "should override" do
+          @email_message.should have_to("to@sanitize_email.org")
+          @email_message.should have_cc("cc@sanitize_email.org")
+          @email_message.should have_bcc("bcc@sanitize_email.org")
+        end
+        it "should not prepend originals by default" do
+          @email_message.should_not have_to_username("to at example.org <to@sanitize_email.org>")
+          @email_message.should_not have_subject("(to at example.org) original subject")
+        end
       end
     end
-  end
 
-  context "deprecated config options" do
-    context "local_environments" do
-      it "should use local_environment_proc for matching environment" do
-        sanitize_spec_dryer('test')
-        configure_sanitize_email({:local_environments => ['test']})
-        SanitizeEmail[:local_environment_proc].call.should == true
-        sanitized_mail_delivery(:force_sanitize => nil)
-        @email_file.should have_to("to@sanitize_email.org")
-        @email_file.should have_subject("(to at example.org) original subject")
-      end
-      it "should use local_environment_proc for non-matching environment" do
-        sanitize_spec_dryer('production')
-        configure_sanitize_email({:local_environments => ['development']}) # Won't match!
-        SanitizeEmail[:local_environment_proc].call.should == false
-        sanitized_mail_delivery(:force_sanitize => nil)
-        @mail_message.should_not have_subject("to at example.org")
+    context "config options" do
+      context ":use_actual_email_prepended_to_subject" do
+        context "true" do
+          before(:each) do
+            sanitize_spec_dryer
+            configure_sanitize_email({:use_actual_email_prepended_to_subject => true})
+            sanitary_mail_delivery
+          end
+          it "original to is prepended" do
+            @email_message.should have_subject("(to at example.org) original subject")
+          end
+          it "should not alter non-sanitized attributes" do
+            @email_message.should have_from('from@example.org')
+            @email_message.should have_reply_to('reply_to@example.org')
+          end
+          it "should not prepend overrides" do
+            @email_message.should_not have_to_username("to at sanitize_email.org")
+            @email_message.should_not have_subject("(to at sanitize_email.org)")
+          end
+        end
+        context "false" do
+          before(:each) do
+            sanitize_spec_dryer
+            configure_sanitize_email({:use_actual_email_prepended_to_subject => false})
+            sanitary_mail_delivery
+          end
+          it "original to is not prepended" do
+            @email_message.should_not have_subject("(to at example.org) original subject")
+          end
+          it "should not alter non-sanitized attributes" do
+            @email_message.should have_from('from@example.org')
+            @email_message.should have_reply_to('reply_to@example.org')
+          end
+          it "should not prepend overrides" do
+            @email_message.should_not have_to_username("to at sanitize_email.org")
+            @email_message.should_not have_subject("(to at sanitize_email.org)")
+          end
+        end
       end
-    end
 
-    context "sanitized_recipients is set" do
-      before(:each) do
-        sanitize_spec_dryer
-        configure_sanitize_email({:sanitized_recipients => 'barney@sanitize_email.org'})
+      context ":use_actual_email_as_sanitized_user_name" do
+        context "true" do
+          before(:each) do
+            sanitize_spec_dryer
+            configure_sanitize_email({:use_actual_email_as_sanitized_user_name => true})
+            sanitary_mail_delivery
+          end
+          it "original to is munged and prepended" do
+            @email_message.should have_to_username("to at example.org <to@sanitize_email.org>")
+          end
+          it "should not alter non-sanitized attributes" do
+            @email_message.should have_from('from@example.org')
+            @email_message.should have_reply_to('reply_to@example.org')
+          end
+          it "should not prepend overrides" do
+            @email_message.should_not have_to_username("to at sanitize_email.org")
+            @email_message.should_not have_subject("(to at sanitize_email.org)")
+          end
+        end
+        context "false" do
+          before(:each) do
+            sanitize_spec_dryer
+            configure_sanitize_email({:use_actual_email_as_sanitized_user_name => false})
+            sanitary_mail_delivery
+          end
+          it "original to is not prepended" do
+            @email_message.should_not have_to_username("to at example.org <to@sanitize_email.org>")
+          end
+          it "should not alter non-sanitized attributes" do
+            @email_message.should have_from('from@example.org')
+            @email_message.should have_reply_to('reply_to@example.org')
+          end
+          it "should not prepend overrides" do
+            @email_message.should_not have_to_username("to at sanitize_email.org")
+            @email_message.should_not have_subject("(to at sanitize_email.org)")
+          end
+        end
       end
-      it "used as sanitized_to" do
-        sanitized_mail_delivery(:force_sanitize => true)
-        @email_file.should have_from("from@example.org")
-        @mail_message.should have_to("to@sanitize_email.org")
-        @email_file.should have_subject("(to at example.org) original subject")
+
+      context "deprecated" do
+        #before(:each) do
+        #  SanitizeEmail::Deprecation.deprecate_in_silence = false
+        #end
+        context ":local_environments" do
+          context "matching" do
+            before(:each) do
+              sanitize_spec_dryer('test')
+              configure_sanitize_email({:local_environments => ['test']})
+              SanitizeEmail[:activation_proc].call.should == true
+              mail_delivery
+            end
+            it "should not alter non-sanitized attributes" do
+              @email_message.should have_from('from@example.org')
+              @email_message.should have_reply_to('reply_to@example.org')
+            end
+            it "should use activation_proc for matching environment" do
+              @email_message.should have_to("to@sanitize_email.org")
+              @email_message.should have_cc("cc@sanitize_email.org")
+              @email_message.should have_bcc("bcc@sanitize_email.org")
+            end
+          end
+          context "non-matching" do
+            before(:each) do
+              sanitize_spec_dryer('production')
+              configure_sanitize_email({:local_environments => ['development']}) # Won't match!
+              SanitizeEmail[:activation_proc].call.should == false
+              mail_delivery
+            end
+            it "should not alter non-sanitized attributes" do
+              @email_message.should have_from('from@example.org')
+              @email_message.should have_reply_to('reply_to@example.org')
+            end
+            it "should use activation_proc for non-matching environment" do
+              @email_message.should have_to("to@example.org")
+              @email_message.should have_cc("cc@example.org")
+              @email_message.should have_bcc("bcc@example.org")
+            end
+          end
+        end
+
+        context ":sanitized_recipients" do
+          before(:each) do
+            sanitize_spec_dryer
+            configure_sanitize_email({:sanitized_recipients => 'barney@sanitize_email.org'})
+            sanitary_mail_delivery
+          end
+          it "should not alter non-sanitized attributes" do
+            @email_message.should have_from('from@example.org')
+            @email_message.should have_reply_to('reply_to@example.org')
+          end
+          it "used as sanitized_to" do
+            @email_message.should have_to("barney@sanitize_email.org")
+          end
+        end
       end
     end
   end
-
 end
 
 #TODO: test good_list

data/spec/spec_helper.rb

@@ -4,80 +4,16 @@ require 'mail'
 require 'rails'
 require 'letter_opener'
 
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true
   config.run_all_when_everything_filtered = true
   #config.filter_run :focus
-end
-
-module EmailMatcherHelpers
-  class UnexpectedMailType < StandardError; end
-
-  # Sweet, nourishing recursion
-  def email_matching(matcher, part, mail_or_part)
-    if mail_or_part.respond_to?(part)
-      # within rspec objects sometimes respond_to all sorts of odd methods they don't really have,
-      # raising an argument error when called
-      # Need to write a failing spec for rspec I think to figure out where this is stemming from
-      begin
-        email_matching(matcher, part, mail_or_part.send(part))
-      rescue ArgumentError
-        if mail_or_part.respond_to?(:=~)
-          mail_or_part =~ Regexp.new(Regexp.escape(matcher))
-        else
-          raise UnexpectedMailType, "Cannot match #{matcher} for #{part}"
-        end
-      end
-    elsif mail_or_part.respond_to?(:join)
-      email_matching(matcher, part, mail_or_part.join(', '))
-    elsif mail_or_part.respond_to?(:=~) # Can we match a regex against it?
-      mail_or_part =~ Regexp.new(Regexp.escape(matcher))
-    else
-      raise UnexpectedMailType, "Cannot match #{matcher} for #{part}"
-    end
-  end
-
-end
 
-RSpec::Matchers.define :have_from do |from|
-  include EmailMatcherHelpers
-  match do |container|
-    #puts "container: #{container}"
-    email_matching(from, :from, container)
-  end
-end
-RSpec::Matchers.define :have_to do |to|
-  include EmailMatcherHelpers
-  match do |container|
-    email_matching(to, :to, container)
-  end
-end
-RSpec::Matchers.define :have_cc do |cc|
-  include EmailMatcherHelpers
-  match do |container|
-    email_matching(cc, :cc, container)
-  end
-end
-# The ActionMailer :file delivery method never prints bcc recipients...
-# Neither does LetterOpener :(
-# But the mail object itself can be tested!
-RSpec::Matchers.define :have_bcc do |bcc|
-  include EmailMatcherHelpers
-  match do |container|
-    email_matching(bcc, :bcc, container)
-  end
-end
-RSpec::Matchers.define :have_subject do |subject|
-  include EmailMatcherHelpers
-  match do |container|
-    email_matching(subject, :subject, container)
-  end
+  config.include SanitizeEmail::EmailMatchers
 end
 
-#RSpec::Matchers.define :have_to_username do |to|
-#  include EmailMatcherHelpers
-#  match do |container|
-#    email_matching(to, :, container)
-#  end
-#end

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: sanitize_email
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc3
-  prerelease: 6
+  version: 1.0.2
+  prerelease: 
 platform: ruby
 authors:
 - Peter Boling
@@ -189,9 +189,9 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.1.0
-description: ! 'In Rails, Sinatra, or any framework using a Mail-like API: Aids in
-  development, testing, qa, and production troubleshooting of email issues without
-  worrying that emails will get sent to actual live addresses.'
+description: ! 'In Rails, Sinatra, or simply the mail gem: Aids in development, testing,
+  qa, and production troubleshooting of email issues without worrying that emails
+  will get sent to actual live addresses.'
 email:
 - peter.boling@gmail.com
 - jtrupiano@gmail.com
@@ -199,6 +199,7 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG
 - LICENSE
 - README.rdoc
 files:
@@ -216,6 +217,7 @@ files:
 - lib/sanitize_email/bleach.rb
 - lib/sanitize_email/config.rb
 - lib/sanitize_email/deprecation.rb
+- lib/sanitize_email/email_matchers.rb
 - lib/sanitize_email/engine.rb
 - lib/sanitize_email/railtie.rb
 - lib/sanitize_email/version.rb
@@ -246,8 +248,8 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: ! 'In Rails, Sinatra, or any framework using a Mail-like API: Test an application''s
-  email abilities without ever sending a message to actual live addresses'
+summary: ! 'Rails/Sinatra/Mail gem: Test email abilities without ever sending a message
+  to actual live addresses'
 test_files:
 - spec/sanitize_email_spec.rb
 - spec/spec_helper.rb