newman 0.1.1 → 0.2.0

data/lib/newman/settings.rb

@@ -1,9 +1,60 @@
+# `Newman::Settings` provides the base functionality that is used by Newman's
+# configuration files. It is currently a thin wrapper on top of Ruby's
+# `OpenStruct` construct, but will later add some domain specific validations
+# and transformations for the various configuration options it supports.
+#
+# Unless you need to customize the way that Newman's configuration system
+# works or make changes to your settings objects at runtime, you probably don't
+# need to worry about how this object is implemented. Both
+# `Newman::Server.simple` and `Newman::Server.test_mode` create a
+# `Newman::Settings` object for you automatically, and you will typically be
+# tweaking a sample settings file rather than crafting one from scratch.
+#
+# `Newman::Settings`is part of Newman's **internal API**, but 
+# the setting file format and various settings that Newman depends
+# on should be considered part of the **external API**.
+
 module Newman 
   class Settings
+
+    # ---
+    
+    # The `Newman::Settings.from_file` method is used to create
+    # a new `Newman::Settings` object and populate it with the data 
+    # contained in a settings file, i.e.
+    #
+    #     settings = Newman::Settings.from_file('config/environment.rb')
+    # 
+    # This method is purely syntactic sugar, and is functionally equivalent to
+    # the following code:
+    #
+    #     settings = Newman::Settings.new
+    #     settings.load_config('config/environment.rb')
+    #
+    # Because there currently is little advantage to explicitly instantiating a
+    # blank `Newman::Settings` object, this method is the preferred way of doing
+    # things.
+    # 
     def self.from_file(filename)
       new.tap { |o| o.load_config(filename) }
     end
-  
+
+    # ---
+     
+    # A `Newman::Settings` object is a blank slate upon creation. It simply
+    # assigns an empty `OpenStruct` object for each type of settings data it 
+    # supports.     
+    # 
+    # In most situations, you will not instantiate a `Newman::Settings` object
+    # directly but instead will make use of a configuration file and the
+    # `Newman::Settings.from_file` method. Newman provides sample configuration
+    # files in its `examples/` and `test/` directories, and applications should do the
+    # same. This will help users discover what fields can be set.
+    #
+    # We are aware of the fact that the current configuration system is way too
+    # flexible and a breeding ground for subtle bugs. This will be fixed in a
+    # future version of Newman.
+
     def initialize
       self.imap        = OpenStruct.new
       self.smtp        = OpenStruct.new
@@ -11,11 +62,28 @@ module Newman
       self.application = OpenStruct.new
     end
 
-    def load_config(filename)
-      eval(File.read(filename), binding)
-    end
+    # ---
 
+    # The `imap` and `smtp` fields are used by `Newman::Mailer`, 
+    # the `service` field is used throughout Newman (particularly in
+    # `Newman::Server`), and the `application` field is reserved for
+    # application-specific configurations.
 
     attr_accessor :imap, :smtp, :service, :application
+
+
+    # ---
+
+    # `Newman::Settings#load_config` is used for evaluating
+    # the contents of a file within the context of a `Newman::Settings`
+    # instance. 
+    #
+    # In practice, this method is typically called by
+    # `Newman::Settings#from_file`, but can also be used to apply 
+    # multiple settings files to a single `Newman::Settings` object
+
+    def load_config(filename)
+      eval(File.read(filename), binding)
+    end
   end
 end

data/lib/newman/store.rb

@@ -1,7 +1,34 @@
-require_relative "store/recorder"
+# `Newman::Store` is a minimal persistence layer for storing non-relational
+# data. It is meant to make the task of building small applications with simple
+# data storage needs easier.
+#
+# For an example of how `Newman::Store` can be used in your applications, you
+# can take a look at how `Newman::MailingList` is implemented. A similar
+# approach could be used to develop arbitrary persistent models.
+#
+# `Newman::Store` is part of Newman's **external interface**.
 
 module Newman
   class Store 
+
+    # ---
+
+    # To initialize a `Newman::Store` object, a `filename` string must 
+    # be provided, i.e.
+    #
+    #     store = Newman::Store.new("simple.store")
+    #
+    # This filename will be used to initialize a `PStore` object after first
+    # running `FileUtils.mkdir_p` to create any directories within the path to
+    # the filename if they do not already exist. Once that `PStore` object is
+    # created, two root keys will be mapped to empty Hash objects if they 
+    # are not set already: `:indentifers` and `:columns`.
+    #
+    # While it's okay to treat the `PStore` object as an implementation detail,
+    # we will treat our interactions with it as part of Newman's **external
+    # interface**, so that we are more conservative about making backwards
+    # incompatible changes to the databases created by `Newman::Store`.
+
     def initialize(filename)
       FileUtils.mkdir_p(File.dirname(filename))
 
@@ -13,22 +40,59 @@ module Newman
       end
     end
 
-    attr_reader :identifiers
+    # ---
+    
+    # `Newman::Store#[]` is syntactic sugar for initializing a
+    # `Newman::Recorder` object, and is meant to be used for
+    # accessing and manipulating column data by `column_key`, i.e.
+    #
+    #     store[:subscriptions].create("gregory.t.brown@gmail.com")
+    #
+    # This method is functionally equivalent to the following code:
+    #
+    #     recorder = Newman::Recorder.new(:subscriptions, store)
+    #     recorder.create("gregory.t.brown@gmail.com")
+    #
+    # For aesthetic reasons and for forward compatibility, it is
+    # preferable to use `Newman::Store#[]` rather than instantiating
+    # a `Newman::Recorder` object directly. 
 
-    def [](column)
-      Recorder.new(column, self) 
+    def [](column_key)
+      Recorder.new(column_key, self) 
     end
 
+    # ---
+    
+    # `Newman::Store#read` initiates a read only transaction and then yields
+    # the underlying `PStore` object stored in the `data` field.
+
     def read
       data.transaction(:read_only) { yield(data) }
     end
 
+    # ---
+    
+    # `Newman::Store#read` initiates a read/write transaction and then yields
+    # the underlying `PStore` object stored in the `data` field.
+
     def write
       data.transaction { yield(data) }
     end
 
+    # ---
+
+    # **NOTE: Methods below this point in the file are implementation 
+    # details, and should not be depended upon**
+    
     private
 
+    # ---
+    
+    # The `data` accessor is kept private because a `Newman::Store` object is
+    # meant to wrap a single `PStore` object once created, and because we want
+    # to force every interaction with a `Newman::Store` to be transactional in
+    # nature. 
+
     attr_accessor :data
   end
 end

data/lib/newman/test_mailer.rb

@@ -1,14 +1,74 @@
+# `Newman::TestMailer` is a drop-in replacement for `Newman::Mailer` meant for
+# use in automated testing. It is a thin wrapper on top of the built in testing
+# functionality provided by the mail gem.
+#
+# `Newman::TestMailer` may be a useful tool for Newman application developers,
+# at some point but is a bit tricky to work with due to the fact that it 
+# relies on global state. This is a known issue and will hopefully be solved in
+# a future version of Newman.
+#
+# `Newman::TestMailer` is part of Newman's **internal interface**, but may
+# become part of the **external interface** if we can make it less brittle.
+# Patches are welcome!
+
 module Newman
-  TestMailer = Object.new
+  class TestMailer
+    # ---
+      
+    # To initialize a `Newman::TestMailer` object, a settings object must be
+    # provided, i.e.
+    #
+    #     settings = Newman::Settings.from_file('config/environment.rb')
+    #     mailer   = Newman::TestMailer.new(settings)
+    #
+    # However, there are handful of caveats worth knowing about this
+    # constructing an instance of this particular object.
+    #
+    # 1) Most unit tests won't need a `Newman::TestMailer` object present, and most
+    # integration tests can make use of `Newman::Server.test_mode`, preventing
+    # the need to ever explicitly instantiate a `Newman::TestMailer` object.
+    #
+    # 2) Because there isn't an obvious way to work with test objects in the
+    # underlying mail gem without relying on global state,
+    # `Newman::TestMailer` actually implements the singleton pattern and
+    # returns references to a single instance rather than creating new
+    # instances. The constructor interface is simply preserved so that it
+    # can be a drop-in replacement for a `Newman::Mailer` object.
+    #  
+    # 3) The settings object is not actually used, and is only part of the
+    # signature for API compatibility reasons.
+    #
+    # With these caveats in mind, be sure to think long and hard about whether
+    # you actually need to explicitly build instances of this object before
+    # doing so :)
+
+    class << self
+      def new(settings)
+        return self.instance if instance
+
+        Mail.defaults do
+          retriever_method :test
+          delivery_method  :test      
+        end
 
-  class << TestMailer
-    def configure(settings)
-      Mail.defaults do
-        retriever_method :test
-        delivery_method  :test      
+        self.instance = allocate
       end
+
+      attr_accessor :instance
     end
 
+    # ---
+
+    # `Newman::TestMailer#messages` is used to retrieve all messages currently in the inbox
+    # and then delete them from the underlying `Mail::TestMailer` object so that
+    # the inbox gets cleared. This method returns an array of
+    # `Mail::Message` objects if any messages were found, and returns
+    # an empty array otherwise.
+    #
+    # Keep in mind that because only a single `Newman::TestMailer` ever gets
+    # instantiated no matter how many times you call `Newman::TestMailer.new`,
+    # you only get one test inbox per process.
+
     def messages
       msgs = Marshal.load(Marshal.dump(Mail::TestMailer.deliveries))
       Mail::TestMailer.deliveries.clear
@@ -16,10 +76,23 @@ module Newman
       msgs
     end
 
+    # ---
+    
+    # `Newman::TestMailer#new_message` is used to construct a new `Mail::Message` object,
+    # with the delivery settings set to test mode. 
+    # This method passes all its arguments on to `Mail.new`, so be sure 
+    # to refer to the [mail gem's documentation](http://github.com/mikel/mail)
+    # for details.
+
     def new_message(*a, &b)
       Mail.new(*a, &b)
     end
 
+    # ---
+
+    # `Newman::TestMailer#deliver_message` method is used to construct and immediately deliver a
+    # message with the delivery settings set to test mode.
+
     def deliver_message(*a, &b)
       new_message(*a, &b).deliver
     end

data/lib/newman/version.rb

@@ -1,8 +1,11 @@
+# Newman::Version is used to determine which version of Newman is currently
+# running and is part of Newman's **external api**.
+
 module Newman
   module Version
     MAJOR  = 0
-    MINOR  = 1
-    TINY   = 1
+    MINOR  = 2
+    TINY   = 0
     STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
   end
 end

data/test/helper.rb

@@ -0,0 +1,18 @@
+gem "minitest" 
+
+require "minitest/autorun"
+require "purdytest"
+require_relative "../lib/newman"
+
+module Newman
+  TEST_DIR   =  File.dirname(__FILE__) 
+
+  def self.new_test_server(app)
+    server = Newman::Server.test_mode(TEST_DIR + "/settings.rb")
+    server.apps << app
+    server.settings.application.simplelist_db = TEST_DIR + "/test.store"
+    server.settings.service.templates_dir = TEST_DIR + "/../examples/views"
+
+    server
+  end
+end

data/{examples → test/integration}/acid_tests.rb

@@ -1,39 +1,42 @@
-require_relative "ping_pong"
-require_relative "simple_mailing_list"
+require_relative "../helper"
 
-require "minitest/autorun"
-
-server = Newman::Server
-server.test_mode("config/test.rb")
-
-mailer = server.mailer
+require_relative "../../examples/ping_pong"
+require_relative "../../examples/simple_mailing_list"
 
 describe "Ping Pong" do
+  let(:server) { Newman.new_test_server(Newman::Examples::PingPong) }
+  let(:mailer) { server.mailer }
+
   it "responds to an email sent to test+ping@test.com" do
     mailer.deliver_message(:to => "test+ping@test.com")
-    server.tick(Newman::Examples::PingPong)
+    server.tick
     mailer.messages.first.subject.must_equal("pong")
   end
 
   it "responds to an email sent to test+bad@test.com" do
     mailer.deliver_message(:to => "test+bad@test.com")
-    server.tick(Newman::Examples::PingPong)
+    server.tick
     mailer.messages.first.subject.must_equal("unknown command")
   end
 end
 
 describe "SimpleList" do
+  let(:server) { Newman.new_test_server(Newman::Examples::SimpleList) }
+  let(:mailer) { server.mailer }
+
   it "emulates a simple mailing list" do
-    mailer.deliver_message(:from => "tester@test.com",
-                           :to   => "test@test.com")
+    mailer.deliver_message(:from    => "tester@test.com",
+                           :to      => "test@test.com")
+
+    server.tick
 
-    server.tick(Newman::Examples::SimpleList)
     mailer.messages.first.subject.must_equal("You are not subscribed")
 
-    mailer.deliver_message(:from => "tester@test.com",
-                           :to   => "test+subscribe@test.com")
+    mailer.deliver_message(:from    => "tester@test.com",
+                           :to      => "test+subscribe@test.com",
+                           :subject => "subscribe")
 
-    server.tick(Newman::Examples::SimpleList)
+    server.tick
     mailer.messages.first.subject.must_equal("SUBSCRIBED!")
 
 
@@ -41,13 +44,14 @@ describe "SimpleList" do
                            :to      => "test@test.com",
                            :subject => "WIN!")
 
-    server.tick(Newman::Examples::SimpleList)
+    server.tick
     mailer.messages.first.subject.must_equal("WIN!")
 
-    mailer.deliver_message(:from => "tester@test.com",
-                           :to   => "test+unsubscribe@test.com")
+    mailer.deliver_message(:from    => "tester@test.com",
+                           :to      => "test@test.com",
+                           :subject => "unsubscribe")
 
-    server.tick(Newman::Examples::SimpleList)
+    server.tick
     mailer.messages.first.subject.must_equal("UNSUBSCRIBED!")
   end
 
@@ -57,3 +61,9 @@ describe "SimpleList" do
     end
   end
 end
+
+
+# move this when test suite set up
+
+
+

data/test/integration/skip_response_test.rb

@@ -0,0 +1,22 @@
+require_relative "../helper"
+
+describe "Server handling request without responding" do
+
+  let(:noop) do
+    Newman::Application.new do
+      default do
+        skip_response
+      end
+    end
+  end
+
+  let(:server) { Newman.new_test_server(noop) }
+  let(:mailer) { server.mailer }
+  
+  it "should not deliver message" do
+    mailer.deliver_message(:from => 'tester@test.com',
+                           :to   => 'test+noop@test.com')
+    server.tick
+    assert_empty mailer.messages
+  end
+end

data/test/integration/subject_filter_test.rb

@@ -0,0 +1,25 @@
+require_relative "../helper"
+
+describe "subject filter" do
+  let(:app) do
+    Newman::Application.new do
+      subject :match, "hello" do
+        respond(:subject => "HELLOOOOOOOO!")
+      end
+
+      default do
+        respond(:subject => "No subject, no greeting")
+      end
+    end
+  end
+
+  let(:server) { Newman.new_test_server(app) }
+  let(:mailer) { server.mailer }
+
+  it "should automatically not match emails without subjects" do
+    mailer.deliver_message(:to => "test@test.com")
+    server.tick
+
+    mailer.messages.first.subject.must_equal("No subject, no greeting")
+  end
+end