email_spec 0.3.0 → 0.3.1

data/History.txt

@@ -3,14 +3,24 @@
  === New features
  === Bufixes
 
+ == 0.3.1 2009-08-19
+This release is a general refactoring of the steps and helpers.
+The example rails app was also updated to use the lateset rails and webrat.  It also takes advantages
+and the newer step definistions including the new third-person forms.
+
+Some of the generated steps are being removed in favor of some of the newer ones.  The older ones
+will remain until 0.3.5 but will issue deprecation warnings.
+
+Big shoutout to Kieran Pilkington who did the majority of work for this release.
+
  == 0.3.0 2009-08-13
 
  === New features
   * New helper #last_email_address which returns the last address used by email-spec for that scenario. (Ben Mabey)
   * Steps now support third person language. (Kieran P)
-  * "[email] should receive ... " now supports "an" instead of just an integer. (Kieran P)
+  * "[email] should receive ... " now supports "an" instead of just an integer. (Kieran Pilkington)
     With these changes, the following is now possible:
-    
+
       Then "jack@example.com" should receive an email
       When they open the email
       Then they should see "Account has been created" in the subject

data/Rakefile

@@ -14,7 +14,8 @@ begin
     s.bindir       = "bin"
     s.description  = s.summary
     s.require_path = "lib"
-    s.files        = %w(History.txt install.rb MIT-LICENSE.txt README.rdoc Rakefile) + Dir["lib/**/*"] + Dir["rails_generators/**/*"] + Dir["spec/**/*"] + Dir["examples/**/*"]
+    s.files        = %w(History.txt install.rb MIT-LICENSE.txt README.rdoc Rakefile) + Dir["lib/**/*"] + Dir["rails_generators/**/*"]
+    s.test_files   = Dir["spec/**/*"] + Dir["examples/**/*"]
     # rdoc
     s.has_rdoc         = true
     s.extra_rdoc_files = %w(README.rdoc MIT-LICENSE.txt)
@@ -24,6 +25,14 @@ rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
 end
 
+
+begin
+  gem 'fixjour'
+rescue Gem::LoadError
+  puts "Installing fixjour for the example rails app..."
+  puts `gem install fixjour --no-rdoc --no-ri`
+end
+
 begin
   require 'cucumber/rake/task'
   Cucumber::Rake::Task.new(:features)

data/examples/rails_root/app/models/user_mailer.rb

@@ -1,6 +1,5 @@
 class UserMailer < ActionMailer::Base
-  default_url_options[:host] = ''
-
+  default_url_options = {:host => 'example.com'}
   def signup(email, name)
     @recipients  = email
     @from        = "admin@example.com"

data/examples/rails_root/config/boot.rb

@@ -44,6 +44,7 @@ module Rails
     def load_initializer
       require "#{RAILS_ROOT}/vendor/rails/railties/lib/initializer"
       Rails::Initializer.run(:install_gem_spec_stubs)
+      Rails::GemDependency.add_frozen_gem_path
     end
   end
 

data/examples/rails_root/config/environment.rb

@@ -5,7 +5,7 @@
 # ENV['RAILS_ENV'] ||= 'production'
 
 # Specifies gem version of Rails to use when vendor/rails is not present
-RAILS_GEM_VERSION = '2.2.2' unless defined? RAILS_GEM_VERSION
+RAILS_GEM_VERSION = '2.3.3' unless defined? RAILS_GEM_VERSION
 
 # Bootstrap the Rails environment, frameworks, and default configuration
 require File.join(File.dirname(__FILE__), 'boot')
@@ -13,7 +13,7 @@ require File.join(File.dirname(__FILE__), 'boot')
 Rails::Initializer.run do |config|
 
   config.time_zone = 'UTC'
- 
+
   config.action_controller.session = {
     :session_key => '_es_session',
     :secret      => 'b9327c7967925fb36f8901e43f47e0a3e8fc7856ae1b4533ddeda776381548f9ac051721446fdbc4ccc88c7353124708e73d8b0950a30487571d8f8eb5b24732'

data/examples/rails_root/config/environments/test.rb

@@ -20,14 +20,10 @@ config.action_controller.allow_forgery_protection    = false
 # The :test delivery method accumulates sent emails in the
 # ActionMailer::Base.deliveries array.
 config.action_mailer.delivery_method = :test
+config.action_mailer.default_url_options = { :host => "example.com" }
 
-
-# I HATE config.gem.. it doesn't work as advertised...
-config.gem 'webrat', :source => "http://gems.github.com"
-#config.gem 'rspec', :lib => 'spec'
-#config.gem 'rspec-rails', :lib => 'spec/rails'
-config.gem 'cucumber', :source => "http://gems.github.com" # aslakhellesoy-cucumber
-config.gem 'nakajima-fixjour', :lib => 'fixjour', :source => "http://gems.github.com" # nakajima-fixjour
-
-
-
+config.gem 'cucumber',         :lib => false
+config.gem 'webrat',           :lib => false
+config.gem 'rspec',            :lib => false
+config.gem 'rspec-rails',      :lib => 'spec/rails'
+config.gem 'fixjour', :lib => 'fixjour'

data/examples/rails_root/features/errors.feature

@@ -1,42 +1,32 @@
 Feature: Email-spec errors example
-
-In order to help alleviate email testing in apps
-As a email-spec contributor I a newcomer
-Should be able to easily determine where I have gone wrong
-These scenarios should fail with helpful messages
-
-    Scenario: I fail to receive an email
-      Given I am at "/"
-      And no emails have been sent
-      When I fill in "Email" with "example@example.com"
-      And I press "Sign up"
-      And I should receive an email
-      When "example@example.com" opens the email with subject "no email"
-
-    Scenario: I fail to receive an email with the expected link
-      Given I am at "/"
-      And no emails have been sent
-      When I fill in "Email" with "example@example.com"
-      And I press "Sign up"
-      And I should receive an email
-      When I open the email
-      When I follow "link that doesn't exist" in the email
-
-    Scenario: I attempt to operate on an email that is not opened
-      Given I am at "/"
-      And no emails have been sent
-      When I fill in "Email" with "example@example.com"
-      And I press "Sign up"
-      And I should receive an email
-      When I follow "confirm" in the email
-
-    Scenario: I attempt to check out an unopened email
-      Given I am at "/"
-      And no emails have been sent
-      When I fill in "Email" with "example@example.com"
-      And I press "Sign up"
-      Then I should see "confirm" in the email
-      And I should see "Account confirmation" in the subject
-
-
-
+  In order to help alleviate email testing in apps
+  As a email-spec contributor I a newcomer
+  Should be able to easily determine where I have gone wrong
+  These scenarios should fail with helpful messages
+
+  Background:
+    Given I am on the homepage
+    And no emails have been sent
+    When I fill in "Email" with "example@example.com"
+    And I press "Sign up"
+
+  Scenario: I fail to open an email with incorrect subject
+    Then I should receive an email
+    When "example@example.com" opens the email with subject "no email"
+
+  Scenario: I fail to open an email with incorrect text
+    Then I should receive an email
+    When "example@example.com" opens the email with text "no email"
+
+  Scenario: I fail to receive an email with the expected link
+    Then I should receive an email
+    When I open the email
+    When I follow "link that doesn't exist" in the email
+
+  Scenario: I attempt to operate on an email that is not opened
+    Then I should receive an email
+    When I follow "confirm" in the email
+
+  Scenario: I attempt to check out an unopened email
+    Then I should see "confirm" in the email body
+    And I should see "Account confirmation" in the email subject

data/examples/rails_root/features/example.feature

@@ -1,59 +1,62 @@
 Feature: EmailSpec Example -- Prevent Bots from creating accounts
 
-In order to help alleviate email testing in apps
-As an email-spec contributor I want new users of the library
-to easily adopt email-spec in their app by following this example
+  In order to help alleviate email testing in apps
+  As an email-spec contributor I want new users of the library
+  to easily adopt email-spec in their app by following this example
 
-In order to prevent bots from setting up new accounts
-As a site manager I want new users
-to verify their email address with a confirmation link
+  In order to prevent bots from setting up new accounts
+  As a site manager I want new users
+  to verify their email address with a confirmation link
 
-Scenario: A new person signs up imperatively 
-    Given I am a real person wanting to sign up for an account
-    And I am at "/"
+  Background:
+    Given no emails have been sent
+    And I am a real person wanting to sign up for an account
+    And I am on the homepage
+    And I submit my registration information
 
-    When I fill in "Email" with "example@example.com"
-    And I fill in "Name" with "example Jones"
-    And I press "Sign up"
-
-    Then "example@example.com" should receive 1 email
-    And "example@example.com" should have 1 email
-    And "foo@bar.com" should not receive an email
+  Scenario: First person signup (as myself) with two ways of opening email
+    Then I should receive an email
+    And I should have 1 email
 
-    When "example@example.com" opens the email with subject "Account confirmation"
+    # Opening email #1
+    When I open the email
+    Then I should see "Account confirmation" in the email subject
+    And I should see "Joe Someone" in the email body
+    And I should see "confirm" in the email body
 
-    Then I should see "confirm" in the email
-    And I should see "example Jones" in the email
-    And I should see "Account confirmation" in the subject
+    # Opening email #2
+    When I open the email with subject "Account confirmation"
+    Then I should see "Account confirmation" in the email subject
+    And I should see "Joe Someone" in the email body
+    And I should see "confirm" in the email body
 
     When I follow "Click here to confirm your account!" in the email
     Then I should see "Confirm your new account"
 
+    And "foo@bar.com" should have no emails
 
-Scenario: slightly more declarative, but still mostly imperative
-    Given I am a real person wanting to sign up for an account
-    And I'm on the signup page
-
-    When I fill in "Email" with "example@example.com"
-    And I fill in "Name" with "example Jones"
-    And I press "Sign up"
-
-    Then I should receive an email
-
-    When I open the email
-    Then I should see "Account confirmation" in the subject
+  Scenario: Third person signup (emails sent to others) with two ways of opening email
+    Then "foo@bar.com" should have no emails
+    And "example@example.com" should receive an email
+    And "example@example.com" should have 1 email
 
-    When I follow "http:///confirm" in the email
-    Then I should see "Confirm your new account"
+    # Opening email #1
+    When they open the email
+    Then they should see "Account confirmation" in the email subject
+    And they should see "Joe Someone" in the email body
+    And they should see "confirm" in the email body
 
+    # Opening email #2
+    When "example@example.com" opens the email with subject "Account confirmation"
+    Then they should see "Account confirmation" in the email subject
+    And they should see "Joe Someone" in the email body
+    And they should see "confirm" in the email body
 
- Scenario: declarative
-    Given I am a real person wanting to sign up for an account
-    And I'm on the signup page
+    When they follow "Click here to confirm your account!" in the email
+    Then they should see "Confirm your new account"
 
-    When I submit my registration information
+  Scenario: Declarative First Person signup
     Then I should receive an email with a link to a confirmation page
 
-
-
-
+  Scenario: Declarative First Person signup
+    Then they should receive an email with a link to a confirmation page

data/examples/rails_root/features/step_definitions/email_steps.rb

@@ -1,9 +1,10 @@
-#Commonly used email steps
+# Commonly used email steps
 #
 # To add your own steps make a custom_email_steps.rb
 # The provided methods are:
 #
-# reset_mailer 
+# last_email_address
+# reset_mailer
 # open_last_email
 # visit_in_email
 # unread_emails_for
@@ -12,6 +13,16 @@
 # open_email
 # read_emails_for
 # find_email
+#
+# General form for email scenarios are:
+#   - clear the email queue (done automatically by email_spec)
+#   - execute steps that sends an email
+#   - check the user received an/no/[0-9] emails
+#   - open the email
+#   - inspect the email contents
+#   - interact with the email (e.g. click links)
+#
+# The Cucumber steps below are setup in this order.
 
 module EmailHelpers
   def current_email_address
@@ -21,63 +32,88 @@ module EmailHelpers
     last_email_address || "example@example.com"
   end
 end
+
 World(EmailHelpers)
 
-# Use this step to reset the e-mail queue within a scenario.
+#
+# 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|they) open the email$/ do
-  open_email(current_email_address)
-end
+#
+# Check how many emails have been sent/received
+#
 
-When %r{^(?:I|they) follow "([^"]*?)" in the email$} do |link|
-  visit_in_email(link)
+Then /^(?:I|they|"([^"]*?)") should receive (an|no|\d+) emails?$/ do |address, amount|
+  unread_emails_for(address).size.should == parse_email_count(amount)
 end
 
-Then /^(?:I|they) should receive (an|\d+) emails?$/ do |amount|
-  amount = 1 if amount == "an"
-  unread_emails_for(current_email_address).size.should == amount.to_i
+Then /^(?:I|they|"([^"]*?)") should have (an|no|\d+) emails?$/ do |address, amount|
+  mailbox_for(address).size.should == parse_email_count(amount)
 end
 
-Then /^(?:I|they) should not receive any emails?$/ do
-  unread_emails_for(current_email_address).size.should == 0
+# DEPRECATED
+# The following methods are left in for backwards compatibility and
+# should be removed by version 0.3.5.
+Then /^(?:I|they|"([^"]*?)") should not receive an email$/ do |address|
+  email_spec_deprecate "The step 'I/they/[email] should not receive an email' is no longer supported.
+                      Please use 'I/they/[email] should receive no emails' instead."
+  unread_emails_for(address).size.should == 0
 end
 
-Then %r{^"([^"]*?)" should receive (an|\d+) emails?$} do |address, amount|
-  amount = 1 if amount == "an"
-  unread_emails_for(address).size.should == amount.to_i 
+#
+# Accessing emails
+#
+
+# Opens the most recently received email
+When /^(?:I|they|"([^"]*?)") opens? the email$/ do |address|
+  open_email(address)
 end
 
-Then %r{^"([^"]*?)" should have (\d+) emails?$} do |address, n|
-  mailbox_for(address).size.should == n.to_i
+When /^(?:I|they|"([^"]*?)") opens? the email with subject "([^"]*?)"$/ do |address, subject|
+  open_email(address, :with_subject => subject)
 end
 
-Then %r{^"([^"]*?)" should not receive an email$} do |address|
-  find_email(address).should be_nil
+When /^(?:I|they|"([^"]*?)") opens? the email with text "([^"]*?)"$/ do |address, text|
+  open_email(address, :with_text => text)
 end
 
-Then %r{^(?:I|they) should see "([^"]*?)" in the subject$} do |text|
+#
+# Inspect the Email Contents
+#
+
+Then /^(?:I|they) should see "([^"]*?)" in the email subject$/ do |text|
   current_email.should have_subject(Regexp.new(text))
 end
 
-Then %r{^(?:I|they) should see "([^"]*?)" in the email$} do |text|
+Then /^(?:I|they) should see "([^"]*?)" in the email body$/ do |text|
   current_email.body.should =~ Regexp.new(text)
 end
 
-When %r{^"([^"]*?)" opens? the email$} do |address|
-  open_email(address)
+# DEPRECATED
+# The following methods are left in for backwards compatibility and
+# should be removed by version 0.3.5.
+Then /^(?:I|they) should see "([^"]*?)" in the subject$/ do |text|
+  email_spec_deprecate "The step 'I/they should see [text] in the subject' is no longer supported.
+                      Please use 'I/they should see [text] in the email subject' instead."
+  current_email.should have_subject(Regexp.new(text))
 end
-
-When %r{^"([^"]*?)" opens? the email with subject "([^"]*?)"$} do |address, subject|
-  open_email(address, :with_subject => subject)
+Then /^(?:I|they) should see "([^"]*?)" in the email$/ do |text|
+  email_spec_deprecate "The step 'I/they should see [text] in the email' is no longer supported.
+                      Please use 'I/they should see [text] in the email body' instead."
+  current_email.body.should =~ Regexp.new(text)
 end
 
-When %r{^"([^"]*?)" opens? the email with text "([^"]*?)"$} do |address, text|
-  open_email(address, :with_text => text)
+#
+# Interact with Email Contents
+#
+
+When /^(?:I|they) follow "([^"]*?)" in the email$/ do |link|
+  visit_in_email(link)
 end
 
 When /^(?:I|they) click the first link in the email$/ do

data/examples/rails_root/features/step_definitions/user_steps.rb

@@ -3,21 +3,24 @@ Given "I am a real person wanting to sign up for an account" do
 end
 
 When /^I submit my registration information$/ do
-  fill_in "Name", :with => valid_user_attributes[:name]
-  fill_in "Email", :with => valid_user_attributes[:email]
+  fill_in "Name", :with => 'Joe Someone'
+  fill_in "Email", :with => 'example@example.com'
   click_button
 end
 
-Then /^I should receive an email with a link to a confirmation page$/ do
-  unread_emails_for(valid_user_attributes[:email]).size.should == 1 
-  
+Then /^(?:I|they) should receive an email with a link to a confirmation page$/ do
+  unread_emails_for(current_email_address).size.should == 1
+
   # this call will store the email and you can access it with current_email
-  open_last_email_for(valid_user_attributes[:email])
+  open_last_email_for(last_email_address)
   current_email.should have_subject(/Account confirmation/)
-  current_email.should have_body_text(valid_user_attributes[:name])
+  current_email.should have_body_text('Joe Someone')
 
   click_email_link_matching /confirm/
   response.should include_text("Confirm your new account")
-  
 end
 
+# Basically aliases "I should see [text]", but for third person
+Then /^they should see "([^\"]*)"$/ do |text|
+  Then "I should see \"#{text}\""
+end