pluginaweek-has_emails 0.3.0

data/CHANGELOG.rdoc

@@ -0,0 +1,49 @@
+== master
+
+== 0.3.0 / 2009-04-19
+
+* Add compatibility with has_messages 0.4.0 / Rails 2.3
+
+== 0.2.1 / 2009-01-11
+
+* Add compatibility with has_messages 0.3.1 / state_machine 0.5.0
+
+== 0.2.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+
+== 0.1.4 / 2008-10-26
+
+* Add compatibility with has_messages 0.2.0
+* Change how the base module is included to prevent namespacing conflicts
+
+== 0.1.3 / 2008-09-07
+
+* Add compatibility with state_machine 0.3.0
+
+== 0.1.2 / 2008-06-29
+
+* Add compatibility with has_messages 0.1.2
+
+== 0.1.1 / 2008-06-22
+
+* Remove log files from gems
+
+== 0.1.0 / 2008-05-05
+
+* Update to latest has_messages api
+* Simplify by removing support for models other than EmailAddresses in Emails
+* Updated documentation
+
+== 0.0.1 / 2007-09-26
+
+* Refactor has_email_address/has_email_addresses so that new associations for unsent/sent emails isn't created for has_email_address
+* Add state changes fixtures for tests
+* Add tests for ApplicationMailer
+* Add support for tracking the original email address for senders/recipients even if the email address changes on the associated model (i.e. EmailAddress/User/etc.)
+* Support converting models with an email_address/email_addresses association
+* Allow the sender of emails to be an arbitrary string email address
+* Add documentation
+* Move test fixtures out of the test application root directory
+* Convert dos newlines to unix newlines
+* Update against latest changes to has_messages

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2009 Aaron Pfeifer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,96 @@
+= has_emails
+
++has_emails+ demonstrates a reference implementation for sending emails with
+logging and asynchronous support.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/has_emails
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13272-has_emails
+
+Development
+
+* http://github.com/pluginaweek/has_emails
+
+Source
+
+* git://github.com/pluginaweek/has_emails.git
+
+== Description
+
+Emailing between users and other parts of a system is a fairly common feature
+in web applications, especially for those that support social networking.
+Emailing doesn't necessarily need to be between users, but can also act as a
+way for the web application to send notices and other notifications to users.
+
+Rails already provides ActionMailer as a way of sending emails.  However, the
+framework does not provide an easy way to persist emails, track their status,
+and process them asynchronously.  Designing and building a framework that
+supports this can be complex and takes away from the business focus.  This
+plugin can help ease that process by demonstrating a reference implementation
+of these features.
+
+== Usage
+
+=== Creating new emails
+
+Emails should usually still be created using ActionMailer.  However, instead of
+delivering the emails, you can queue the emails like so:
+
+  Notifier.deliver_signup_notification(david) # sends the email now
+  Notifier.queue_signup_notification(david) # sends the email later (has_emails kicks in)
+
+In addition to queueing emails, you can build them directly like so:
+
+  email_address = EmailAddress.find(123)
+  email = email_address.emails.build
+  email.to EmailAddress.find(456)
+  email.subject = 'Hey!'
+  email.body = 'Does anyone want to go out tonight?'
+  email.deliver
+
+=== Replying to emails
+
+  reply = email.reply_to_all
+  reply.body = "I'd love to go out!"
+  reply.deliver
+
+=== Forwarding emails
+
+  forward = email.forward
+  forward.body = 'Interested?'
+  forward.deliver
+
+=== Processing email asynchronously
+
+In addition to delivering emails immediately, you can also *queue* emails so
+that an external application processes and delivers them (as mentioned above).
+This is especially useful when you want to asynchronously send e-mails so that
+it doesn't block the user interface on your web application.
+
+To process queued emails, you need an external cron job that checks and sends
+them like so:
+
+  Email.with_state('queued').each do |email|
+    email.deliver
+  end
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
+
+To run against a specific version of Rails:
+
+  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails
+
+== Dependencies
+
+* Rails 2.3 or later
+* has_messages[http://github.com/pluginaweek/has_messages]
+* state_machine[http://github.com/pluginaweek/state_machine]

data/Rakefile

@@ -0,0 +1,98 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'has_emails'
+  s.version           = '0.3.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Demonstrates a reference implementation for sending emails with logging and asynchronous support in ActiveRecord'
+  s.description       = s.summary
+  
+  s.files             = FileList['{app,db,lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc) - FileList['test/app_root/{log,log/*,script,script/*}']
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  s.add_dependency    'has_messages', '>= 0.4.0'
+  s.add_dependency    'validates_as_email_address', '>= 0.0.2'
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/|app/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb', 'app/**/*.rb')
+end
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem.'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
+end
+
+desc 'Publish the API documentation.'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
+  end
+end

data/app/models/email.rb

@@ -0,0 +1,14 @@
+# Represents an email which has been sent to one or more recipients.  This is
+# essentially the same as the Message class, but changes how the it is
+# delivered.
+class Email < Message
+  state_machine :state do
+    after_transition :on => :deliver, :do => :deliver_email
+  end
+  
+  private
+    # Actually delivers the email to the recipients using ActionMailer
+    def deliver_email
+      ActionMailer::Base.deliver_email(self)
+    end
+end

data/app/models/email_address.rb

@@ -0,0 +1,62 @@
+# Represents a valid RFC822 email address.  See http://www.w3.org/Protocols/rfc822/
+# for more information about the entire specification.
+# 
+# Email addresses are directly associated with emails and, therefore, should be
+# used for building and delivering new e-mails.
+# 
+# == Associations
+# 
+# Email addresses have the following associations defined as a result of using
+# the +has_emails+ macro:
+# * +emails+ - Emails that were composed and are visible to the owner.  Emails
+#   may have been sent or unsent.
+# * +received_emails+ - Emails that have been received from others and are
+#   visible.  Emails may have been read or unread.
+# * +unsent_emails+ - Emails that have not yet been delivered
+# * +sent_emails+ - Emails that have already been delivered
+class EmailAddress < ActiveRecord::Base
+  has_emails
+  
+  validates_presence_of :spec
+  validates_as_email_address :spec
+  validates_uniqueness_of :spec, :scope => 'name'
+  
+  class << self
+    # Finds or create an email address based on the given value
+    def find_or_create_by_address(address)
+      name, spec = split_address(address)
+      find_or_create_by_name_and_spec(name, spec)
+    end
+    
+    # Splits the given address into a name and spec. For example,
+    # 
+    #   EmailAddress.split_address("John Smith <john.smith@gmail.com")  # => ["John Smith", "john.smith@gmail.com"]
+    #   EmailAddress.split_address("john.smith@gmail.com")              # => [nil, "john.smith@gmail.com"]
+    def split_address(address)
+      if match = /^(\S.*)\s+<(.*)>$/.match(address)
+        name = match[1]
+        spec = match[2]
+      else
+        spec = address
+      end
+      
+      return name, spec
+    end
+  end
+  
+  # Sets the value to be used for this email address.  This can come in two formats:
+  # * With name - John Doe <john.doe@gmail.com>
+  # * Without name - john.doe@gmail.com
+  def address=(address)
+    self.name, self.spec = self.class.split_address(address)
+  end
+  
+  # Generates the value for the email address, including the name associated with
+  # it (if provided).  For example,
+  # 
+  #   e = EmailAddress.new(:name => 'John Doe', :spec => 'john.doe@gmail.com')
+  #   e.with_name # => "John Doe <john.doe@gmail.com>"
+  def with_name
+    name.blank? ? spec : "#{name} <#{spec}>"
+  end
+end

data/db/migrate/001_create_email_addresses.rb

@@ -0,0 +1,14 @@
+class CreateEmailAddresses < ActiveRecord::Migration
+  def self.up
+    create_table :email_addresses do |t|
+      t.string :spec, :null => false, :limit => 382
+      t.string :name
+      t.timestamps
+    end
+    add_index :email_addresses, [:spec, :name], :unique => true
+  end
+  
+  def self.down
+    drop_table :email_addresses
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'has_emails'

data/lib/has_emails.rb

@@ -0,0 +1,60 @@
+require 'has_messages'
+require 'validates_as_email_address'
+require 'has_emails/extensions/action_mailer'
+
+# Adds a generic implementation for sending emails
+module HasEmails
+  module MacroMethods
+    # Creates the following email associations:
+    # * +emails+ - Emails that were composed and are visible to the owner.
+    #   Emails may have been sent or unsent.
+    # * +received_emails - Emails that have been received from others and are
+    #   visible.  Emails may have been read or unread.
+    # 
+    # == Creating new emails
+    # 
+    # To create a new email, the +emails+ association should be used.  For
+    # example:
+    # 
+    #   address = EmailAddress.find(123)
+    #   email = user.emails.build
+    #   email.subject = 'Hello'
+    #   email.body = 'How are you?'
+    #   email.to EmailAddress.find(456)
+    #   email.save!
+    #   email.deliver!
+    def has_emails
+      has_many  :emails,
+                  :as => :sender,
+                  :class_name => 'Email',
+                  :conditions => {:hidden_at => nil},
+                  :order => 'messages.created_at ASC'
+      has_many  :received_emails,
+                  :as => :receiver,
+                  :class_name => 'MessageRecipient',
+                  :include => :message,
+                  :conditions => ['message_recipients.hidden_at IS NULL AND messages.state = ?', 'sent'],
+                  :order => 'messages.created_at ASC'
+      
+      include HasEmails::InstanceMethods
+    end
+  end
+  
+  module InstanceMethods
+    # Composed emails that have not yet been sent.  These consists of all
+    # emails that are currently in the "unsent" state.
+    def unsent_emails
+      emails.with_state(:unsent)
+    end
+    
+    # Composed emails that have already been sent.  These consist of all emails
+    # that are currently in the "queued" or "sent states.
+    def sent_emails
+      emails.with_states(:queued, :sent)
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend HasEmails::MacroMethods
+end

data/lib/has_emails/extensions/action_mailer.rb

@@ -0,0 +1,117 @@
+module HasEmails
+  module Extensions #:nodoc:
+    # Adds support for queueing emails so that they can be procssed in the
+    # background.  Emails are stored in the database using the Email ActiveRecord
+    # model.
+    # 
+    # == Queueing mail
+    # 
+    # Once a mailer action and template are defined, you can queue your message
+    # for background processing like so:
+    # 
+    #   Notifier.queue_signup_notification(john_smith) # Queues the email
+    # 
+    # If you were to deliver the mail immediately, the normal process would be
+    # used like so:
+    # 
+    #   Notifier.deliver_signup_notification(john_smith) # Delivers the email
+    module ActionMailer
+      def self.included(base) #:nodoc:
+        base.class_eval do
+          @@default_subject_prefix = "[#{File.basename(File.expand_path(Rails.root)).camelize}] "
+          cattr_accessor :default_subject_prefix
+          
+          # Specify the prefix to use for the subject. This defaults to the
+          # +default_subject_prefix+ specified for ActionMailer::Base.
+          adv_attr_accessor :subject_prefix
+          
+          include HasEmails::Extensions::ActionMailer::InstanceMethods
+          extend HasEmails::Extensions::ActionMailer::ClassMethods
+        end
+      end
+      
+      module ClassMethods
+        def self.extended(base) #:nodoc:
+          class << base
+            alias_method_chain :method_missing, :has_emails
+          end
+        end
+        
+        # Handles calls to queue_*
+        def method_missing_with_has_emails(method_symbol, *parameters)
+          case method_symbol.id2name
+            when /^queue_([_a-z]\w*)/
+              # Queues the mail so that it's processed in the background
+              new($1, *parameters).queue
+            else
+              # Handle the mail delivery as normal
+              method_missing_without_has_emails(method_symbol, *parameters)
+          end
+        end
+      end
+      
+      module InstanceMethods
+        def self.included(base) #:nodoc:
+          base.class_eval do
+            alias_method_chain :initialize_defaults, :subject_prefix
+            alias_method_chain :subject, :prefix
+            alias_method :subject=, :subject_with_prefix
+          end
+        end
+        
+        # Sets or gets the subject of the email.  All subjects are prefixed with a
+        # value indicating the application it is coming from.
+        def subject_with_prefix(*parameters)
+          if parameters.empty?
+            subject_without_prefix
+          else
+            subject_without_prefix(subject_prefix + subject_without_prefix(*parameters))
+          end
+        end
+        
+        # Sets the default subject prefix
+        def initialize_defaults_with_subject_prefix(method_name) #:nodoc
+          initialize_defaults_without_subject_prefix(method_name)
+          @subject_prefix ||= ::ActionMailer::Base.default_subject_prefix.dup
+        end
+        
+        # Delivers an email based on the content in the specified email
+        def email(email)
+          @from       = email.sender.with_name
+          @recipients = email.to.map(&:with_name)
+          @cc         = email.cc.map(&:with_name)
+          @bcc        = email.bcc.map(&:with_name)
+          @subject    = email.subject || ''
+          @body       = email.body || ''
+          @sent_on    = email.updated_at
+        end
+        
+        # Queues the current e-mail that has been constructed
+        def queue
+          Email.transaction do
+            # Create the main email
+            email = EmailAddress.find_or_create_by_address(from).emails.build(
+              :subject => subject,
+              :body => body,
+              :to => email_addresses_for(:recipients),
+              :cc => email_addresses_for(:cc),
+              :bcc => email_addresses_for(:bcc)
+            )
+            email.queue!
+          end
+        end
+        
+        private
+          # Finds or creates all of the email addresses for the given type of
+          # recipient (can be :recipients, :cc, or :bcc)
+          def email_addresses_for(kind)
+            [send(kind)].flatten.collect {|address| EmailAddress.find_or_create_by_address(address)}
+          end
+      end
+    end
+  end
+end
+
+ActionMailer::Base.class_eval do
+  include HasEmails::Extensions::ActionMailer
+end

data/test/app_root/config/environment.rb

@@ -0,0 +1,10 @@
+require 'config/boot'
+
+Rails::Initializer.run do |config|
+  config.plugin_paths << '..'
+  config.plugins = %w(plugin_tracker state_machine has_messages validates_as_email_address has_emails)
+  config.cache_classes = false
+  config.whiny_nils = true
+  config.action_mailer.delivery_method = :test
+  config.action_controller.session = {:key => 'rails_session', :secret => 'd229e4d22437432705ab3985d4d246'}
+end

data/test/app_root/db/migrate/001_migrate_has_messages_to_version_2.rb

@@ -0,0 +1,18 @@
+class MigrateHasMessagesToVersion2 < ActiveRecord::Migration
+  def self.up
+    ActiveRecord::Migrator.new(:up, "#{directory}/db/migrate", 0).migrations.each do |migration|
+      migration.migrate(:up)
+    end
+  end
+  
+  def self.down
+    ActiveRecord::Migrator.new(:up, "#{directory}/db/migrate", 0).migrations.each do |migration|
+      migration.migrate(:down)
+    end
+  end
+  
+  private
+    def self.directory
+      Rails.plugins.find {|plugin| plugin.name == 'has_messages'}.directory
+    end
+end

data/test/app_root/db/migrate/002_migrate_has_emails_to_version_1.rb

@@ -0,0 +1,13 @@
+class MigrateHasEmailsToVersion1 < ActiveRecord::Migration
+  def self.up
+    ActiveRecord::Migrator.new(:up, "#{Rails.root}/../../db/migrate", 0).migrations.each do |migration|
+      migration.migrate(:up)
+    end
+  end
+  
+  def self.down
+    ActiveRecord::Migrator.new(:up, "#{Rails.root}/../../db/migrate", 0).migrations.each do |migration|
+      migration.migrate(:down)
+    end
+  end
+end

data/test/app_root/vendor/plugins/plugin_tracker/init.rb

@@ -0,0 +1,5 @@
+class << Rails
+  attr_accessor :plugins
+end
+
+Rails.plugins = initializer.loaded_plugins

data/test/factory.rb

@@ -0,0 +1,58 @@
+module Factory
+  # Build actions for the model
+  def self.build(model, &block)
+    name = model.to_s.underscore
+    
+    define_method("#{name}_attributes", block)
+    define_method("valid_#{name}_attributes") {|*args| valid_attributes_for(model, *args)}
+    define_method("new_#{name}")              {|*args| new_record(model, *args)}
+    define_method("create_#{name}")           {|*args| create_record(model, *args)}
+  end
+  
+  # Get valid attributes for the model
+  def valid_attributes_for(model, attributes = {})
+    name = model.to_s.underscore
+    send("#{name}_attributes", attributes)
+    attributes.stringify_keys!
+    attributes
+  end
+  
+  # Build an unsaved record
+  def new_record(model, *args)
+    attributes = valid_attributes_for(model, *args)
+    record = model.new(attributes)
+    attributes.each {|attr, value| record.send("#{attr}=", value) if model.accessible_attributes && !model.accessible_attributes.include?(attr) || model.protected_attributes && model.protected_attributes.include?(attr)}
+    record
+  end
+  
+  # Build and save/reload a record
+  def create_record(model, *args)
+    record = new_record(model, *args)
+    record.save!
+    record.reload
+    record
+  end
+  
+  build Email do |attributes|
+    attributes[:sender] = create_user unless attributes.include?(:sender)
+    attributes.reverse_merge!(
+      :subject => 'New features',
+      :body => 'Lots of new things to talk about... come to the meeting tonight to find out!'
+    )
+  end
+  
+  build EmailAddress do |attributes|
+    attributes.reverse_merge!(
+      :name => 'John Smith',
+      :spec => 'john.smith@gmail.com'
+    )
+  end
+  
+  build MessageRecipient do |attributes|
+    attributes[:message] = create_message unless attributes.include?(:message)
+    attributes[:receiver] = create_user(:login => 'me') unless attributes.include?(:receiver)
+    attributes.reverse_merge!(
+      :kind => 'to'
+    )
+  end
+end

data/test/functional/has_emails_test.rb

@@ -0,0 +1,139 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+class EmailAddressByDefaultFunctionalTest < ActiveSupport::TestCase
+  def setup
+    @email_address = create_email_address
+  end
+  
+  def test_should_not_have_any_emails
+    assert @email_address.emails.empty?
+  end
+  
+  def test_should_not_have_any_unsent_emails
+    assert @email_address.unsent_emails.empty?
+  end
+  
+  def test_should_not_have_any_sent_emails
+    assert @email_address.sent_emails.empty?
+  end
+  
+  def test_should_not_have_any_received_emails
+    assert @email_address.received_emails.empty?
+  end
+end
+
+class EmailAddressFunctionalTest < ActiveSupport::TestCase
+  def setup
+    @email_address = create_email_address
+  end
+  
+  def test_should_be_able_to_create_new_emails
+    email = @email_address.emails.build
+    assert_instance_of Email, email
+    assert_equal @email_address, email.sender
+  end
+  
+  def test_should_be_able_to_send_new_emails
+    email = @email_address.emails.build
+    email.to create_email_address(:spec => 'jane.smith@gmail.com')
+    assert email.deliver
+  end
+end
+
+class EmailAddressWithUnsentEmails < ActiveSupport::TestCase
+  def setup
+    @email_address = create_email_address
+    @sent_email = create_email(:sender => @email_address, :to => create_email_address(:spec => 'jane.smith@gmail.com'))
+    @sent_email.deliver
+    @first_draft = create_email(:sender => @email_address)
+    @second_draft = create_email(:sender => @email_address)
+  end
+  
+  def test_should_have_unsent_emails
+    assert_equal [@first_draft, @second_draft], @email_address.unsent_emails
+  end
+  
+  def test_should_include_unsent_emails_in_emails
+    assert_equal [@sent_email, @first_draft, @second_draft], @email_address.emails
+  end
+end
+
+class EmailAddressWithSentEmails < ActiveSupport::TestCase
+  def setup
+    @email_address = create_email_address
+    @to = create_email_address(:spec => 'jane.smith@gmail.com')
+    @draft = create_email(:sender => @email_address)
+    
+    @first_sent_email = create_email(:sender => @email_address, :to => @to)
+    @first_sent_email.deliver
+    
+    @second_sent_email = create_email(:sender => @email_address, :to => @to)
+    @second_sent_email.deliver
+  end
+  
+  def test_should_have_sent_emails
+    assert_equal [@first_sent_email, @second_sent_email], @email_address.sent_emails
+  end
+  
+  def test_should_include_sent_emails_in_emails
+    assert_equal [@draft, @first_sent_email, @second_sent_email], @email_address.emails
+  end
+end
+
+class EmailAddressWithReceivedEmails < ActiveSupport::TestCase
+  def setup
+    @sender = create_email_address
+    @email_address = create_email_address(:spec => 'jane.smith@gmail.com')
+    
+    @unsent_email = create_email(:sender => @sender, :to => @email_address)
+    
+    @first_sent_email = create_email(:sender => @sender, :to => @email_address)
+    @first_sent_email.deliver
+    
+    @second_sent_email = create_email(:sender => @sender, :to => @email_address)
+    @second_sent_email.deliver
+  end
+  
+  def test_should_have_received_emails
+    assert_equal [@first_sent_email, @second_sent_email], @email_address.received_emails.map(&:message)
+  end
+end
+
+class EmailAddressWithHiddenEmailsTest < ActiveSupport::TestCase
+  def setup
+    @email_address = create_email_address
+    @friend = create_email_address(:spec => 'jane.smith@gmail.com')
+    
+    hidden_unsent_email = create_email(:sender => @email_address)
+    hidden_unsent_email.hide
+    @unsent_email = create_email(:sender => @email_address)
+    
+    hidden_sent_email = create_email(:sender => @email_address, :to => @friend)
+    hidden_sent_email.deliver
+    hidden_sent_email.hide
+    @sent_email = create_email(:sender => @email_address, :to => @friend)
+    @sent_email.deliver
+    
+    hidden_received_email = create_email(:sender => @friend, :to => @email_address)
+    hidden_received_email.deliver
+    hidden_received_email.recipients.first.hide
+    @received_email = create_email(:sender => @friend, :to => @email_address)
+    @received_email.deliver
+  end
+  
+  def test_should_not_include_hidden_emails_in_emails
+    assert_equal [@unsent_email, @sent_email], @email_address.emails
+  end
+  
+  def test_should_not_include_hidden_emails_in_unsent_emails
+    assert_equal [@unsent_email], @email_address.unsent_emails
+  end
+  
+  def test_should_not_include_hidden_emails_in_sent_emails
+    assert_equal [@sent_email], @email_address.sent_emails
+  end
+  
+  def test_should_not_include_hidden_emails_in_received_emails
+    assert_equal [@received_email], @email_address.received_emails.map(&:message)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+# Load the plugin testing framework
+$:.unshift("#{File.dirname(__FILE__)}/../../plugin_test_helper/lib")
+require 'rubygems'
+require 'plugin_test_helper'
+
+# Run the migrations
+ActiveRecord::Migrator.migrate("#{Rails.root}/db/migrate")
+
+# Mixin the factory helper
+require File.expand_path("#{File.dirname(__FILE__)}/factory")
+Test::Unit::TestCase.class_eval do
+  include Factory
+end

data/test/unit/action_mailer_test.rb

@@ -0,0 +1,53 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+class TestMailer < ActionMailer::Base
+  def signed_up(recipient)
+    subject    'Thanks for signing up'
+    from       'MyWebApp <welcome@mywebapp.com>'
+    recipients recipient
+    cc         'Nobody <nobody@mywebapp.com>'
+    bcc        'root@mywebapp.com'
+    body       'Congratulations!'
+  end
+end
+
+class TestMailerTest < ActionMailer::TestCase
+  def test_should_use_camelized_application_name_for_default_subject_prefix
+    assert_equal '[AppRoot] ', ActionMailer::Base.default_subject_prefix
+  end
+  
+  def test_should_queue_email
+    assert_nothing_raised {TestMailer.queue_signed_up('john.smith@gmail.com')}
+    assert_equal 1, Email.count
+    
+    email = Email.find(1)
+    assert_equal '[AppRoot] Thanks for signing up', email.subject
+    assert_equal 'Congratulations!', email.body
+    assert_equal 'MyWebApp <welcome@mywebapp.com>', email.sender.with_name
+    assert_equal ['john.smith@gmail.com'], email.to.map(&:with_name)
+    assert_equal ['Nobody <nobody@mywebapp.com>'], email.cc.map(&:with_name)
+    assert_equal ['root@mywebapp.com'], email.bcc.map(&:with_name)
+  end
+  
+  def test_should_deliver_email
+    email = create_email(
+      :subject => 'Hello',
+      :body => 'How are you?',
+      :sender => create_email_address(:name => 'MyWebApp', :spec => 'welcome@mywebapp.com'),
+      :to => create_email_address(:spec => 'john.smith@gmail.com'),
+      :cc => create_email_address(:name => 'Nobody', :spec => 'nobody@mywebapp.com'),
+      :bcc => create_email_address(:spec => 'root@mywebapp.com')
+    )
+    
+    assert_nothing_raised {ActionMailer::Base.deliver_email(email)}
+    assert_equal 1, ActionMailer::Base.deliveries.size
+    
+    delivery = ActionMailer::Base.deliveries.first
+    assert_equal 'Hello', delivery.subject
+    assert_equal 'How are you?', delivery.body
+    assert_equal ['welcome@mywebapp.com'], delivery.from
+    assert_equal ['john.smith@gmail.com'], delivery.to
+    assert_equal ['nobody@mywebapp.com'], delivery.cc
+    assert_equal ['root@mywebapp.com'], delivery.bcc
+  end
+end

data/test/unit/email_address_test.rb

@@ -0,0 +1,160 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+class EmailAddressByDefaultTest < ActiveSupport::TestCase
+  def setup
+    @email_address = EmailAddress.new
+  end
+  
+  def test_should_not_have_a_name
+    assert @email_address.name.blank?
+  end
+  
+  def test_should_not_have_a_spec
+    assert @email_address.name.blank?
+  end
+end
+
+class EmailAddressTest < ActiveSupport::TestCase
+  def test_should_be_valid_with_a_set_of_valid_attributes
+    email_address = new_email_address
+    assert email_address.valid?
+  end
+  
+  def test_should_require_a_spec
+    email_address = new_email_address(:spec => nil)
+    assert !email_address.valid?
+    assert email_address.errors.invalid?(:spec)
+  end
+  
+  def test_should_require_a_properly_formatted_email
+    email_address = new_email_address(:spec => '!@@!@@!')
+    assert !email_address.valid?
+    assert email_address.errors.invalid?(:spec)
+  end
+  
+  def test_should_not_allow_emails_less_than_3_characters
+    email_address = new_email_address(:spec => 'aa')
+    assert !email_address.valid?
+    assert email_address.errors.invalid?(:spec)
+    
+    email_address.spec = 'a@a'
+    assert email_address.valid?
+  end
+  
+  def test_should_not_allow_emails_longer_than_320_characters
+    email_address = new_email_address(:spec => 'a' * 314 + '@a.com')
+    assert email_address.valid?
+    
+    email_address.spec += 'a'
+    assert !email_address.valid?
+    assert email_address.errors.invalid?(:spec)
+  end
+  
+  def test_should_require_a_unique_spec_scoped_by_name
+    email_address = create_email_address(:spec => 'john.smith@gmail.com', :name => 'John Smith')
+    
+    second_email_address = new_email_address(:spec => 'john.smith@gmail.com', :name => 'John Smith II')
+    assert second_email_address.valid?
+    
+    second_email_address = new_email_address(:spec => 'john.smith@gmail.com', :name => 'John Smith')
+    assert !second_email_address.valid?
+    assert second_email_address.errors.invalid?(:spec)
+  end
+  
+  def test_should_not_require_a_name
+    email_address = new_email_address(:name => nil)
+    assert email_address.valid?
+  end
+  
+  def test_should_protect_attributes_from_mass_assignment
+    email_address = EmailAddress.new(
+      :id => 1,
+      :name => 'John Smith',
+      :spec => 'john.smith@gmail.com'
+    )
+    
+    assert_nil email_address.id
+    assert_equal 'John Smith', email_address.name
+    assert_equal 'john.smith@gmail.com', email_address.spec
+  end
+end
+
+class EmailAddressFromAddressTest < ActiveSupport::TestCase
+  def setup
+    @email_address = EmailAddress.new(:address => 'John Smith <john.smith@gmail.com>')
+  end
+  
+  def test_should_be_valid
+    assert @email_address.valid?
+  end
+  
+  def test_should_find_a_name
+    assert_equal 'John Smith', @email_address.name
+  end
+  
+  def test_should_find_a_spec
+    assert_equal 'john.smith@gmail.com', @email_address.spec
+  end
+end
+
+class EmailAddressFromAddressWithoutNameTest < ActiveSupport::TestCase
+  def setup
+    @email_address = EmailAddress.new(:address => 'john.smith@gmail.com')
+  end
+  
+  def test_should_be_valid
+    assert @email_address.valid?
+  end
+  
+  def test_should_not_find_a_name
+    assert @email_address.name.blank?
+  end
+  
+  def test_should_find_a_spec
+    assert_equal 'john.smith@gmail.com', @email_address.spec
+  end
+end
+
+class EmailAddressAfterBeingCreatedTest < ActiveSupport::TestCase
+  def setup
+    @email_address = create_email_address(:name => 'John Smith', :spec => 'john.smith@gmail.com')
+  end
+  
+  def test_should_record_when_it_was_created
+    assert_not_nil @email_address.created_at
+  end
+  
+  def test_should_record_when_it_was_updated
+    assert_not_nil @email_address.updated_at
+  end
+  
+  def test_should_generate_an_address_with_the_name
+    assert_equal 'John Smith <john.smith@gmail.com>', @email_address.with_name
+  end
+end
+
+class EmailAddressAsAClassTest < ActiveSupport::TestCase
+  def test_should_be_able_to_split_address_containing_name
+    name, spec = EmailAddress.split_address('John Smith <john.smith@gmail.com>')
+    assert_equal 'John Smith', name
+    assert_equal 'john.smith@gmail.com', spec
+  end
+  
+  def test_should_be_able_to_split_address_not_containing_name
+    name, spec = EmailAddress.split_address('john.smith@gmail.com')
+    assert_nil name
+    assert_equal 'john.smith@gmail.com', spec
+  end
+  
+  def test_should_be_able_to_find_an_existing_email_by_address
+    email_address = create_email_address(:address => 'John Smith <john.smith@gmail.com>')
+    assert_equal email_address, EmailAddress.find_or_create_by_address('John Smith <john.smith@gmail.com>')
+  end
+  
+  def test_should_be_able_to_create_from_a_new_address
+    email_address = EmailAddress.find_or_create_by_address('John Smith <john.smith@gmail.com>')
+    assert !email_address.new_record?
+    assert_equal 'John Smith', email_address.name
+    assert_equal 'john.smith@gmail.com', email_address.spec
+  end
+end

data/test/unit/email_test.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+class EmailAfterBeingDeliveredTest < ActiveSupport::TestCase
+  def setup
+    ActionMailer::Base.deliveries = []
+    
+    @email = new_email(
+      :subject => 'Hello',
+      :body => 'How are you?',
+      :sender => create_email_address(:spec => 'webmaster@localhost'),
+      :to => create_email_address(:spec => 'partners@localhost'),
+      :cc => create_email_address(:spec => 'support@localhost'),
+      :bcc => create_email_address(:spec => 'feedback@localhost')
+    )
+    assert @email.deliver
+  end
+  
+  def test_should_send_mail
+    assert ActionMailer::Base.deliveries.any?
+    
+    delivery = ActionMailer::Base.deliveries.first
+    assert_equal 'Hello', delivery.subject
+    assert_equal 'How are you?', delivery.body
+    assert_equal ['webmaster@localhost'], delivery.from
+    assert_equal ['partners@localhost'], delivery.to
+    assert_equal ['support@localhost'], delivery.cc
+    assert_equal ['feedback@localhost'], delivery.bcc
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification 
+name: pluginaweek-has_emails
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Aaron Pfeifer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-08 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: has_messages
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: validates_as_email_address
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.2
+    version: 
+description: Demonstrates a reference implementation for sending emails with logging and asynchronous support in ActiveRecord
+email: aaron@pluginaweek.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- app/models
+- app/models/email_address.rb
+- app/models/email.rb
+- db/migrate
+- db/migrate/001_create_email_addresses.rb
+- lib/has_emails.rb
+- lib/has_emails
+- lib/has_emails/extensions
+- lib/has_emails/extensions/action_mailer.rb
+- test/unit
+- test/unit/email_address_test.rb
+- test/unit/email_test.rb
+- test/unit/action_mailer_test.rb
+- test/factory.rb
+- test/app_root
+- test/app_root/vendor
+- test/app_root/vendor/plugins
+- test/app_root/vendor/plugins/plugin_tracker
+- test/app_root/vendor/plugins/plugin_tracker/init.rb
+- test/app_root/db
+- test/app_root/db/migrate
+- test/app_root/db/migrate/002_migrate_has_emails_to_version_1.rb
+- test/app_root/db/migrate/001_migrate_has_messages_to_version_2.rb
+- test/app_root/config
+- test/app_root/config/environment.rb
+- test/test_helper.rb
+- test/functional
+- test/functional/has_emails_test.rb
+- CHANGELOG.rdoc
+- init.rb
+- LICENSE
+- Rakefile
+- README.rdoc
+has_rdoc: true
+homepage: http://www.pluginaweek.org
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: pluginaweek
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Demonstrates a reference implementation for sending emails with logging and asynchronous support in ActiveRecord
+test_files: 
+- test/unit/email_address_test.rb
+- test/unit/email_test.rb
+- test/unit/action_mailer_test.rb
+- test/functional/has_emails_test.rb